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 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 :

        % tla 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:

        % tla get hello-world--snapshots--0.1

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

        % tla 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.