From 8c07f36b480226a988c24f60d4130c8a2b5922ab Mon Sep 17 00:00:00 2001 From: Yann Hodique Date: Sat, 18 Sep 2010 10:29:50 +0200 Subject: [PATCH 1/3] incorrect hook was used to insert topgit section --- magit-topgit.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/magit-topgit.el b/magit-topgit.el index e19e877c..f576805c 100644 --- a/magit-topgit.el +++ b/magit-topgit.el @@ -78,7 +78,7 @@ ((topic) (magit-checkout info))) -(add-hook 'magit-after-insert-stashes 'magit-insert-topics) +(add-hook 'magit-after-insert-stashes-hook 'magit-insert-topics) (add-hook 'magit-create-branch-command-hook 'magit-topgit-create-branch) (add-hook 'magit-pull-command-hook 'magit-topgit-pull) From 73dbc9d47d9511de495e5432d0e2afa97ef5b329 Mon Sep 17 00:00:00 2001 From: Yann Hodique Date: Sat, 18 Sep 2010 11:58:53 +0200 Subject: [PATCH 2/3] use `intern' in place of `make-symbol' The important difference between the 2 is that we actually *need* the value definition, since this is where we store the actual hooks --- magit.el | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/magit.el b/magit.el index 0532a1bf..e2b5c64f 100644 --- a/magit.el +++ b/magit.el @@ -1478,7 +1478,7 @@ error otherwise." clauses) ,@(when opname `(((run-hook-with-args-until-success - ',(make-symbol (format "magit-%s-action-hook" opname))) + ',(intern (format "magit-%s-action-hook" opname))) t) ((not ,type) (error "Nothing to %s here" ,opname)) @@ -1502,7 +1502,7 @@ the actions." (let ((section (car head)) (info (cadr head)) (type (caddr head))) - `(add-hook ',(make-symbol (format "magit-%s-action-hook" type)) + `(add-hook ',(intern (format "magit-%s-action-hook" type)) (lambda () ,(macroexpand ;; Don't pass in the opname so we don't recursively From 367461f0a1444aaede6dba39da11be5aea885f00 Mon Sep 17 00:00:00 2001 From: Yann Hodique Date: Sat, 18 Sep 2010 13:57:32 +0200 Subject: [PATCH 3/3] Magit extensions documentation documentation for Magit extensions Signed-off-by: Yann Hodique --- magit.texi | 157 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 137 insertions(+), 20 deletions(-) diff --git a/magit.texi b/magit.texi index f53c2fa2..2ad016b4 100644 --- a/magit.texi +++ b/magit.texi @@ -29,26 +29,26 @@ Magit is an interface to the version control system Git, implemented as an extension to Emacs. @menu -* Introduction:: -* Acknowledgments:: -* Sections:: -* Status:: -* Untracked files:: -* Staging and Committing:: -* History:: -* Reflogs:: -* Diffing:: -* Tagging:: -* Resetting:: -* Stashing:: -* Branching:: +* Introduction:: +* Acknowledgments:: +* Sections:: +* Status:: +* Untracked files:: +* Staging and Committing:: +* History:: +* Reflogs:: +* Diffing:: +* Tagging:: +* Resetting:: +* Stashing:: +* Branching:: * The branch list:: -* Wazzup:: -* Merging:: -* Rebasing:: -* Rewriting:: -* Pushing and Pulling:: -* Interfacing with Subversion:: +* Wazzup:: +* Merging:: +* Rebasing:: +* Rewriting:: +* Pushing and Pulling:: +* Using Magit Extensions:: * Using Git Directly:: @end menu @@ -676,8 +676,17 @@ When the remote branch has changes that are not in the current branch, Magit shows them in a section called @emph{Unpulled changes}. Typing @kbd{f f} will merge them into the current branch. +@node Using Magit Extensions +@chapter Magit Extensions + +@menu +* Interfacing with Subversion:: +* Interfacing with Topgit:: +* Developing Extensions:: +@end menu + @node Interfacing with Subversion -@chapter Interfacing with Subversion +@section Interfacing with Subversion Typing @kbd{N r} runs @code{git svn rebase}, typing @kbd{N c} runs @code{git svn dcommit} and typing @kbd{N f} runs @code{git svn fetch}. @@ -688,6 +697,114 @@ limited to the path of the remote Subversion repository. With a prefix (@kbd{C-u N s} the user will also be prompted for a branch to search in. +@node Interfacing with Topgit +@section Interfacing with Topgit + +Topgit (http://repo.or.cz/r/topgit.git) is a patch queue manager that +aims at being close as possible to raw Git, which makes it easy to use +with Magit. In particular, it does not require to use a different set of +commands for ``commit'', ``update'',… operations. + +@file{magit-topgit.el} provides basic integration with Magit, mostly by +providing a ``Topics'' section. + +Topgit branches can be created the regular way, by using a ``t/'' prefix +by convention. So, creating a ``t/foo'' branch will actually populate +the ``Topics'' section with one more branch after committing +@file{.topdeps} and @file{.topmsg}. + +Also, the way we pull (see @ref{Pushing and Pulling}) such a branch is +slightly different, since it requires updating the various dependencies +of that branch. This should be mostly transparent, except in case +of conflicts. + +@node Developing Extensions +@section Developing Extensions + +Magit provides a generic mechanism to allow cooperation with Git-related +systems, such as foreign VCS, patch systems,… + +In particular it allows to: + +@itemize @bullet +@item +Define sections to display specific informations about the current state +of the repository, and place them relatively to existing sections. + +@code{magit-define-inserter} automagically defines two hooks called +@code{magit-before-insert-SECTION-hook} and +@code{magit-after-insert-SECTION-hook} that allow to generate and place +more sections. + +In the following example, we use the builtin ``stashes'' section to +place our own ``foo'' one. + +@example +(magit-define-inserter foo () + (magit-git-section 'foo + "Foo:" 'foo-wash-function + "foo" "arg1" "arg2")) +(add-hook 'magit-after-insert-stashes-hook 'magit-insert-foo) +@end example + +@item +Define new types of objects in those sections. + +The function @code{foo-wash-function} defined above post-processes each +line of the output of the ``git foo arg1 arg2'' command, and is able to +associate a type to certain lines. + +A simple implementation could be: + +@example +(defun foo-wash-function () + (let ((foo (buffer-substring (line-beginning-position) (line-end-position)))) + (goto-char (line-beginning-position)) + (magit-with-section foo 'foo + (magit-set-section-info foo) + (forward-line)))) +@end example + +In this case, every line of the command output is transformed into an +object of type @code{'foo}. + +@item +Alter behavior of generic commands to dispatch them correctly to the +relevant system, optionally making use of the newly defined types. + +@example +(magit-add-action (item info "discard") + ((foo) + (do-something-meaningful-for-discarding-a-foo))) +@end example + +This will alter the behavior of @kbd{k}, when applied to those objects. + +@item +Plug a different logic into basic commands, to reflect the presence of +the extension. + +@code{magit-define-command} automagically defines +a @code{magit-CMD-command-hook} that can contain a list of functions to +call before the actual core code. Execution stops after the first hook +that returns a non-nil value. This leaves room for extension logic. + +@example +(add-hook 'magit-create-branch-command-hook 'foo-create-branch) +@end example + +The function @code{foo-create-branch} will be called each time an +attempt is made to create a branch, and can, for example, react to +a certain name convention. + +@item +Define new commands and associated menu. + +This part is not really specific to extensions, except that menus take +place in the ``Extensions'' submenu. + +@end itemize + @node Using Git Directly @chapter Using Git Directly