The Hackerlab at `regexps.com`

## Patch Logs and ChangeLogs

up: arch next: Star Topology Branching and Merging prev: Basic Branching and Merging

Every project tree has an associated patch log: a collection of log entries for each `commit` or `import` in the history of that patch tree. When you commit a new revision, the log entry you write is saved in two places: it is saved in the archive as a plain text file (for browsing and as a record of complex ancestory relationships), and in the project tree itself (for browsing and to control history sensative merging).

Logs are organized by version. The command:

            % cd ~/wd/project
            % larch add-log [[ARCHVIE/]VERSION-NAME]

creates a new (empty) log for the indicated version. (Version names were introduced in The arch Global Name-space of Projects and their relationship to archived revisions explained in Development Paths.)

The command:

            % larch logs

lists all of the version names for which a project tree has a patch log.

The command:

            % larch log-ls [[ARCHIVE/]VERSION-NAME]

lists all of the patch levels for which a tree has log entries (for revisions in the indicated version). With the `summary` flag:

            % larch log-ls --summary [[ARCHIVE/]VERSION-NAME]

the `Summary:` header of each log entry is printed.

To see the complete text of an entry, use:

            % larch cat-log [ARCHIVE/]VERSION--PATCH-LEVEL

### Branches and Patch Logs

When you form a branch, project trees on the branch have (at least) two patch logs: one for the original development path, and one for the branch itself. When you merge changes from one branch to another, so long as both branches have the same project category, the merged tree has patch logs for both branches. ("Project categories" were introduced in The arch Global Name-space of Projects).)

### Comparing Patch Logs to Archives

You can find out if an archive contains patches that haven't yet been applied to your project tree with this command:

            % larch whats-missing [[ARCHIVE/]VERSION ...]
            <list of missing patches>

That command compares the patch log stored in the archived with the patch log found in the project tree and prints the list of missing patches. There may be missing patches if your tree is not up-to-date with respect to the archive, or if when your tree was created, some patches were skipped.

You can see the `Summary:` line of each missing patch with:

            % larch whats-missing --summary [[ARCHIVE/]VERSION ...]

If you want the list to contain fully-qualified patch level names, use the `--full` option.

If you want to know where branch A stands in relation to branch B, one way to find out is with:

            % larch get A dir

            % cd dir

            % larch whats-missing B

(It is possible to obtain the same information without having to `get` a revision from branch A, using commands already introduced, plus some other shell commands. The details are left as an exercise for the interested reader.)

### ChangeLogs

The command `larch changelog` generates a GNU-style `ChangeLog` file from a patch log:

            % larch changelog

or

            % larch changelog [ARCHIVE/]VERSION

The `ChangeLog` file generated for `arch` , for example, might begin:

       # do not edit -- automatically generated by arch changelog
       #
       # tag: automatic-ChangeLog--lord@regexps.com--arch-1/arch--devo--0.5
       #

       2001-12-17  Tom Lord <lord@regexps.com>

           Summary:
             `update' and `replay' output format and bug fixes

           `udpate' and `replay' -- structured output and updated argument
           processing for reasonable defaults.

           `replay': copy precious files before (not after) appling patches
           so they are carried along with directory renames in patch sets.

           `dopatch': don't pipe `larch heading' into `larch body-indent'.

           modified files:
            ChangeLog src/arch/=TODO
            src/arch/branching-and-merging/replay.sh
            src/arch/branching-and-merging/update.sh
            src/arch/patch-sets/dopatch.sh

       2001-12-17  Tom Lord <lord@regexps.com>

           Summary:

       [...]

Notice the first line which says `do not edit ...` . If a project tree contains files matching either of the patterns:

            ChangeLog
            ChangeLog.*

whose first lines contain the string `larch changelog` , the command `larch commit` will automatically update that file before checking-in the new revision; the commands `update` and `replay` will update the change logs after patches have been applied.

When updating a `ChangeLog` , `larch commit` looks for a line that says `patch log:` and uses the corresponding patch log to update the ChangeLog.

This is especially useful when development takes place on branches that are later to be merged with a primary branch. The top-level `ChangeLog` file always remains on the primary development path. Each branch can add its own file:

            ChangeLog.BRANCH--VERSION

When it comes time to merge, a log entry for the merge `commit` can be written by editting the `ChangeLog.BRANCH--VERSION` file. A useful idiom is:

            % larch tag BRANCH-FROM BRANCH-TO
            [....]

            % larch get BRANCH-TO DIR
            [....]

            % cd DIR

            % larch changelog > ChangeLog.BRANCH-TO

            % larch make-log
            [...edit log file...]

            % larch commit

arch: The arch Revision Control System
The Hackerlab at `regexps.com`