<title>Check-in Names</title>
<div class="sidebar no-label">
<b>Quick Reference</b>
<ul>
<li> Hash prefix
<li> Branch name
<li> Tag name
<li> Timestamp: <i>YYYY-MM-DD HH:MM:SS</i>
<li> <i>tag-name</i> <big><b>:</b></big> <i>timestamp</i>
<li> <b>root <big>:</big></b> <i>branchname</i>
<li> <b>start <big>:</big></b> <i>branchname</i>
<li> <b>merge-in <big>:</big></b> <i>branchname</i>
<li> Special names:
<ul>
<li> <b>tip</b>
<li> <b>current</b>
<li> <b>next</b>
<li> <b>previous</b> or <b>prev</b>
<li> <b>ckout</b> (<a href='./embeddeddoc.wiki'>embedded docs</a> only)
</ul>
</ul>
</div>
Many Fossil [/help|commands] and [./webui.wiki | web interface] URLs accept
check-in names as an argument. For example, the "[/help/info|info]" command
accepts an optional check-in name to identify the specific check-in
about which information is desired:
<pre style="white-space: pre-wrap">
fossil info <i>checkin-name</i>
</pre>
You are perhaps reading this page from the following URL:
<verbatim>
https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki
</verbatim>
This is an example of an [./embeddeddoc.wiki | embedded documentation]
page URL. The "trunk" element of the pathname is a
[./glossary.md#check-in | check-in] name that
determines which version of the documentation to display.
Fossil provides a variety of ways to specify a check-in. This
document describes the various methods.
<h2 id="canonical">Canonical Check-in Name</h2>
The canonical name of a check-in is the hash of its
[./fileformat.wiki#manifest | manifest] expressed as a
[./hashes.md | long lowercase hexadecimal number]. For example:
<pre>
fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9
</pre>
The full 40 or 64 character hash is unwieldy to remember and type, though,
so Fossil also accepts a unique prefix of the hash, using any combination
of upper and lower case letters, as long as the prefix is at least 4
characters long. Hence the following commands all
accomplish the same thing as the above:
<pre>
fossil info e5a734a19a9
fossil info E5a734A
fossil info e5a7
</pre>
Fossil uses this feature itself, identifying check-ins by 8 to 16-character
prefixes of the canonical name in places where it doesn't want to chew
up the screen real estate required to display the whole hash.
<h2 id="tags">Tags And Branch Names</h2>
Using a tag or branch name where a check-in name is expected causes
Fossil to choose the most recent check-in with that tag or branch name.
So for example, the most recent check-in that
is tagged with "release" as of this writing is [b98ce23d4fc].
The command:
<pre>
fossil info release
</pre>
…results in the following output:
<pre>
hash: b98ce23d4fc3b734cdc058ee8a67e6dad675ca13 2020-08-20 13:27:04 UTC
parent: 40feec329163103293d98dfcc2d119d1a16b227a 2020-08-20 13:01:51 UTC
tags: release, branch-2.12, version-2.12.1
comment: Version 2.12.1 (user: drh)
</pre>
There are multiple check-ins that are tagged with "release" but
(as of this writing) the [b98ce23d4fc]
check-in is the most recent so it is the one that is selected.
Note that unlike some other version control systems, a "branch" in Fossil
is not anything special: it is simply a sequence of check-ins that
share a common tag, so the same mechanism that resolves tag names
also resolves branch names.
<a id="tagpfx"></a>
Note also that there can — in theory, if rarely in practice — be an ambiguity
between tag names and canonical names. Suppose, for example, you had a
check-in with the canonical name deed28aa99… and you
also happened to have tagged a different check-in with "deed2". If
you use the "deed2" name, does it choose the canonical name or the tag
name? In such cases, you can prefix the tag name with "tag:".
For example:
<pre>
fossil info tag:deed2
</pre>
The "tag:deed2" name will refer to the most recent check-in
tagged with "deed2" rather than the
check-in whose canonical name begins with "deed2".
<h2 id="whole-branches">Whole Branches</h2>
Usually when a branch name is specified, it means the latest check-in on
that branch, but for some commands (ex: [/help/purge|purge]) a branch name
on the argument means the earliest connected check-in on the branch. This
seems confusing when being explained here, but it works out to be intuitive
in practice.
For example, the command "fossil purge XYZ" means to purge the check-in XYZ
and all of its descendants. But when XYZ is in the form of a branch name, one
generally wants to purge the entire branch, not just the last check-in on the
branch. And so for this reason, commands like purge will interpret a branch
name to be the first check-in of the branch rather than the last. If there
are two or more branches with the same name, then these commands will select
the first check-in of the branch that has the most recent check-in. What
happens is that Fossil searches for the most recent check-in with the given
tag, just as it always does. But if that tag is a branch name, it then walks
back down the branch looking for the first check-in of that branch.
Again, this behavior only occurs on a few commands where it make sense.
<h2 id="timestamps">Timestamps</h2>
A timestamp in one of the formats shown below means the most recent
check-in that occurs no later than the timestamp given:
1. <i>YYYY-MM-DD</i>
2. <i>YYYY-MM-DD HH:MM</i>
3. <i>YYYY-MM-DD HH:MM:SS</i>
4. <i>YYYY-MM-DD HH:MM:SS.SSS</i>
5. <i>YYYYMMDD</i>
6. <i>YYYYMMDDHHMM</i>
7. <i>YYYYMMDDHHMMSS</i>
In the second through the fourth forms,
the space between the day and the year can optionally be
replaced by an uppercase <b>T</b>, and the entire timestamp can
optionally be followed by "<b>z</b>" or "<b>Z</b>". In the fourth
form with fractional seconds, any number of digits may follow the
decimal point, though due to precision limits only the first three
digits will be significant. The final three pure-digit forms
without punctuation are only valid if the number they encode is
not also the prefix of an artifact hash.
In its default configuration, Fossil interprets and displays all dates
in Universal Coordinated Time (UTC). This tends to work the best for
distributed projects where participants are scattered around the globe.
But there is an option on the Admin/Timeline page of the web interface to
switch to local time. The "<b>Z</b>" suffix on a timestamp check-in
name is meaningless if Fossil is in the default mode of using UTC for
everything, but if Fossil has been switched to local time mode, then the
"<b>Z</b>" suffix means to interpret that particular timestamp using
UTC instead of local time.
You may prefix a timestamp with the string “date:”, in which case
processing stops immediately, whether the string is parsed correctly and
refers to anything within the repository or not. The prefix is therefore
useful when the date could be misinterpreted as a tag. For example, a
repo could have release tags like “2020-04-01”, the date the release was
cut, but you could force Fossil to interpret that string as a date
rather than as a tag by passing “date:2020-04-01”.
For an example of how timestamps are useful,
consider the homepage for the Fossil website itself:
<pre>
https://fossil-scm.org/home/doc/<b>trunk</b>/www/index.wiki
</pre>
The bold component of that URL is a check-in name. To see the stored content
of the Fossil website repository as of January 1, 2009, one has merely to change
the URL to the following:
<pre>
https://fossil-scm.org/home/doc/<b>2009-01-01</b>/www/index.wiki
</pre>
(Note that this won't roll you back to the <i>skin</i> and other
cosmetic configurations as of that date. It also won't change screens
like the timeline, which has an independent date selector.)
<h2 id="tag-ts">Tag And Timestamp</h2>
A check-in name can also take the form of a tag or branch name followed by
a colon and then a timestamp. The combination means to take the most
recent check-in with the given tag or branch which is not more recent than
the timestamp. So, for example:
<pre>
fossil update trunk:2010-07-01T14:30
</pre>
Would cause Fossil to update the working check-out to be the most recent
check-in on the trunk that is not more recent than 14:30 (UTC) on
July 1, 2010.
<h2 id="root">Root Of A Branch</h2>
A branch name that begins with the "<tt>root:</tt>" prefix refers to the
last check-in on the parent branch prior to the beginning of the branch.
Such a label is useful, for example, in computing all diffs for a single
branch. The following example will show all changes in the hypothetical
branch "xyzzy":
<pre>
fossil diff --from root:xyzzy --to xyzzy
</pre>
<a id="merge-in"></a>
That doesn't do what you might expect after you merge the parent
branch's changes into the child branch: the above command will include
changes made on the parent branch as well.
You can solve this by using the prefix "<tt>merge-in:</tt>" instead of
"<tt>root:</tt>" to tell Fossil to find
the most recent merge-in point for that branch.
The resulting diff will then show only the changes in
the branch itself, omitting
any changes that have already been merged in from the parent branch.
<a id="start"></a>
The prefix "<tt>start:</tt>" gives the first check-in of the named branch.
The prefixes "<tt>root:</tt>", "<tt>start:</tt>", and "<tt>merge-in:</tt>"
can be chained: one can say for example
<pre>
fossil info merge-in:xyzzy:2022-03-01
</pre>
to get informations about the most recent merge-in point on the branch
"xyzzy" that happened on or before March 1, 2022.
<h2 id="special">Special Tags</h2>
The tag "tip" means the most recent check-in. The "tip" tag is practically
equivalent to the timestamp "9999-12-31".
This special name works anywhere you can pass a "NAME", such as with
<tt>/info</tt> URLs:
<pre>
http://localhost:8080/info/tip
</pre>
There are several other special names, but they only work from within a
check-out directory because they are relative to the current checked-out
version:
* "current": the current checked-out version
* "next": the youngest child of the current checked-out version
* "previous" or "prev": the primary (non-merge) parent of "current"
Therefore, you can use these names in a <tt>fossil info</tt> command,
but not in an <tt>/info</tt> URL, for example.
For embedded documentation URLs only, there is one more special name,
"ckout". See [./embeddeddoc.wiki#ckout | its coverage elsewhere] for
more details. You cannot currently use "ckout" anywhere other than in
<tt>/doc</tt> URLs.
<h2 id="examples">Additional Examples</h2>
To view the changes in the most recent check-in prior to the version currently
checked out:
<pre>
fossil diff --from previous --to current
</pre>
Suppose you are of the habit of tagging each release with a "release" tag.
Then to see everything that has changed on the trunk since the last release:
<pre>
fossil diff --from release --to trunk
</pre>
<h2 id="order">Resolution Order</h2>
Fossil currently resolves name strings to artifact hashes in the
following order:
# Exact matches on [#special | the special names]
# [#timestamps | Timestamps], with preference to ISO8601 forms
# [#tagpfx | tag:TAGNAME]
# [#root | root:BRANCH]
# [#start | start:BRANCH]
# [#merge-in | merge-in:BRANCH]
# [#tag-ts | TAGNAME:timestamp]
# Full artifact hash or hash prefix.
# Any other type of symbolic name that Fossil extracts from
artifacts.
<div style="height:50em" id="this-space-intentionally-left-blank"></div>