Next: , Previous: Selected Files Commit, Up: Working With Arch


4.4 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 in Elementary Branches – Maintaining Private Changes).

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.