regexps.com
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
.
regexps.com