The Emacs command C-x 4 a adds a new entry to the change log file for the file you are editing (add-change-log-entry-other-window). If that file is actually a backup file, it makes an entry appropriate for the file's parent--that is useful for making log entries for functions that have been deleted in the current version.
A change log file contains a chronological record of when and why you have changed a program, consisting of a sequence of entries describing individual changes. Normally it is kept in a file called ChangeLog in the same directory as the file you are editing, or one of its parent directories. A single ChangeLog file can record changes for all the files in its directory and all its subdirectories.
A change log entry starts with a header line that contains your name, your email address (taken from the variable user-mail-address), and the current date and time. Aside from these header lines, every line in the change log starts with a space or a tab. The bulk of the entry consists of items, each of which starts with a line starting with whitespace and a star. Here are two entries, both dated in May 1993, each with two items:
1993-05-25 Richard Stallman <rms@gnu.org>
* man.el: Rename symbols `man-*' to `Man-*'.
(manual-entry): Make prompt string clearer.
* simple.el (blink-matching-paren-distance):
Change default to 12,000.
1993-05-24 Richard Stallman <rms@gnu.org>
* vc.el (minor-mode-map-alist): Don't use it if it's void.
(vc-cancel-version): Doc fix. |
One entry can describe several changes; each change should have its own item. Normally there should be a blank line between items. When items are related (parts of the same change, in different places), group them by leaving no blank line between them. The second entry above contains two items grouped in this way.
C-x 4 a visits the change log file and creates a new entry unless the most recent entry is for today's date and your name. It also creates a new item for the current file. For many languages, it can even guess the name of the function or other object that was changed.
When the option add-log-keep-changes-together is non-nil, C-x 4 a adds to any existing entry for the file rather than starting a new entry.
If the value of the variable change-log-version-info-enabled is non-nil, C-x 4 a ads the file's version number to the change log entry. It finds the version number by searching the first ten percent of the file, using regular expressions from the variable change-log-version-number-regexp-list.
The change log file is visited in Change Log mode. In this major mode, each bunch of grouped items counts as one paragraph, and each entry is considered a page. This facilitates editing the entries. C-j and auto-fill indent each new line like the previous line; this is convenient for entering the contents of an entry.
You can use the command M-x change-log-merge to merge other log files into a buffer in Change Log Mode, preserving the date ordering of entries.
Versions of Emacs before 20.1 used a different format for the time of the change log entry:
Fri May 25 11:23:23 1993 Richard Stallman <rms@gnu.org> |
The M-x change-log-redate command converts all the old-style date entries in the change log file visited in the current buffer to the new format, to make the file uniform in style. This is handy when entries are contributed by many different people, some of whom use old versions of Emacs.
Version control systems are another way to keep track of changes in your program and keep a change log. .