3.3 How vc-chlog works

At the heart of vc-chlog, there is a long pipe that processes a prototype ChangeLog entry from a patch and a source tree. This source tree is assumed to be patched, i.e., already has the patch applied.

From the patch text, func_extract_changed_lines generates a list of changes. For each changed file, it outputs a line containing the filename, a strip prefix, a couple of integers d1 and d2, then a list of ranges, all separated with spaces. The strip prefix is the argument that needs to be passed to the -p option of the patch command. The integers d1 and d2 denote the line numbers of the patch text that deal with filename, while the ranges deal with line numbers within the file filename.

A range consists of four minus-separated integers a-b-c-d. They denote that, in the old version of filename, lines a through b inclusively have been changed and end up as lines c through d inclusively in the new file. Purely added or purely removed lines are denoted with a 0-0 pair.

This information is passed to func_extract_identifiers, the heart of the script. Unless identifier extraction has been disabled with --no-functions, for each changed file, it calls a helper function func_taglist, which uses ctags -x to obtain a list of identifiers in both the new, and the old version of the file. These lists are ordered by line number. Changes between two consecutive identifiers will later be assumed to change the earlier of the two.

While this works reasonably well for functions, it fails, for example, for global variable declarations or changes to comments outside of functions. So func_taglist applies some heuristics to guess the end of a function, e.g. a closing brace in the first column, and inserts an empty tag there.

With all tags in place, func_extract_identifiers selects those that match the change intervals, merges the lists from the old and the new file, and outputs them, avoiding duplicates and roughly maintaining the order of the identifiers in the new file.

Care is taken throughout that the tags may contain spaces, so that Texinfo @nodes may be listed as tags.

In a couple of final steps, the sets of files with identifiers are keyed to one or more ChangeLog files throughout the source tree using func_sortby_chlog, and a GCS-style ChangeLog entry stub is formatted with func_pretty_changelog_entry.

The fact that vc-chlog is written as a portable shell script, using awk, sed, and other POSIX tools freely, adds to the compactness of the script, added to the fun in writing it, necessitates slightly awkward data constructs, and probably impedes easy modification and debugging. This might be construed as a bug.