@need 3200

@node Basic Revision Control
@chapter Basic Revision Control

This chapter introduces the fundamental operations for storing
revisions in archives, retrieving them, doing clever things with
patches, and managing project trees for archived projects.

@menu
* The First Revision::
* Successive Revisions::
* Patch Levels and Development Phases::
* Getting a Revision::
* Optimizing Archives for get::
* Finding Out What Changed::
* The whats-missing Command::
* Update::
* Replay::
* The Next Version::
@end menu

@need 3200

@node The First Revision
@section The First Revision

@geindex init-tree



When beginning a new project, the first step is to check in the very
first revision of the tree.


@strong{Prepare the Archive} We've already seen how to prepare the archive by
creating the category, branch, and version for the project (see
@strong{Creating a Development Path} in @ref{Development Paths}).  You have to perform those
steps before checking in the first revision:

@example
@group
        % larch make-category CATEGORY
        % larch make-branch BRANCH
        % larch make-version VERSION
@end group
@group
@end group
@end example

@strong{Prepare the Project Tree} We've also seen how to turn an ordinary
directory into a project tree using the @code{init-tree} command (see
@ref{Initializing a Project Tree}).  And we've seen how to set the
default version of a project tree using @code{set-tree-version} (see
@ref{Labelling Project Trees}).  Both of these steps must be
completed before checking in the first revision:

@example
@group
        % larch init-tree
        % larch set-tree-version VERSION-NAME
@end group
@group
@end group
@end example

In addition, you must create for the project tree a "patch log" --
where log entries for revisions in the development path @code{VERSION-NAME}
will be stored:

@example
@group
        % larch add-log VERSION-NAME
@end group
@group
@end group
@end example

Patch logs are explained in detail in the next chapter.  For now, just
accept the necessity of that command on faith. 


@strong{Prepare a Log Message} In the root of the project tree, the command:

@example
@group
        % larch make-log 
@end group
@group
@end group
@end example

@noindent
creates a template for a log file (look for file whose name begins
with @code{++log}).  The details of what should go in a log message are
project specific.  In general, the format of a log message uses
@code{RFC822} style headers followed by a free-form body.  When @code{arch}
stores a log message, it will add some headers of its own.


@strong{Archive the Tree} Again, in the root of the project tree, use
the @code{import} command to archive the tree:

@example
@group
        % larch import
@end group
@group
@end group
@end example

@code{import} will print the headers of the log message (including headers
added by @code{arch}), store the tree in the archive (as a compressed tar
file), and update the patch log of the working directory to reflect
the commit.


After commiting a revision to, say, @code{hello--devo--1.0}, you can use
the command @code{revisions} to see a list of archived revisions:

@example
@group
        % larch revisions hello--devo--1.0
        base-0
@end group
@group
@end group
@end example

@code{base-0} is the "patch level name" for the first revision.  Patch
levels are described in greater detail below.




@need 3200

@node Successive Revisions
@section Successive Revisions

@geindex revisions



Suppose that you have continued to edit your working directory after
checking in the initial revision.  Successive revisions can be checked
in with the command @code{commit}, issued at the root of the working
directory.  As with @code{import}, you must first use @code{make-log} to
prepare a log message for each commit:

@example
@group
        % larch make-log
@end group
@group
@end group
@end example
@example
@group
        [...edit log message...]
@end group
@group
@end group
@end example
@example
@group
        % larch commit
        [output omitted]
@end group
@group
@end group
@end example

After several commits, you'll have a number of patch levels:

@example
@group
        % larch revisions hello--devo--1.0
        base-0
        patch-1
        patch-2
        patch-3
        ...
@end group
@group
@end group
@end example

As a point of interest, the base revision is stored as a compressed
tar file of the entire tree.  Each @code{patch-N} is stored as a compressed
tar file of just a patch set that describes how to derive that
revision from the previous revision.




@need 3200

@node Patch Levels and Development Phases
@section Patch Levels and Development Phases

Within a version, there is a sequence of revisions, each of which is a
different @geindex patch level
@dfn{patch level}.  Every patch level has a @geindex patch level name
@dfn{patch level name},
derived from the version name by adding a suffix:

@example
@group
        hello--devo--1.0--base-0
        hello--devo--1.0--patch-1
        hello--devo--1.0--patch-2
        hello--devo--1.0--patch-3
        ...
@end group
@group
@end group
@end example

Just as with version names, there is also such a thing as a @geindex fully
qualified patch level name
@dfn{fully
qualified patch level name}:

@example
@group
        joe.hacker@@gnu.org--test-archive/hello--devo--1.0--patch-3
@end group
@group
@end group
@end example

