@need 3200

@node Patch Logs and ChangeLogs
@chapter Patch Logs and ChangeLogs

@geindex patch log

@geindex add-log

@geindex log-ls

@geindex cat-log



Every project tree has an associated patch log: a collection of log
entries for each @code{commit} or @code{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:

@example
@group
        % cd ~/wd/project
        % larch add-log [[ARCHVIE/]VERSION-NAME]
@end group
@group
@end group
@end example

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


The command:

@example
@group
        % larch logs
@end group
@group
@end group
@end example

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


The command:

@example
@group
        % larch log-ls [[ARCHIVE/]VERSION-NAME]
@end group
@group
@end group
@end example

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

@example
@group
        % larch log-ls --summary [[ARCHIVE/]VERSION-NAME]
@end group
@group
@end group
@end example

@noindent
the @code{Summary:} header of each log entry is printed.


To see the complete text of an entry, use:

@example
@group
        % larch cat-log [ARCHIVE/]VERSION--PATCH-LEVEL
@end group
@group
@end group
@end example
@need 3200

@section 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 @ref{The arch Global Name-space of Projects}).)




@need 3200

@section Comparing Patch Logs to Archives

@geindex whats-missing



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

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

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 @code{Summary:} line of each missing patch with:

@example
@group
        % larch whats-missing --summary [[ARCHIVE/]VERSION ...]
@end group
@group
@end group
@end example

If you want the list to contain fully-qualified patch level names, 
use the @code{--full} option.


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

@example
@group
        % larch get A dir
@end group
@group
@end group
@end example
@example
@group
        % cd dir
@end group
@group
@end group
@end example
@example
@group
        % larch whats-missing B
@end group
@group
@end group
@end example

(It is possible to obtain the same information without having to @code{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.)




@need 3200

@section ChangeLogs

@geindex changelog



The command @code{larch changelog} generates a GNU-style @code{ChangeLog} file from
a patch log:

@example
@group
        % larch changelog
@end group
@group
@end group
@end example

@noindent
or 

@example
@group
        % larch changelog [ARCHIVE/]VERSION
@end group
@group
@end group
@end example

The @code{ChangeLog} file generated for @code{arch}, for example, might begin:

@example
@group
   # do not edit -- automatically generated by arch changelog
   #
   # tag: automatic-ChangeLog--lord@@regexps.com--arch-1/arch--devo--0.5
   #
@end group
@group
@end group
@end example
@example
@group
   2001-12-17  Tom Lord <lord@@regexps.com>
@end group
@group
@end group
@end example
@example
@group
       Summary:
         `update' and `replay' output format and bug fixes
@end group
@group
@end group
@end example
@example
@group
       `udpate' and `replay' -- structured output and updated argument
       processing for reasonable defaults.
@end group
@group
@end group
@end example
@example
@group
       `replay': copy precious files before (not after) appling patches
       so they are carried along with directory renames in patch sets.
@end group
@group
@end group
@end example
@example
@group
       `dopatch': don't pipe `larch heading' into `larch body-indent'.
@end group
@group
@end group
@end example
@example
@group
       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
@end group
@group
@end group
@end example
@example
@group
   2001-12-17  Tom Lord <lord@@regexps.com>
@end group
@group
@end group
@end example
@example
@group
       Summary:
@end group
@group
@end group
@end example
@example
@group
   [...]
@end group
@group
@end group
@end example

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

@example
@group
        ChangeLog
        ChangeLog.*
@end group
@group
@end group
@end example

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


When updating a @code{ChangeLog}, @code{larch commit} looks for a line that says
@code{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
@code{ChangeLog} file always remains on the primary development path.  Each
branch can add its own file:

@example
@group
        ChangeLog.BRANCH--VERSION
@end group
@group
@end group
@end example

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

@example
@group
        % larch tag BRANCH-FROM BRANCH-TO
        [....]
@end group
@group
@end group
@end example
@example
@group
        % larch get BRANCH-TO DIR
        [....]
@end group
@group
@end group
@end example
@example
@group
        % cd DIR
@end group
@group
@end group
@end example
@example
@group
        % larch changelog > ChangeLog.BRANCH-TO
@end group
@group
@end group
@end example
@example
@group
        % larch make-log
        [...edit log file...]
@end group
@group
@end group
@end example
@example
@group
        % larch commit
@end group
@group
@end group
@end example