@need 3200

@node Symbolic Tags
@chapter Symbolic Tags

As projects grow larger and more complicated, it is often useful
to be able to give a symbolic name to particular revisions within an
arch version.


For example, let's suppose that the @code{hello-world} project has many
revisions:

@example
@group

@end group
@group
        mainline
        --------
        base-0
        patch-1
        patch-2
        ....
        patch-23
@end group
@group


@end group
@end example

It may be that, as development proceeds, occasional "snapshot"
releases are made from the @code{mainline}.  Not every revision becomes a
snapshot, but some do.


It would be convenient to provide a label of which revisions became
snapshots:

@example
@group

@end group
@group
        mainline
        --------
        base-0
        patch-1         snapshot 0
        patch-2
        ....
        patch-12        snapshot 2
        ....
        patch-23        snapshot 3
@end group
@group


@end group
@end example

The @code{tag} command, introduced earlier, can be used for this purpose
(see @strong{Making a Branch from a Remote Project in a Local Archive} in @ref{Elementary Branches -- Maintaining Private Changes}).


When we first encountered @code{tag}, it was used just to create the
@code{base-0} revision of an elementary branch.   It can also be used to
create a branch @emph{all} of whose revisions are tags.


Let's suppose that we'll be creating a branch called
@code{hello-world--snapshots--0.1}.  Diagramatically, we'll have:

@example
@group

@end group
@group
        mainline                        snapshots
        --------                        ---------
        base-0                --------> base-0 (tag)
        patch-1 -------------'  ------> patch-1 (tag)
        patch-2                '
        ....                  '
        patch-12 ------------'
        ....
        patch-23
@end group
@group

@end group
@end example

To create the @code{snapshot} tag for @code{patch-23}:

@example
@group

@end group
@group
        % larch tag hello-world--mainline--0.1--patch-23 \
                    hello-world--snapshots--0.1
@end group
@group

@end group
@end example

@noindent
after which we'll have:

@example
@group

@end group
@group
        mainline                        snapshots
        --------                        ---------
        base-0                --------> base-0 (tag)
        patch-1 -------------'  ------> patch-1 (tag)
        patch-2                ' -----> patch-2 (tag)
        ....                  ' '
        patch-12 ------------' '
        ....                  '
        patch-23 ------------'
@end group
@group

@end group
@end example

In effect, the @code{snapshots} branch is a kind of "symbolic name" with
history.   We can get the latest revision named by that symbol with:

@example
@group
        % larch get hello-world--snapshots--0.1
@end group
@group
@end group
@end example

@noindent
and earlier revisions by naming specific revisions, e.g.:

@example
@group
        % larch get hello-world--snapshots--0.1--patch-1
@end group
@group
@end group
@end example

@strong{Usage Caution:} As a rule of thumb, your branches should be either
@code{commit} based branches (all revisions after @code{base-0} are created by
@code{commit}) or tag-based branches (all revisions are created by @code{tag}).
Commands such as @code{replay}, @code{update}, and @code{star-merge} are based on the
presumption that you stick to that rule.  While it can be tempting, in
obscure circumstances, to mix @code{commit} and @code{tag} on a single branch --
it isn't generally recommended.




