regexps.com
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
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).)
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.)
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 commitarch: The arch Revision Control System
regexps.com