28.1.4 Features of the Log Entry Buffer

When you tell VC to commit a change, it pops up a buffer named *vc-log*. In this buffer, you should write a log entry describing the changes you have made (see Why Version Control?). After you are done, type C-c C-c (log-edit-done) to exit the buffer and commit the change, together with your log entry.

The major mode for the *vc-log* buffer is Log Edit mode, a variant of Text mode (see Text Mode). On entering Log Edit mode, Emacs runs the hooks text-mode-hook and vc-log-mode-hook (see Hooks).

In the *vc-log* buffer, you can write one or more header lines, specifying additional information to be supplied to the version control system. Each header line must occupy a single line at the top of the buffer; the first line that is not a header line is treated as the start of the log entry. For example, the following header line states that the present change was not written by you, but by another developer:

Author: J. R. Hacker <jrh@example.com>

Apart from the ‘Author’ header, Emacs recognizes the headers ‘Summary’ (a one-line summary of the changeset), ‘Date’ (a manually-specified commit time), and ‘Fixes’ (a reference to a bug fixed by the change). Not all version control systems recognize all headers. If you specify a header for a system that does not support it, the header is treated as part of the log entry.

While in the *vc-log* buffer, the current VC fileset is considered to be the fileset that will be committed if you type C-c C-c. To view a list of the files in the VC fileset, type C-c C-f (log-edit-show-files). To view a diff of changes between the VC fileset and the version from which you started editing (see Old Revisions), type C-c C-d (log-edit-show-diff).

To help generate ChangeLog entries, type C-c C-w (log-edit-generate-changelog-from-diff), to generate skeleton ChangeLog entries, listing all changed file and function names based on the diff of the VC fileset. Consecutive entries left empty will be combined by C-q (fill-paragraph).

If the VC fileset includes one or more ChangeLog files (see Change Log), type C-c C-a (log-edit-insert-changelog) to pull the relevant entries into the *vc-log* buffer. If the topmost item in each ChangeLog was made under your user name on the current date, this command searches that item for entries matching the file(s) to be committed, and inserts them. If you are using CVS or RCS, see Change Logs and VC, for the opposite way of working—generating ChangeLog entries from the Log Edit buffer.

To abort a commit, just don’t type C-c C-c in that buffer. You can switch buffers and do other editing. As long as you don’t try to make another commit, the entry you were editing remains in the *vc-log* buffer, and you can go back to that buffer at any time to complete the commit.

You can also browse the history of previous log entries to duplicate a commit comment. This can be useful when you want to make several commits with similar comments. The commands M-n, M-p, M-s and M-r for doing this work just like the minibuffer history commands (see Minibuffer History), except that they are used outside the minibuffer.