The Hackerlab at `regexps.com`

## Writing Log Entries for Merges

up: arch next: Arbitrary Patching with delta-patch prev: Star Topology Branching and Merging

Suppose you have used `star-merge` or some other commands to merge two or more branches. You are ready to commit those changes, but first you have to write a log message.

All of the changes you've just merged are already explained in existing log messages. Your new log message can simply summarize the changes, and point to the more detailed log entries. `arch` has commands which help with this.

The command:

            % larch new-on-branch [--reverse] [--dir .] VERSION

reports a list of patches found in a project tree, but not previously merged with `VERSION` . Those patches are the ones that were added by your merging activity.

You can print a summary of the changes made by those patches by using `xargs` and the `log-ls` command. For example, the main development path for arch `1` .0 is called `arch--devo--1.0` . I develop new features on various branches. When it comes time to write a log message before committing a merge to `arch--devo` , I use:

            % larch new-on-branch --reverse arch--devo--1.0 \
              | xargs larch log-ls --full --summary

            lord@regexps.com--2002/arch--lord--1.0--patch-14
                `merge-points' fixes and `new-on-branch' speed-up
            lord@regexps.com--2002/arch--lord--1.0--patch-13
                Use --dir consistently.
            lord@regexps.com--2002/arch--lord--1.0--patch-12
                output format touch-ups

That idiom is captured, along with a little bit of formatting, by the command `log-for-merge` :

            % larch log-for-merge arch--devo--1.0

            Patches applied:

            * lord@regexps.com--2002/arch--lord--1.0--patch-14
                `merge-points' fixes and `new-on-branch' speed-up

            * lord@regexps.com--2002/arch--lord--1.0--patch-13
                Use --dir consistently.

            * lord@regexps.com--2002/arch--lord--1.0--patch-12
                output format touch-ups

(An advantage of using the formate generated by `log-for-merge` is that it is understood by other `arch` commands which automatically format web pages from `ChangeLogs` .)

That works out nicely as part of a log message if you organize `ChangeLogs` as I do. In the top-level of the `arch` source code, I have an automatic `ChangeLog` for the `arch--devo--branch` :

            arch/
              arch/ChangeLog

I created that once, using:

            % larch changelog arch--devo--1.0 > ChangeLog

and after that, it is automatically updated with every `commit` , `update` , or similar operation.

I also have per-branch `ChangeLogs` :

        arch/
          arch/ChangeLog.d/
            arch/ChangeLog.d/lord@regexps.com--2002/
              arch/ChangeLog.d/lord@regexps.com--2002/ChangeLog.lord--1.0
              arch/ChangeLog.d/lord@regexps.com--2002/ChangeLog.lord-doc--1.0

Note that `lord@regexps.com...` is the name of my archive. Two branches that I develop on are:

            arch--lord--1.0
            arch--lord-doc--1.0

and each of those has their own ChangeLog. I created those logs with similar commands. For example:

            % larch changelog arch--lord--1.0 > ChangeLog.lord

To write the log entry for a merge, I start with the output of `log-for-merge` application shown above, and add a tiny bit of extra text for people browsing the ChangeLogs as plain text:

            Summary: merge with `lord'
            Keywords:

            Merge with branch `lord'.

            For details, see

                Changelog.d/lord@regexps.com--2002/ChangeLog.lord--1.0

            Patches applied:

            * lord@regexps.com--2002/arch--lord--1.0--patch-14
                 `merge-points' fixes and `new-on-branch' speed-up

            * lord@regexps.com--2002/arch--lord--1.0--patch-13
                 Use --dir consistently.

            * lord@regexps.com--2002/arch--lord--1.0--patch-12
                 output format touch-ups

Note that for each of the `Patches applied` , there is a corresponding `ChangeLog` entry in `ChangeLog.d` .

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