Previous: Initiating a Commit, Up: Committing [Contents][Index]
After initiating a commit as described in the previous section, two new buffers appear. One shows the changes that are about to committed, while the other is used to write the message. All regular editing commands are available in the commit message buffer. This section only describes the additional commands.
Commit messages are edited in an edit session - in the background Git
is waiting for the editor, in our case the Emacsclient, to save the
commit message in a file (in most cases .git/COMMIT_EDITMSG) and then
return. If the Emacsclient returns with a non-zero exit status then
Git does not create the commit. So the most important commands are
those for finishing and aborting the commit.
with-editor-finish)Finish the current editing session by returning with exit code 0. Git then creates the commit using the message it finds in the file.
with-editor-cancel)Cancel the current editing session by returning with exit code 1. Git then cancels the commit, but leaves the file untouched.
In addition to being used by Git, these messages may also be stored in a ring that persists until Emacs is closed. By default the message is stored at the beginning and the end of an edit session (regardless of whether the session is finished successfully or was canceled). It is sometimes useful to bring back messages from that ring.
git-commit-save-message)Save the current buffer content to the commit message ring.
git-commit-prev-message)Cycle backward through the commit message ring, after saving the current message to the ring. With a numeric prefix ARG, go back ARG comments.
git-commit-next-message)Cycle forward through the commit message ring, after saving the current message to the ring. With a numeric prefix ARG, go back ARG comments.
By default the diff for the changes that are about to be committed are automatically shown when invoking the commit. When amending to an existing commit it may be useful to show either the changes that are about to be added to that commit or to show those changes together with those that are already committed.
magit-diff-while-committing)While committing, show the changes that are about to be committed. While amending, invoking the command again toggles between showing just the new changes or all the changes that will be committed.
magit-pop-revision-stack)This command inserts a representation of a revision into the current buffer. It can be used inside buffers used to write commit messages but also in other buffers such as buffers used to edit emails or ChangeLog files.
By default this command pops the revision which was last added to
the magit-revision-stack and inserts it into the current buffer
according to magit-pop-revision-stack-format. Revisions can be put
on the stack using magit-copy-section-value and
magit-copy-buffer-revision.
If the stack is empty or with a prefix argument it instead reads a revision in the minibuffer. By using the minibuffer history this allows selecting an item which was popped earlier or to insert an arbitrary reference or revision without first pushing it onto the stack.
When reading the revision from the minibuffer, then it might not be possible to guess the correct repository. When this command is called inside a repository (e.g. while composing a commit message), then that repository is used. Otherwise (e.g. while composing an email) then the repository recorded for the top element of the stack is used (even though we insert another revision). If not called inside a repository and with an empty stack, or with two prefix arguments, then read the repository in the minibuffer too.
This option controls how the command magit-pop-revision-stack
inserts a revision into the current buffer.
The entries on the stack have the format (HASH TOPLEVEL) and this
option has the format (POINT-FORMAT EOB-FORMAT INDEX-REGEXP), all
of which may be nil or a string (though either one of EOB-FORMAT
or POINT-FORMAT should be a string, and if INDEX-REGEXP is
non-nil, then the two formats should be too).
First INDEX-REGEXP is used to find the previously inserted entry, by searching backward from point. The first submatch must match the index number. That number is incremented by one, and becomes the index number of the entry to be inserted. If you don’t want to number the inserted revisions, then use nil for INDEX-REGEXP.
If INDEX-REGEXP is non-nil then both POINT-FORMAT and EOB-FORMAT should contain \"%N\", which is replaced with the number that was determined in the previous step.
Both formats, if non-nil and after removing %N, are then expanded using ‘git show –format=FORMAT …’ inside TOPLEVEL.
The expansion of POINT-FORMAT is inserted at point, and the expansion of EOB-FORMAT is inserted at the end of the buffer (if the buffer ends with a comment, then it is inserted right before that).
Some projects use pseudo headers in commit messages. Magit colorizes such headers and provides some commands to insert such headers.
A list of Git pseudo headers to be highlighted.
git-commit-ack)Insert a header acknowledging that you have looked at the commit.
git-commit-review)Insert a header acknowledging that you have reviewed the commit.
git-commit-signoff)Insert a header to sign off the commit.
git-commit-test)Insert a header acknowledging that you have tested the commit.
git-commit-cc)Insert a header mentioning someone who might be interested.
git-commit-reported)Insert a header mentioning the person who reported the issue being fixed by the commit.
git-commit-suggested)Insert a header mentioning the person who suggested the change.
git-commit-mode is a minor mode that is only used to establish
the above key bindings. This allows using an arbitrary major mode
when editing the commit message. It’s even possible to use a
different major mode in different repositories, which is useful when
different projects impose different commit message conventions.
The value of this option is the major mode used to edit Git commit messages.
Because git-commit-mode is a minor mode, we don’t use its mode hook
to setup the buffer, except for the key bindings. All other setup
happens in the function git-commit-setup, which among other things runs
the hook git-commit-setup-hook. The following functions are suitable
for that hook.
Hook run at the end of git-commit-setup.
Revert unmodified file-visiting buffers of the current repository.
If either magit-revert-buffers is non-nil and inhibit-magit-revert
is nil, or if optional FORCE is non-nil, then revert all unmodified
buffers that visit files being tracked in the current repository.
Save the current buffer content to the commit message ring.
After this function is called, ChangeLog entries are treated as paragraphs.
Turn on auto-fill-mode and set fill-column to the value of
git-commit-fill-column.
Turn on Flyspell mode. Also prevent comments from being checked and finally check current non-comment text.
Propertize the diff shown inside the commit message buffer. Git
inserts such diffs into the commit message template when the
--verbose argument is used. Magit’s commit popup by default does
not offer that argument because the diff that is shown in a separate
buffer is more useful. But some users disagree, which is why this
function exists.
Show usage information in the echo area.
Magit also helps with writing good commit messages by complaining when certain rules are violated.
The intended maximal length of the summary line of commit messages. Characters beyond this column are colorized to indicate that this preference has been violated.
Column beyond which automatic line-wrapping should happen in commit message buffers.
List of functions called to query before performing commit.
The commit message buffer is current while the functions are called. If any of them returns nil, then the commit is not performed and the buffer is not killed. The user should then fix the issue and try again.
The functions are called with one argument. If it is non-nil then that indicates that the user used a prefix argument to force finishing the session despite issues. Functions should usually honor this wish and return non-nil.
Check for violations of certain basic style conventions. For each violation ask the user if she wants to proceed anyway. This makes sure the summary line isn’t too long and that the second line is empty.
To show no diff while committing remove magit-commit-diff from
server-switch-hook.
Previous: Initiating a Commit, Up: Committing [Contents][Index]