23.8.9.1 Change Logs and VC

If you use RCS or CVS for a program and also maintain a change log file for it (see section Change Logs), you can generate change log entries automatically from the version control log entries:

C-x v a

Visit the current directory's change log file and, for registered files in that directory, create new entries for versions checked in since the most recent entry in the change log file. (vc-update-change-log).

This command works with RCS or CVS only, not with any of the other back ends.

C-u C-x v a

As above, but only find entries for the current buffer's file.

M-1 C-x v a

As above, but find entries for all the currently visited files that are maintained with version control. This works only with RCS, and it puts all entries in the log for the default directory, which may not be appropriate.

For example, suppose the first line of ‘ChangeLog’ is dated 1999-04-10, and that the only check-in since then was by Nathaniel Bowditch to ‘rcs2log’ on 1999-05-22 with log text ‘Ignore log messages that start with `#'.’. Then C-x v a visits ‘ChangeLog’ and inserts text like this:

1999-05-22  Nathaniel Bowditch  <nat@apn.org>

        * rcs2log: Ignore log messages that start with `#'.

You can then edit the new change log entry further as you wish.

Some of the new change log entries may duplicate what's already in ChangeLog. You will have to remove these duplicates by hand.

Normally, the log entry for file ‘foo’ is displayed as ‘* foo: text of log entry’. The ‘:’ after ‘foo’ is omitted if the text of the log entry starts with ‘(functionname): ’. For example, if the log entry for ‘vc.el’ is ‘(vc-do-command): Check call-process status.’, then the text in ‘ChangeLog’ looks like this:

1999-05-06  Nathaniel Bowditch  <nat@apn.org>

        * vc.el (vc-do-command): Check call-process status.

When C-x v a adds several change log entries at once, it groups related log entries together if they all are checked in by the same author at nearly the same time. If the log entries for several such files all have the same text, it coalesces them into a single entry. For example, suppose the most recent check-ins have the following log entries:

• For ‘vc.texinfo’: ‘Fix expansion typos.’ • For ‘vc.el’: ‘Don't call expand-file-name.’ • For ‘vc-hooks.el’: ‘Don't call expand-file-name.’

They appear like this in ‘ChangeLog’:

1999-04-01  Nathaniel Bowditch  <nat@apn.org>

        * vc.texinfo: Fix expansion typos.

        * vc.el, vc-hooks.el: Don't call expand-file-name.

Normally, C-x v a separates log entries by a blank line, but you can mark several related log entries to be clumped together (without an intervening blank line) by starting the text of each related log entry with a label of the form ‘{clumpname} ’. The label itself is not copied to ‘ChangeLog’. For example, suppose the log entries are:

• For ‘vc.texinfo’: ‘{expand} Fix expansion typos.’ • For ‘vc.el’: ‘{expand} Don't call expand-file-name.’ • For ‘vc-hooks.el’: ‘{expand} Don't call expand-file-name.’

Then the text in ‘ChangeLog’ looks like this:

1999-04-01  Nathaniel Bowditch  <nat@apn.org>

        * vc.texinfo: Fix expansion typos.
        * vc.el, vc-hooks.el: Don't call expand-file-name.

A log entry whose text begins with ‘#’ is not copied to ‘ChangeLog’. For example, if you merely fix some misspellings in comments, you can log the change with an entry beginning with ‘#’ to avoid putting such trivia into ‘ChangeLog’.