Development within a version may be optionally divided into four
phases: @geindex base revision
@dfn{base revision}, @geindex pre-patches
@dfn{pre-patches}, @geindex version revision
@dfn{version revision}, and
@geindex post-patches
@dfn{post-patches}.  Conceptually, "pre-patches" are revisions made
before the version is "done".  "Post-patches" are revisions made
after the version is done (e.g. "bug fix patches").


At the beginning of a development path is the @geindex base revision
@dfn{base revision}
(called @code{base-0}).  Between the pre-patch and post-patch phases is the
@geindex version revision
@dfn{version revision} (called @code{version-0}).  Post-patches have names like
@code{versionfix-1}, @code{versionfix-2}, etc.


So the total sequence of revisions within a development path has the
form:

@example
@group
        The Initial Revision:
@end group
@group
@end group
@end example
@example
@group
                base-0
@end group
@group
@end group
@end example
@example
@group
        Pre-Patches:
@end group
@group
@end group
@end example
@example
@group
                patch-1
                patch-2
                patch-3
                ...
                patch-N
@end group
@group
@end group
@end example
@example
@group
        The Version Revision:
@end group
@group
@end group
@end example
@example
@group
                version-0
@end group
@group
@end group
@end example
@example
@group
        Post-Patches:
@end group
@group
@end group
@end example
@example
@group
                versionfix-1
                versionfix-2
                versionfix-3
                ...
@end group
@group
@end group
@end example

Typically, the @code{version-0} revision is what would be released under
the version number and the post-patch revisions are fixes made after
the release.


The ordinary @code{commit} command creates pre-patches (@code{patch-N}
revisions).


To create the version revision, use @code{commit --seal}:

@example
@group
        % larch commit --seal
@end group
@group
@end group
@end example

After the version revision exists, ordinary commit will no longer
work.  To create a post-patch revision, use @code{commit --fix}:

@example
@group
        % larch commit --fix
@end group
@group
@end group
@end example

It is perhaps worth mentioning that patch level names can be sorted
easily using:

@example
@group
       sort -t - -k 1,1 -k 2,2n
@end group
@group
@end group
@end example

@noindent
or in reverse:

@example
@group
       sort -t - -k 1,1r -k 2,2rn
@end group
@group
@end group
@end example

If you are familiar with other revision control systems, a four-phased
development process may at first seem somewhat arbitrary and
needlessly complicated.  Two points are worth mentioning:


First, phased development is entirely optional.  Nothing requires you
to ever @code{--seal} a version, and if you never seal a version,
you never need to use @code{--fix}.  Instead, every revision (after
@code{base-0}) will be a @code{patch-N} revision.


Second, phased development is a handy way to prevent accidents when
organizing more complex projects.  Sealing a version is a
way to set a flag that says, in effect, "ordinary development in this
version has stopped -- you might not really want to make a new
revision here."  You can make a new revision if you insist (by
specifying @code{--fix}), but the requirement that you insist helps alert
you to the fact that your new revision might need to be merged with
later versions of the same project; or that that version you are
revising has already been released.  Phased development is a
bookkeeping convenience: for the most part, @code{arch} treats all
revisions equally, regardless of their phase.




@need 3200

@node Getting a Revision
@section Getting a Revision

To retrieve a revision from an archive, use @code{larch get}:

@example
@group
        % larch get REVISION DIR
@end group
@group
@end group
@end example

@noindent
as in:

@example
@group
        % larch get hello--devo--1.0--patch-4 hello
@end group
@group
@end group
@end example

@noindent
to retrieve the revision @code{patch-4} and store it in the new directory
@code{hello}.


An abbreviation can be used to obtain the most recent revision of a
version:

@example
@group
        % larch get hello--devo--1.0 hello
@end group
@group
@end group
@end example

@noindent
or to obtain the most recent revsion of the highest-numbered version:

@example
@group
        % larch get hello--devo hello
@end group
@group
@end group
@end example

A fully-qualified name can be used to obtain a revision from someplace
other than the default archive:

@example
@group
        % larch get joe.hacker@@gnu.org--test-archive/hello--devo
@end group
@group
@end group
@end example



@need 3200

@node Optimizing Archives for get
@section Optimizing Archives for get

The way that @code{get} ordinarilly works is that it searches backwards
from the desired revision to find the nearest full-source base
revision.  It gets the compressed tar file for that base revision and
creates a source tree.  Then, for each intermediate patch level, it
gets a compressed tar file of the patch set, uncompresses and un-tars
the patch-set, and applies the patch-set to the source tree.


