GNU Info

(emacs)Change Log

---

Next: Tags Up: Maintaining

---

Enter node , (file) or (file)node

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 `user-mail-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, 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' 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'.

   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.  Note: Log Buffer.