The Hackerlab at `regexps.com`

## Symbolic Tags

up: arch Meets hello-world next: Cherrypicking Changes prev: Development Branches -- The star-merge Style of Cooperation

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 `hello-world` project has many revisions:

            mainline
            --------
            base-0
            patch-1
            patch-2
            ....
            patch-23

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

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

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

The `tag` command, introduced earlier, can be used for this purpose (see Making a Branch from a Remote Project in a Local Archive).

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

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

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

To create the `snapshot` tag for `patch-23` :

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

after which we'll have:

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

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

            % larch get hello-world--snapshots--0.1

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

            % larch get hello-world--snapshots--0.1--patch-1

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

arch Meets hello-world: A Tutorial Introduction to The arch Revision Control System
The Hackerlab at `regexps.com`