If there are many intermediate patch-sets, that process can be slow.  
In such cases, you can ask @code{arch} to cache a full-source copy of an
arbitrary revision, with the command:

@example
@group
        % larch archive-cache-revision [ARCHIVE/]REVISION
@end group
@group
@end group
@end example

That command first builds the requested revision, then it builds a
compressed tar file of the revision, then it stores the tar file back
in the archive.  Subsequent attempts to @code{get} the same revision (or
any later revision) will use the cached tree.


To remove a previously cached tree, use:

@example
@group
        % larch archive-uncache-revision [ARCHIVE/]REVISION
@end group
@group
@end group
@end example

For each user, @code{arch} also maintains a "client side" cache of
revisions that can speed up @code{get} (and other operations).  The details
of client side caching are documented in a later chapter (xref!!!).




@need 3200

@node Finding Out What Changed
@section Finding Out What Changed

@geindex what-changed



Before performing a @code{commit}, you might want to check to see what 
has actually changed -- that is, find out exactly what patch set your
@code{commit} will create.


You can do that with the command @code{what-changed}:

@example
@group
        % larch what-changed
        [...patch set report...]
@end group
@group
@end group
@end example

@code{what-changed} computes a patch set between your modified project tree
and the latest patch level for which your project tree is up-to-date.
In other words, it tells you what changes have been made to your tree
compared to the tree in the archive.


@code{what-changed} leaves behind a directory containing the patch set and
patch report, which you can usefully browse by hand.

@example
@group
    % ls
    ,,what-changed.arch--devo--0.5--patch-14--lord@@regexps.com--arch-1
    [...]
@end group
@group
@end group
@end example

The default output of @code{what-changed} is formatted for use with the
@code{outline} mode of @emph{@strong{GNU Emacs}}.


You can ask @code{what-changed} to also generate an HTML-formatted report
with:

@example
@group
        % larch what-changed --url
        URL of patch report
@end group
@group
@end group
@end example

The HTML report has links to each context diff, added, and removed
file.  The output of the command is a @code{file:} method URL.  For
example, a useful command for @code{netscape} users is:

@example
@group
        % netscape --remote "openURL(`larch what-changed --url`)"
@end group
@group
@end group
@end example



@need 3200

@node The whats-missing Command
@section The whats-missing Command

@geindex whats-missing



Suppose that more than one programmer is checking revisions into a
version, Alice and Bob for example.


Alice and Bob both start with working directories and both make some
changes.  Alice commits several changes.  Now Bob's working directory
has fallen behind archived development path.


The command @code{whats-missing} can be used to tell Bob which patches he
is missing:

@example
@group
        % larch whats-missing --summary
        patch-N
                summary of patch N
        patch-N+1
                summary of patch N+1 
        ...
@end group
@group
@end group
@end example

For each patch that Bob is missing, @code{whats-missing --summary} prints
the name of the patch and the contents of the @code{Summary:} header from
its log message.


The @code{whats-missing} command is explained in greater detail in a later
chapter (see @ref{Patch Logs and ChangeLogs}).




@need 3200

@node Update
@section Update

So Bob is behind by a few patches, but also has his own modifications.


Diagramatically, we have something like:

@example
@group
        Patch Levels    Bob's Working
        in the          Directory
        Archive:
        ------------------------------
@end group
@group
@end group
@end example
@example
@group
        base-0
