Fossil

<title>Check-in Names</title>

<table align="right" width="33%">
<tr><td>
<h3>Quick Reference</h3>
<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>
</td></tr>
</table>

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:

<blockquote>
<tt>fossil info</tt> <i>checkin-name</i>
</blockquote>

You are perhaps reading this page from the following URL:

<blockquote>
https://fossil-scm.org/home/doc/<b>trunk</b>/www/checkin_names.wiki
</blockquote>

The URL above is an example of an [./embeddeddoc.wiki | embedded documentation]
page in Fossil.  The bold term of the pathname is a 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:

<blockquote><pre>
fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9
</pre></blockquote>

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:

<blockquote><pre>
fossil info e5a734a19a9
fossil info E5a734A
fossil info e5a7
</blockquote>

Many web interface screens identify check-ins by 10- or 16-character
prefix of canonical name.


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

<blockquote><pre>
fossil info release
</pre></blockquote>

…results in the following output:

<blockquote><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></blockquote>

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:

<blockquote><tt>
fossil info tag:deed2
</tt></blockquote>

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>

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:

<blockquote>
https://fossil-scm.org/home/doc/<b>trunk</b>/www/index.wiki
</blockquote>

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:

<blockquote>
https://fossil-scm.org/home/doc/<b>2009-01-01</b>/www/index.wiki
</blockquote>

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

<blockquote><tt>
fossil update trunk:2010-07-01T14:30
</tt></blockquote>

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

<blockquote><tt>
fossil diff --from root:xyzzy --to xyzzy
</tt></blockquote>

<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 

<blockquote><tt>
fossil info merge-in:xyzzy:2022-03-01
</tt></blockquote>

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:

<blockquote><pre>
http://localhost:8080/info/tip
</pre></blockquote>

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

<h2 id="examples">Additional Examples</h2>

To view the changes in the most recent check-in prior to the version currently
checked out:

<blockquote><pre>
fossil diff --from previous --to current
</pre></blockquote>

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:

<blockquote><pre>
fossil diff --from release --to trunk
</pre></blockquote>


<h2 id="order">Resolution Order</h2>

Fossil currently resolves name strings to artifact hashes in the
following order: