32.1.4 Features of the Log Entry Buffer

When you tell VC to commit a change, it pops up a buffer called ‘*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; this exits the buffer and commits the change, together with your log entry.

While 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 ‘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: Bazaar recognizes all three headers, while git, Mercurial, and Monotone recognizes only ‘Author’ and ‘Summary’. If you specify a header for a version control that does not support it, the header is treated as part of the log entry.

Type C-c C-f (log-edit-show-files) to display a list of files in the current VC fileset. If you called C-x v v directly from a work file, the fileset consists of that single file; if you called C-x v v from a VC directory buffer (see VC Directory Mode), the fileset may consist of multiple files.

Type C-c C-d (log-edit-show-diff) to show a diff of the changes you have made (i.e., the differences between the work file and the repository revision from which you started editing). See Old Revisions.

If the current 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 that match the file(s) to be committed; if found, these entries are inserted. See Change Logs and VC, for the opposite way of working—generating ChangeLog entries from the revision control log.

To abort a check-in, 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 commit another file, 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 check-in.

If you change several source files for the same reason, it is often convenient to specify the same log entry for many of the files. (This is the normal way to do things on a changeset-oriented system, where comments are attached to changesets rather than the history of individual files.) The most convenient way to do this is to mark all the files in VC Directory Mode and commit from there; the log buffer will carry the fileset information with it and do a group commit when you type C-c C-c.

You can also browse the history of previous log entries to duplicate a checkin comment. This can be useful when you want several files to have checkin comments that vary only slightly from each other. The commands M-n, M-p, M-s and M-r for doing this work just like the minibuffer history commands (except that these versions are used outside the minibuffer).

Each time you commit a change, the log entry buffer is put into VC Log Edit mode, which involves running two hooks: text-mode-hook and vc-log-mode-hook. See Hooks.