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 Understanding the Problems it Addresses).
Alternatively, you can have the entry automatically inserted from a
ChangeLog file or buffer (see below), which you can further edit in the
*vc-log* buffer if necessary. 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.
In the *vc-log* buffer, you can also write one or more header lines specifying additional information to be supplied to the version control system. 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>
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. In addition to the ‘Author’ header, most version control systems also support the headers ‘Summary’ (a one-line summary of the changeset) and ‘Date’ (a manually specified commit time). Emacs recognizes these as well as several VCS-specific headers. If you specify a header for a VCS that does not support it, the header is treated as part of the 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 addition, to set up the *vc-log* buffer,
Emacs runs the hook log-edit-hook, which optionally makes several
useful features available. The following paragraphs describe several of
these features, including three that are generally useful and enabled by
default. (To see a complete list of the features and enable or disable
any of them, type M-x customize-option RET log-edit-hook RET;
see Customizing Specific Items.)
The function log-edit-insert-message-template produces the
default *vc-log* buffer setup, containing ‘Author’ and
‘Summary’ headers, and displays a thick line separating the header
part of the buffer from the log entry part. If you remove
log-edit-insert-message-template from log-edit-hook, then
the initial *vc-log* buffer is simply empty. The two header
lines are initially empty. If you are the author of the change and you
have configured the VCS to use your name and email address in commit
messages, you can leave the ‘Author’ header empty. If you leave
the ‘Summary’ header empty, most systems will use the first line of
the log entry as the summary line (see below for a way to have the
‘Summary’ header automatically filled).
When VC pops up the *vc-log* buffer, a buffer named
*log-edit-files* listing the current VC fileset, that is, the
files that will be committed if you type C-c C-c, also pops up
by default. If you have removed the command log-edit-show-files
from log-edit-hook, the *log-edit-files* buffer does not
automatically pop up, but you can invoke the command by typing
C-c C-f. Likewise, if you kill or bury the
*log-edit-files* buffer, typing C-c C-f will pop it up
again.
To view a diff of changes between the VC fileset and the version from
which you started editing (see Examining And Comparing Old Revisions), type C-c C-d
(log-edit-show-diff). This command also selects the window
displaying the diff. To have VC automatically display the diff when it
pops up the *vc-log* buffer, add log-edit-maybe-show-diff
to log-edit-hook; unlike C-c C-d, this function does not
select the window displaying the 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 M-q (fill-paragraph). By default the
skeleton will just include the file name, without any leading
directories. If you wish to prepend the leading directories up to the
VC root, customize diff-add-log-use-relative-names.
If you have added log entries for the current VC fileset to one or
more ChangeLog files or to a temporary ChangeLog buffer
(see Change Logs), by default VC automatically inserts these entries
into the *vc-log* buffer on popping it up. If you have removed
the command log-edit-insert-changelog from log-edit-hook,
VC does not automatically insert the log entries, but you can invoke the
command by typing C-c C-a. Likewise, if you delete or otherwise
change the content of this buffer and then decide you want to use the
ChangeLog entries after all, type C-c C-a to repopulate the buffer
with these entries.
If the relevant log entries are in one or more ChangeLog files and the topmost item in each file was made under your user name on the current date, this command searches that item (or those items) for entries matching the file(s) to be committed, and inserts them. If you invoke the command with a prefix argument (C-u C-c C-a) or repeat it immediately (C-c C-a C-c C-a), it searches the topmost item regardless of the user name and date of the item.
If VC detects that all log entries come from the same ChangeLog file or buffer, then the command simply inserts the entire body of the entry into the *vc-log* buffer. In addition, if the first line of the entry does not begin with ‘* ’ (an asterisk followed by a space), VC considers it to be a summary line and moves it to the ‘Summary’ header. Finally, if VC detects that the set of changed files listed in the ChangeLog entry differs from the current VC fileset, it displays a warning urging you to fix this discrepancy before committing the changes.
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.