Say you have made some changes to your code, ready to be committed. The only remaining part is to write one or more ChangeLog entries: for each ChangeLog governing a part of the package, collect the list of changed files, in each file list the changed functions, and mention all of those, in order to afterwards describe the changes:
1984-01-01 A.U. Thor <email@address> * file1.c (foo, bar, ...): ... * file2.c (baz): ...
vc-chlog attempts to help with this step. It scans the diff
vc-dwim --diff or passed on standard input with
--stdin) for the files that were touched and the set of lines
that have been changed. It then uses the ctags program to try
to find out in which functions those changes have occurred, and formats
the file and functions names in a prototype ChangeLog entry form
on standard output.
There is a crucial assumption behind this idea to work well in practice:
ctags should be able to generate tags for the identifiers that changed.
For example, it should list functions in C source files (but not
function-local or other nested entities); it should list macros in M4
files (e.g., those that serve as input to Autoconf), or it should list
@nodes in Texinfo files. The output of vc-chlog
improves with that of ctags.
Exuberant Ctags is a powerful and extensible implementation of this command, and therefore preferred. For example, with the .ctags file in this package:
it detects the shell script vc-chlog as such. With a ~/.ctags containing
--langdef=Texinfo --langmap=Texinfo:.texi.txi.texinfo --regex-texinfo=/^@node[ ]+([^,]+)/\1/d,definition/
it detects Texinfo node names (vc-chlog uses some heuristic to deal with spaces in the identifier names when Exuberant Ctags is used).
Autoconf macros may be tagged by options such as
--langdef=m4 --langmap=m4:.m4.at.ac.as.m4sh --regex-m4=/^(m4_def(ine|un(|_once))|A[CU]_DEFUN(|_ONCE)|AU_ALIAS)\ \(\[*([a-zA-Z0-9_()+]+)/\5/d,definition/
vc-chlog tries to find out about added as well as removed
identifiers by examining both the new and the old version of a file.
Here, it works hard not to change any file in your working directory, by
ctags -x and keeping all intermediate files in a temporary
For some languages, vc-chlog attempts to guess where functions end, and thus not attribute changes past that end to the previous identifier.
Typically, vc-chlog is exact in the list of files that changed, false negatives in the list of identifiers stem from a ctags that failed to enumerate all identifiers properly, or changes before a function, false positives typically stem from constructs like nested functions.
Use vc-chlog with multiple ChangeLog files in a project
If a project uses multiple ChangeLog files, vc-chlog assumes that changes are to be recorded in the log file that is nearest up the directory tree. One possibility is to invoke vc-chlog always from the project root and put the output of
find . -name ChangeLog | sed 's,^\./,--changelog ,'
into the .vc-chlogrc file at the root.