|
1
|
<title>Check-in Names</title> |
|
2
|
|
|
3
|
<div class="sidebar no-label"> |
|
4
|
<b>Quick Reference</b> |
|
5
|
<ul> |
|
6
|
<li> Hash prefix |
|
7
|
<li> Branch name |
|
8
|
<li> Tag name |
|
9
|
<li> Timestamp: <i>YYYY-MM-DD HH:MM:SS</i> |
|
10
|
<li> <i>tag-name</i> <big><b>:</b></big> <i>timestamp</i> |
|
11
|
<li> <b>root <big>:</big></b> <i>branchname</i> |
|
12
|
<li> <b>start <big>:</big></b> <i>branchname</i> |
|
13
|
<li> <b>merge-in <big>:</big></b> <i>branchname</i> |
|
14
|
<li> Special names: |
|
15
|
<ul> |
|
16
|
<li> <b>tip</b> |
|
17
|
<li> <b>current</b> |
|
18
|
<li> <b>next</b> |
|
19
|
<li> <b>previous</b> or <b>prev</b> |
|
20
|
<li> <b>ckout</b> (<a href='./embeddeddoc.wiki'>embedded docs</a> only) |
|
21
|
</ul> |
|
22
|
</ul> |
|
23
|
</div> |
|
24
|
|
|
25
|
Many Fossil [/help|commands] and [./webui.wiki | web interface] URLs accept |
|
26
|
check-in names as an argument. For example, the "[/help/info|info]" command |
|
27
|
accepts an optional check-in name to identify the specific check-in |
|
28
|
about which information is desired: |
|
29
|
|
|
30
|
<pre style="white-space: pre-wrap"> |
|
31
|
fossil info <i>checkin-name</i> |
|
32
|
</pre> |
|
33
|
|
|
34
|
You are perhaps reading this page from the following URL: |
|
35
|
|
|
36
|
<verbatim> |
|
37
|
https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki |
|
38
|
</verbatim> |
|
39
|
|
|
40
|
This is an example of an [./embeddeddoc.wiki | embedded documentation] |
|
41
|
page URL. The "trunk" element of the pathname is a |
|
42
|
[./glossary.md#check-in | check-in] name that |
|
43
|
determines which version of the documentation to display. |
|
44
|
|
|
45
|
Fossil provides a variety of ways to specify a check-in. This |
|
46
|
document describes the various methods. |
|
47
|
|
|
48
|
<h2 id="canonical">Canonical Check-in Name</h2> |
|
49
|
|
|
50
|
The canonical name of a check-in is the hash of its |
|
51
|
[./fileformat.wiki#manifest | manifest] expressed as a |
|
52
|
[./hashes.md | long lowercase hexadecimal number]. For example: |
|
53
|
|
|
54
|
<pre> |
|
55
|
fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9 |
|
56
|
</pre> |
|
57
|
|
|
58
|
The full 40 or 64 character hash is unwieldy to remember and type, though, |
|
59
|
so Fossil also accepts a unique prefix of the hash, using any combination |
|
60
|
of upper and lower case letters, as long as the prefix is at least 4 |
|
61
|
characters long. Hence the following commands all |
|
62
|
accomplish the same thing as the above: |
|
63
|
|
|
64
|
<pre> |
|
65
|
fossil info e5a734a19a9 |
|
66
|
fossil info E5a734A |
|
67
|
fossil info e5a7 |
|
68
|
</pre> |
|
69
|
|
|
70
|
Fossil uses this feature itself, identifying check-ins by 8 to 16-character |
|
71
|
prefixes of the canonical name in places where it doesn't want to chew |
|
72
|
up the screen real estate required to display the whole hash. |
|
73
|
|
|
74
|
<h2 id="tags">Tags And Branch Names</h2> |
|
75
|
|
|
76
|
Using a tag or branch name where a check-in name is expected causes |
|
77
|
Fossil to choose the most recent check-in with that tag or branch name. |
|
78
|
So for example, the most recent check-in that |
|
79
|
is tagged with "release" as of this writing is [b98ce23d4fc]. |
|
80
|
The command: |
|
81
|
|
|
82
|
<pre> |
|
83
|
fossil info release |
|
84
|
</pre> |
|
85
|
|
|
86
|
…results in the following output: |
|
87
|
|
|
88
|
<pre> |
|
89
|
hash: b98ce23d4fc3b734cdc058ee8a67e6dad675ca13 2020-08-20 13:27:04 UTC |
|
90
|
parent: 40feec329163103293d98dfcc2d119d1a16b227a 2020-08-20 13:01:51 UTC |
|
91
|
tags: release, branch-2.12, version-2.12.1 |
|
92
|
comment: Version 2.12.1 (user: drh) |
|
93
|
</pre> |
|
94
|
|
|
95
|
There are multiple check-ins that are tagged with "release" but |
|
96
|
(as of this writing) the [b98ce23d4fc] |
|
97
|
check-in is the most recent so it is the one that is selected. |
|
98
|
|
|
99
|
Note that unlike some other version control systems, a "branch" in Fossil |
|
100
|
is not anything special: it is simply a sequence of check-ins that |
|
101
|
share a common tag, so the same mechanism that resolves tag names |
|
102
|
also resolves branch names. |
|
103
|
|
|
104
|
<a id="tagpfx"></a> |
|
105
|
Note also that there can — in theory, if rarely in practice — be an ambiguity |
|
106
|
between tag names and canonical names. Suppose, for example, you had a |
|
107
|
check-in with the canonical name deed28aa99… and you |
|
108
|
also happened to have tagged a different check-in with "deed2". If |
|
109
|
you use the "deed2" name, does it choose the canonical name or the tag |
|
110
|
name? In such cases, you can prefix the tag name with "tag:". |
|
111
|
For example: |
|
112
|
|
|
113
|
<pre> |
|
114
|
fossil info tag:deed2 |
|
115
|
</pre> |
|
116
|
|
|
117
|
The "tag:deed2" name will refer to the most recent check-in |
|
118
|
tagged with "deed2" rather than the |
|
119
|
check-in whose canonical name begins with "deed2". |
|
120
|
|
|
121
|
<h2 id="whole-branches">Whole Branches</h2> |
|
122
|
|
|
123
|
Usually when a branch name is specified, it means the latest check-in on |
|
124
|
that branch, but for some commands (ex: [/help/purge|purge]) a branch name |
|
125
|
on the argument means the earliest connected check-in on the branch. This |
|
126
|
seems confusing when being explained here, but it works out to be intuitive |
|
127
|
in practice. |
|
128
|
|
|
129
|
For example, the command "fossil purge XYZ" means to purge the check-in XYZ |
|
130
|
and all of its descendants. But when XYZ is in the form of a branch name, one |
|
131
|
generally wants to purge the entire branch, not just the last check-in on the |
|
132
|
branch. And so for this reason, commands like purge will interpret a branch |
|
133
|
name to be the first check-in of the branch rather than the last. If there |
|
134
|
are two or more branches with the same name, then these commands will select |
|
135
|
the first check-in of the branch that has the most recent check-in. What |
|
136
|
happens is that Fossil searches for the most recent check-in with the given |
|
137
|
tag, just as it always does. But if that tag is a branch name, it then walks |
|
138
|
back down the branch looking for the first check-in of that branch. |
|
139
|
|
|
140
|
Again, this behavior only occurs on a few commands where it make sense. |
|
141
|
|
|
142
|
<h2 id="timestamps">Timestamps</h2> |
|
143
|
|
|
144
|
A timestamp in one of the formats shown below means the most recent |
|
145
|
check-in that occurs no later than the timestamp given: |
|
146
|
|
|
147
|
1. <i>YYYY-MM-DD</i> |
|
148
|
2. <i>YYYY-MM-DD HH:MM</i> |
|
149
|
3. <i>YYYY-MM-DD HH:MM:SS</i> |
|
150
|
4. <i>YYYY-MM-DD HH:MM:SS.SSS</i> |
|
151
|
5. <i>YYYYMMDD</i> |
|
152
|
6. <i>YYYYMMDDHHMM</i> |
|
153
|
7. <i>YYYYMMDDHHMMSS</i> |
|
154
|
|
|
155
|
In the second through the fourth forms, |
|
156
|
the space between the day and the year can optionally be |
|
157
|
replaced by an uppercase <b>T</b>, and the entire timestamp can |
|
158
|
optionally be followed by "<b>z</b>" or "<b>Z</b>". In the fourth |
|
159
|
form with fractional seconds, any number of digits may follow the |
|
160
|
decimal point, though due to precision limits only the first three |
|
161
|
digits will be significant. The final three pure-digit forms |
|
162
|
without punctuation are only valid if the number they encode is |
|
163
|
not also the prefix of an artifact hash. |
|
164
|
|
|
165
|
In its default configuration, Fossil interprets and displays all dates |
|
166
|
in Universal Coordinated Time (UTC). This tends to work the best for |
|
167
|
distributed projects where participants are scattered around the globe. |
|
168
|
But there is an option on the Admin/Timeline page of the web interface to |
|
169
|
switch to local time. The "<b>Z</b>" suffix on a timestamp check-in |
|
170
|
name is meaningless if Fossil is in the default mode of using UTC for |
|
171
|
everything, but if Fossil has been switched to local time mode, then the |
|
172
|
"<b>Z</b>" suffix means to interpret that particular timestamp using |
|
173
|
UTC instead of local time. |
|
174
|
|
|
175
|
You may prefix a timestamp with the string “date:”, in which case |
|
176
|
processing stops immediately, whether the string is parsed correctly and |
|
177
|
refers to anything within the repository or not. The prefix is therefore |
|
178
|
useful when the date could be misinterpreted as a tag. For example, a |
|
179
|
repo could have release tags like “2020-04-01”, the date the release was |
|
180
|
cut, but you could force Fossil to interpret that string as a date |
|
181
|
rather than as a tag by passing “date:2020-04-01”. |
|
182
|
|
|
183
|
For an example of how timestamps are useful, |
|
184
|
consider the homepage for the Fossil website itself: |
|
185
|
|
|
186
|
<pre> |
|
187
|
https://fossil-scm.org/home/doc/<b>trunk</b>/www/index.wiki |
|
188
|
</pre> |
|
189
|
|
|
190
|
The bold component of that URL is a check-in name. To see the stored content |
|
191
|
of the Fossil website repository as of January 1, 2009, one has merely to change |
|
192
|
the URL to the following: |
|
193
|
|
|
194
|
<pre> |
|
195
|
https://fossil-scm.org/home/doc/<b>2009-01-01</b>/www/index.wiki |
|
196
|
</pre> |
|
197
|
|
|
198
|
(Note that this won't roll you back to the <i>skin</i> and other |
|
199
|
cosmetic configurations as of that date. It also won't change screens |
|
200
|
like the timeline, which has an independent date selector.) |
|
201
|
|
|
202
|
<h2 id="tag-ts">Tag And Timestamp</h2> |
|
203
|
|
|
204
|
A check-in name can also take the form of a tag or branch name followed by |
|
205
|
a colon and then a timestamp. The combination means to take the most |
|
206
|
recent check-in with the given tag or branch which is not more recent than |
|
207
|
the timestamp. So, for example: |
|
208
|
|
|
209
|
<pre> |
|
210
|
fossil update trunk:2010-07-01T14:30 |
|
211
|
</pre> |
|
212
|
|
|
213
|
Would cause Fossil to update the working check-out to be the most recent |
|
214
|
check-in on the trunk that is not more recent than 14:30 (UTC) on |
|
215
|
July 1, 2010. |
|
216
|
|
|
217
|
<h2 id="root">Root Of A Branch</h2> |
|
218
|
|
|
219
|
A branch name that begins with the "<tt>root:</tt>" prefix refers to the |
|
220
|
last check-in on the parent branch prior to the beginning of the branch. |
|
221
|
Such a label is useful, for example, in computing all diffs for a single |
|
222
|
branch. The following example will show all changes in the hypothetical |
|
223
|
branch "xyzzy": |
|
224
|
|
|
225
|
<pre> |
|
226
|
fossil diff --from root:xyzzy --to xyzzy |
|
227
|
</pre> |
|
228
|
|
|
229
|
<a id="merge-in"></a> |
|
230
|
That doesn't do what you might expect after you merge the parent |
|
231
|
branch's changes into the child branch: the above command will include |
|
232
|
changes made on the parent branch as well. |
|
233
|
|
|
234
|
You can solve this by using the prefix "<tt>merge-in:</tt>" instead of |
|
235
|
"<tt>root:</tt>" to tell Fossil to find |
|
236
|
the most recent merge-in point for that branch. |
|
237
|
The resulting diff will then show only the changes in |
|
238
|
the branch itself, omitting |
|
239
|
any changes that have already been merged in from the parent branch. |
|
240
|
|
|
241
|
<a id="start"></a> |
|
242
|
The prefix "<tt>start:</tt>" gives the first check-in of the named branch. |
|
243
|
|
|
244
|
The prefixes "<tt>root:</tt>", "<tt>start:</tt>", and "<tt>merge-in:</tt>" |
|
245
|
can be chained: one can say for example |
|
246
|
|
|
247
|
<pre> |
|
248
|
fossil info merge-in:xyzzy:2022-03-01 |
|
249
|
</pre> |
|
250
|
|
|
251
|
to get information about the most recent merge-in point on the branch |
|
252
|
"xyzzy" that happened on or before March 1, 2022. |
|
253
|
|
|
254
|
<h2 id="special">Special Tags</h2> |
|
255
|
|
|
256
|
The tag "tip" means the most recent check-in. The "tip" tag is practically |
|
257
|
equivalent to the timestamp "9999-12-31". |
|
258
|
|
|
259
|
This special name works anywhere you can pass a "NAME", such as with |
|
260
|
<tt>/info</tt> URLs: |
|
261
|
|
|
262
|
<pre> |
|
263
|
http://localhost:8080/info/tip |
|
264
|
</pre> |
|
265
|
|
|
266
|
There are several other special names, but they only work from within a |
|
267
|
check-out directory because they are relative to the current checked-out |
|
268
|
version: |
|
269
|
|
|
270
|
* "current": the current checked-out version |
|
271
|
* "next": the youngest child of the current checked-out version |
|
272
|
* "previous" or "prev": the primary (non-merge) parent of "current" |
|
273
|
|
|
274
|
Therefore, you can use these names in a <tt>fossil info</tt> command, |
|
275
|
but not in an <tt>/info</tt> URL, for example. |
|
276
|
|
|
277
|
For embedded documentation URLs only, there is one more special name, |
|
278
|
"ckout". See [./embeddeddoc.wiki#ckout | its coverage elsewhere] for |
|
279
|
more details. You cannot currently use "ckout" anywhere other than in |
|
280
|
<tt>/doc</tt> URLs. |
|
281
|
|
|
282
|
|
|
283
|
<h2 id="examples">Additional Examples</h2> |
|
284
|
|
|
285
|
To view the changes in the most recent check-in prior to the version currently |
|
286
|
checked out: |
|
287
|
|
|
288
|
<pre> |
|
289
|
fossil diff --from previous --to current |
|
290
|
</pre> |
|
291
|
|
|
292
|
Suppose you are of the habit of tagging each release with a "release" tag. |
|
293
|
Then to see everything that has changed on the trunk since the last release: |
|
294
|
|
|
295
|
<pre> |
|
296
|
fossil diff --from release --to trunk |
|
297
|
</pre> |
|
298
|
|
|
299
|
|
|
300
|
<h2 id="order">Resolution Order</h2> |
|
301
|
|
|
302
|
Fossil currently resolves name strings to artifact hashes in the |
|
303
|
following order: |
|
304
|
|
|
305
|
# Exact matches on [#special | the special names] |
|
306
|
# [#timestamps | Timestamps], with preference to ISO8601 forms |
|
307
|
# [#tagpfx | tag:TAGNAME] |
|
308
|
# [#root | root:BRANCH] |
|
309
|
# [#start | start:BRANCH] |
|
310
|
# [#merge-in | merge-in:BRANCH] |
|
311
|
# [#tag-ts | TAGNAME:timestamp] |
|
312
|
# Full artifact hash or hash prefix. |
|
313
|
# Any other type of symbolic name that Fossil extracts from |
|
314
|
artifacts. |
|
315
|
|
|
316
|
<div style="height:50em" id="this-space-intentionally-left-blank"></div> |
|
317
|
|