← Back to branch summary

~ubuntu-branches/ubuntu/trusty/tla/trusty

« back to all changes in this revision

Viewing changes to src/docs-tla/texi/symbolic-tags.texi

  • Committer: Bazaar Package Importer
  • Author(s): Andrew Suffield
  • Date: 2004-05-30 20:13:29 UTC
  • Revision ID: james.westby@ubuntu.com-20040530201329-mgovd2u99mkxi0hf
Tags: upstream-1.2
Import upstream version 1.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/docs-tla/texi/symbolic-tags.texi
 
1
@need 3200
 
2
 
 
3
@node Symbolic Tags
 
4
@chapter Symbolic Tags
 
5
 
 
6
As projects grow larger and more complicated, it is often useful
 
7
to be able to give a symbolic name to particular revisions within an
 
8
arch version.
 
9
 
 
10
 
 
11
For example, let's suppose that the @code{hello-world} project has many
 
12
revisions:
 
13
 
 
14
@example
 
15
@group
 
16
 
 
17
@end group
 
18
@group
 
19
        mainline
 
20
        --------
 
21
        base-0
 
22
        patch-1
 
23
        patch-2
 
24
        ....
 
25
        patch-23
 
26
@end group
 
27
@group
 
28
 
 
29
 
 
30
@end group
 
31
@end example
 
32
 
 
33
It may be that, as development proceeds, occasional "snapshot"
 
34
releases are made from the @code{mainline}.  Not every revision becomes a
 
35
snapshot, but some do.
 
36
 
 
37
 
 
38
It would be convenient to provide a label of which revisions became
 
39
snapshots:
 
40
 
 
41
@example
 
42
@group
 
43
 
 
44
@end group
 
45
@group
 
46
        mainline
 
47
        --------
 
48
        base-0
 
49
        patch-1         snapshot 0
 
50
        patch-2
 
51
        ....
 
52
        patch-12        snapshot 2
 
53
        ....
 
54
        patch-23        snapshot 3
 
55
@end group
 
56
@group
 
57
 
 
58
 
 
59
@end group
 
60
@end example
 
61
 
 
62
The @code{tag} command, introduced earlier, can be used for this purpose
 
63
(see @strong{Making a Branch from a Remote Project in a Local Archive} in @ref{Elementary Branches -- Maintaining Private Changes}).
 
64
 
 
65
 
 
66
When we first encountered @code{tag}, it was used just to create the
 
67
@code{base-0} revision of an elementary branch.   It can also be used to
 
68
create a branch @emph{all} of whose revisions are tags.
 
69
 
 
70
 
 
71
Let's suppose that we'll be creating a branch called
 
72
@code{hello-world--snapshots--0.1}.  Diagramatically, we'll have:
 
73
 
 
74
@example
 
75
@group
 
76
 
 
77
@end group
 
78
@group
 
79
        mainline                        snapshots
 
80
        --------                        ---------
 
81
        base-0                --------> base-0 (tag)
 
82
        patch-1 -------------'  ------> patch-1 (tag)
 
83
        patch-2                '
 
84
        ....                  '
 
85
        patch-12 ------------'
 
86
        ....
 
87
        patch-23
 
88
@end group
 
89
@group
 
90
 
 
91
@end group
 
92
@end example
 
93
 
 
94
To create the @code{snapshot} tag for @code{patch-23}:
 
95
 
 
96
@example
 
97
@group
 
98
 
 
99
@end group
 
100
@group
 
101
        % tla tag hello-world--mainline--0.1--patch-23 \
 
102
                    hello-world--snapshots--0.1
 
103
@end group
 
104
@group
 
105
 
 
106
@end group
 
107
@end example
 
108
 
 
109
@noindent
 
110
after which we'll have:
 
111
 
 
112
@example
 
113
@group
 
114
 
 
115
@end group
 
116
@group
 
117
        mainline                        snapshots
 
118
        --------                        ---------
 
119
        base-0                --------> base-0 (tag)
 
120
        patch-1 -------------'  ------> patch-1 (tag)
 
121
        patch-2                ' -----> patch-2 (tag)
 
122
        ....                  ' '
 
123
        patch-12 ------------' '
 
124
        ....                  '
 
125
        patch-23 ------------'
 
126
@end group
 
127
@group
 
128
 
 
129
@end group
 
130
@end example
 
131
 
 
132
In effect, the @code{snapshots} branch is a kind of "symbolic name" with
 
133
history.   We can get the latest revision named by that symbol with:
 
134
 
 
135
@example
 
136
@group
 
137
        % tla get hello-world--snapshots--0.1
 
138
@end group
 
139
@group
 
140
@end group
 
141
@end example
 
142
 
 
143
@noindent
 
144
and earlier revisions by naming specific revisions, e.g.:
 
145
 
 
146
@example
 
147
@group
 
148
        % tla get hello-world--snapshots--0.1--patch-1
 
149
@end group
 
150
@group
 
151
@end group
 
152
@end example
 
153
 
 
154
@strong{Usage Caution:} As a rule of thumb, your branches should be either
 
155
@code{commit} based branches (all revisions after @code{base-0} are created by
 
156
@code{commit}) or tag-based branches (all revisions are created by @code{tag}).
 
157
Commands such as @code{replay}, @code{update}, and @code{star-merge} are based on the
 
158
presumption that you stick to that rule.  While it can be tempting, in
 
159
obscure circumstances, to mix @code{commit} and @code{tag} on a single branch --
 
160
it isn't generally recommended.
 
161
 
 
162
 
 
163
 
 
164