Previous: , Up: Committing   [Contents][Index]

6.4.2 Editing Commit Messages

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.

C-c C-c     (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.

C-c C-k     (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.

C-c M-s     (git-commit-save-message)

Save the current buffer content to the commit message ring.

M-p     (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.

M-n     (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.

C-c C-d     (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.

C-c C-w     (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.

User Option: magit-pop-revision-stack-format

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.

User Option: git-commit-known-pseudo-headers

A list of Git pseudo headers to be highlighted.

C-c C-a     (git-commit-ack)

Insert a header acknowledging that you have looked at the commit.

C-c C-r     (git-commit-review)

Insert a header acknowledging that you have reviewed the commit.

C-c C-s     (git-commit-signoff)

Insert a header to sign off the commit.

C-c C-t     (git-commit-test)

Insert a header acknowledging that you have tested the commit.

C-c C-o     (git-commit-cc)

Insert a header mentioning someone who might be interested.

C-c C-p     (git-commit-reported)

Insert a header mentioning the person who reported the issue being fixed by the commit.

C-c C-i     (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.

User Option: git-commit-major-mode

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.

User Option: git-commit-setup-hook

Hook run at the end of git-commit-setup.

Function: magit-revert-buffers &optional force

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.

Function: git-commit-save-message

Save the current buffer content to the commit message ring.

Function: git-commit-setup-changelog-support

After this function is called, ChangeLog entries are treated as paragraphs.

Function: git-commit-turn-on-auto-fill

Turn on auto-fill-mode and set fill-column to the value of git-commit-fill-column.

Function: git-commit-turn-on-flyspell

Turn on Flyspell mode. Also prevent comments from being checked and finally check current non-comment text.

Function: git-commit-propertize-diff

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.

Function: with-editor-usage-message

Show usage information in the echo area.

Magit also helps with writing good commit messages by complaining when certain rules are violated.

User Option: git-commit-summary-max-length

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.

User Option: git-commit-fill-column

Column beyond which automatic line-wrapping should happen in commit message buffers.

User Option: git-commit-finish-query-functions

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.

Function: git-commit-check-style-conventions

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: , Up: Committing   [Contents][Index]