@end group
@group
@end group
@end example
@example
@group
        patch-1
        patch-2
        patch-3
        patch-4 --------> bob-0 (Bob's initial working directory)
        patch-5             |
        patch-6             |
        patch-7             V
        patch-8           bob-1 (Bob's working dir with changes)
@end group
@group
@end group
@end example

Bob is missing patches five through eight.


The command @code{update} can be used to fix the situation:

@example
@group
        % larch update OLD-DIR NEW-DIR
@end group
@group
@end group
@end example

@noindent
as in:

@example
@group
        % larch update bob-1 bob-2
@end group
@group
@end group
@end example

@code{update} works in several steps.  First, it gets a copy of the latest
revision (@code{patch-8} in this case).  It also gets a copy of the
revision from which @code{OLD-DIR} is dervied (@code{patch-4} in this case).
Then it uses @code{mkpatch} to compute the differences between @code{OLD-DIR} 
and its source revision, and applies those differences (using
@code{dopatch}) to the latest revision.


In the example, update will create the directory @code{bob-2}, with
the source:

@example
@group
        delta(patch-4, bob-1)[patch-8]
@end group
@group
@end group
@end example

(For information about this notation, see @ref{The Theory of Patches and Revisions}.)


Applying that patch might cause conflicts.  In that case, @code{update}
will print a message telling Bob to look for @code{.rej} files.


As a convenience, @code{update} also copies all "precious" non-source
files from @code{OLD-DIR} to @code{NEW-DIR} (see @ref{arch Project Inventories}).


Of course, if Bob only wanted to "partly update", he could do that
with an extra parameter to @code{update}, as in the example:

@example
@group
        # update, but only up to patch level 6:
        # 
@end group
@group
@end group
@end example
@example
@group
        % larch update bob-1 bob-2 hello--devo--1.1--patch-6
@end group
@group
@end group
@end example

Finally, @code{update} can replace @code{OLD-DIR} with the updated directory if
given the @code{--in-place} flag:

@example
@group
        % larch update --in-place OLD-DIR
@end group
@group
@end group
@end example



@need 3200

@node Replay
@section Replay

@code{update} isn't the only way to catch-up with a development path.
Another option is @code{replay}:

@example
@group
        % larch replay old-dir new-dir
@end group
@group
@end group
@end example

Using the same example:

@example
@group
        Patch Levels    Bob's Working
        in the          Directory
        Archive:
        ------------------------------
@end group
@group
@end group
@end example
@example
@group
        base-0
@end group
@group
@end group
@end example
@example
@group
        patch-1
        patch-2
        patch-3
        patch-4 --------> bob-0 (Bob's initial working directory)
        patch-5             |
        patch-6             |
        patch-7             V
        patch-8           bob-1 (Bob's working dir with changes)
@end group
@group
@end group
@end example

@noindent
and the command:

@example
@group
        % larch replay bob-1 bob-2
@end group
@group
@end group
@end example

@code{replay} will first copy @code{bob-1} to create @code{bob-2}.  Then it will
apply each missing patch in succession until @code{bob-2} is up-to-date, or
until a merge conflict occurs.


Thus, if no conflict occurs, @code{replay} computes:

@example
@group
        patch-8 [ patch-7 [ patch-6 [ patch-5 [ bob-1 ]]]]
@end group
@group
@end group
@end example

If a conflict occured in, say, @code{patch-6}, then @code{replay} would compute:

@example
@group
        patch-6 [ patch-5 [ bob-1 ]]
@end group
@group
@end group
@end example

@noindent
and after fixing the conflict, Bob could use a second @code{replay} command
to apply patches seven and eight.


As with @code{update}, @code{replay} also copies all "precious" non-source
files from @code{OLD-DIR} to @code{NEW-DIR} (see @ref{arch Project Inventories}).


Of course, if Bob only wanted to "partly replay", he could do that
with an extra parameter to @code{replay}, as in the example:

@example
@group
        # replay, but only up to patch level 6:
        # 
@end group
@group
@end group
@end example
@example
@group
        % larch replay bob-1 bob-2 hello--devo--1.1--patch-6
@end group
@group
@end group
@end example

You can use @code{replay} to modify an existing directory rather than
creating a new directory:

@example
@group
        % larch replay --in-place DIR [REVISION]
@end group
@group
@end group
@end example

@noindent
but be careful: if @code{DIR} contains precious local changes, and
conflicts occur, or if you simply decide the @code{replay} wasn't a good
idea, you'll have to do some work to revert the @code{replay}.




@need 3200

@node The Next Version
@section The Next Version

In simple situations, a version like @code{hello--devo--1.0} will be
followed by the @geindex next version
@dfn{next version}: @code{hello--devo--1.1} or
@code{hello--devo--2.0}, for example.


Such a version is called a @geindex continuation
@dfn{continuation} of the previous version and
it is created with this sequence of commands (in the root of a working
directory):

@example
@group
        % larch make-version NEXT-VERSION
        % larch add-log NEXT-VERSION
        % larch set-tree-version NEXT-VERSION
        % larch make-log
        [...edit log message...]
        % larch commit --continuation PREVIOUS-VERSION
@end group
@group
@end group
@end example

@noindent
as in:

@example
@group
        % larch make-version hello--devo--1.1
        % larch add-log hello--devo--1.1
        % larch set-tree-version hello--devo--1.1
        % larch make-log
        [...edit log message...]
        % larch commit --continuation hello--devo--1.0
@end group
@group
@end group
@end example

Those commands create the @code{base-0} revision of the new version but
instead of storing complete source for the base revision, they store a
pointer to the older revision which the base revision is equal to.


On the other hand, if you wanted the next version to start completely
from scratch (perhaps because a program is being replaced by an
entirely new implementation), the @code{import} command can create the next
version as documented earlier in this chapter.


Finally, there is another command (besides @code{commit --continuation})
for creating the next version, @code{larch tag}, described in the next
chapter.