File: git-commit.el.html

This package assists the user in writing good Git commit messages.

While Git allows for the message to be provided on the command line, it is preferable to tell Git to create the commit without actually passing it a message. Git then invokes the $GIT_EDITOR
(or if that is undefined $EDITOR) asking the user to provide the
message by editing the file ".git/COMMIT_EDITMSG" (or another file in that directory, e.g., ".git/MERGE_MSG" for merge commits).

When global-git-commit-mode(var)/global-git-commit-mode(fun) is enabled, which it is by default, then opening such a file causes the features described below, to be enabled in that buffer. Normally this would be done using a major-mode but to allow the use of any major-mode, as the user sees fit, it is done here by running a setup function, which among other things turns on the preferred major-mode, by default text-mode.

Git waits for the $EDITOR to finish and then either creates the commit using the contents of the file as commit message, or, if the editor process exited with a non-zero exit status, aborts without creating a commit. Unfortunately Emacsclient (which is what Emacs users should be using as $EDITOR or at least as $GIT_EDITOR) does not differentiate between "successfully" editing a file and aborting; not out of the box that is.

By making use of the with-editor package this package provides both ways of finish an editing session. In either case the file is saved, but Emacseditor's exit code differs.

  C-c C-c Finish the editing session successfully by returning
           with exit code 0. Git then creates the commit using
           the message it finds in the file.

  C-c C-k Aborts the edit editing session by returning with exit
           code 1. Git then aborts the commit.

Aborting the commit does not cause the message to be lost, but relying solely on the file not being tampered with is risky. This package additionally stores all aborted messages for the duration of the current session (i.e., until you close Emacs). To get back an aborted message use M-p and M-n while editing a message.

  M-p Replace the buffer contents with the previous message
           from the message ring. Of course only after storing
           the current content there too.

  M-n Replace the buffer contents with the next message from
           the message ring, after storing the current content.

Support for inserting Git trailers (as described in the manpage git-interpret-trailers(1)) is available.

  C-c C-i Insert a trailer selected from a transient menu.

When Git requests a commit message from the user, it does so by having her edit a file which initially contains some comments, instructing her what to do, and providing useful information, such as which files were modified. These comments, even when left intact by the user, do not become part of the commit message. This package ensures these comments are propertizes as such and further prettifies them by using different faces for various parts, such as files.

Finally this package highlights style errors, like lines that are too long, or when the second line is not empty. It may even nag you when you attempt to finish the commit without having fixed these issues. The style checks and many other settings can easily be configured:

  M-x customize-group RET git-commit RET

Defined variables (27)

git-commit-cd-to-toplevelWhether to set ‘default-directory’ to the worktree in message buffer.
git-commit-comment-headingsAlso fontified outside of comments in ‘git-commit-font-lock-keywords-2’.
git-commit-elisp-text-mode-abbrev-tableAbbrev table for ‘git-commit-elisp-text-mode’.
git-commit-elisp-text-mode-hookHook run after entering ‘git-commit-elisp-text-mode’.
git-commit-elisp-text-mode-mapKeymap for ‘git-commit-elisp-text-mode’.
git-commit-elisp-text-mode-syntax-tableSyntax table for ‘git-commit-elisp-text-mode’.
git-commit-finish-query-functionsList of functions called to query before performing commit.
git-commit-font-lock-keywordsFont-Lock keywords for Git-Commit mode.
git-commit-header-line-formatIf non-nil, header line format used by ‘git-commit-mode’.
git-commit-known-pseudo-headersA list of Git trailers to be highlighted.
git-commit-major-modeMajor mode used to edit Git commit messages.
git-commit-modeNon-nil if Git-Commit mode is enabled.
git-commit-mode-hookThis variable is an alias for ‘git-commit-setup-hook’ (which see).
git-commit-mode-mapKeymap used by ‘git-commit-mode’.
git-commit-mode-menuGit Commit Mode Menu.
git-commit-need-summary-lineWhether the text should have a heading that is separated from the body.
git-commit-post-finish-hookHook run after the user finished writing a commit message.
git-commit-post-finish-hook-timeoutTime in seconds to wait for git to create a commit.
git-commit-redundant-bindingsBindings made redundant by ‘git-commit-insert-trailer’.
git-commit-setup-hookHook run at the end of ‘git-commit-setup’.
git-commit-style-convention-checksList of checks performed by ‘git-commit-check-style-conventions’.
git-commit-summary-max-lengthColumn beyond which characters in the summary lines are highlighted.
git-commit-trailersA list of Git trailers to be highlighted.
git-commit-usage-messageMessage displayed when editing a commit message.
git-commit-use-local-message-ringWhether to use a local message ring instead of the global one.
global-git-commit-modeNon-nil if Global Git-Commit mode is enabled.
global-git-commit-mode-hookHook run after entering or leaving ‘global-git-commit-mode’.

Defined functions (44)

git-commit--auto-fill-except-summary()
git-commit--flyspell-verify()
git-commit--insert-ident-trailer(TRAILER NAME EMAIL)
git-commit--insert-trailer(TRAILER VALUE)
git-commit-ack(NAME MAIL)
git-commit-cc(NAME MAIL)
git-commit-check-style-conventions(FORCE)
git-commit-co-authored(NAME MAIL)
git-commit-co-developed(NAME MAIL)
git-commit-collapse-diff()
git-commit-elisp-text-mode()
git-commit-ensure-comment-gap()
git-commit-extend-region-summary-line()
git-commit-finish-query-functions(FORCE)
git-commit-get-ident(&optional PROMPT)
git-commit-insert-changelog-gnu()
git-commit-insert-changelog-plain()
git-commit-insert-header(TRAILER NAME EMAIL)
git-commit-insert-trailer()
git-commit-mode(&optional ARG)
git-commit-mode-menu(ARG1)
git-commit-modified(NAME MAIL)
git-commit-next-message(ARG)
git-commit-prev-message(ARG)
git-commit-read-ident(PROMPT)
git-commit-reported(NAME MAIL)
git-commit-review(NAME MAIL)
git-commit-run-post-finish-hook(PREVIOUS)
git-commit-save-message()
git-commit-search-message-backward(STRING)
git-commit-search-message-forward(STRING)
git-commit-self-ident(&optional PROMPT)
git-commit-setup-auto-fill()
git-commit-setup-capf()
git-commit-setup-changelog-support()
git-commit-setup-flyspell()
git-commit-setup-orglink()
git-commit-signoff(NAME MAIL)
git-commit-suggested(NAME MAIL)
git-commit-test(NAME MAIL)
git-commit-turn-on-auto-fill()
git-commit-turn-on-flyspell()
git-commit-turn-on-orglink()
global-git-commit-mode(&optional ARG)

Defined faces (12)

git-commit-comment-actionFace used for actions in commit message comments.
git-commit-comment-branch-localFace used for names of local branches in commit message comments.
git-commit-comment-branch-remoteFace used for names of remote branches in commit message comments.
git-commit-comment-buttonFace used for buttons in commit message comments.
git-commit-comment-detachedFace used for detached ‘HEAD’ in commit message comments.
git-commit-comment-fileFace used for file names in commit message comments.
git-commit-keywordFace used for keywords in commit messages. In this context a "keyword" is text surrounded by brackets.
git-commit-nonempty-second-lineFace used for non-whitespace on the second line of commit messages.
git-commit-overlong-summaryFace used for the tail of overlong commit message summaries.
git-commit-summaryFace used for the summary in commit messages.
git-commit-trailer-tokenFace used for Git trailer tokens in commit messages.
git-commit-trailer-valueFace used for Git trailer values in commit messages.