3.1 Getting up and going with vc-chlog

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 (obtained by 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.

Finding identifiers for what has changed:

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:

--langmap=Sh:+.in

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 heuristics 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 using ctags -x and keeping all intermediate files in a temporary directory.

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, and 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.