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
-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
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
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
@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
The fact that vc-chlog is written as 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.