33.1 Change Logs
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.
You should put a copyright notice and permission notice at the
end of the change log file. Here is an example:
Copyright 1997, 1998 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification, are
permitted provided the copyright notice and this notice are preserved.
Of course, you should substitute the proper years and copyright holder.
A change log entry starts with a header line that contains the current
date, your name, and your email address (taken from the variable
add-log-mailing-address). 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, with two items and one item respectively.
1993-05-25 Richard Stallman <[email protected]>
* 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 <[email protected]>
* 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, or its own line in an 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.
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 variable add-log-keep-changes-together is
non-nil, C-x 4 a adds to any existing item for the file
rather than starting a new item.
If the value of the variable change-log-version-info-enabled
is non-nil, C-x 4 a adds 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.
If add-log-always-start-new-record is non-nil,
C-x 4 a always makes a new entry, even if the last entry
was made by you and on the same date.
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 <[email protected]>
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. See Log Buffer.
