Executive SummaryA check-in can be identified using any of the following names:
|
fossil info checkin-name
You are perhaps reading this page from the following URL:
http://www.fossil-scm.org/fossil/doc/trunk/www/checkin_names.wiki
The URL above is an example of an 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.
Canonical Check-in Name
The canonical name of a check-in is the hash of its manifest expressed as a 40-or-more character lowercase hexadecimal number. For example:
fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9
The full 40+ 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:
fossil info e5a734a19a9 fossil info E5a734A fossil info e5a7
Many web-interface screens identify check-ins by 10- or 16-character prefix of canonical name.
Tags And Branch Names
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, as of this writing the most recent check-in that is tagged with "release" is [d0753799e44]. So the command:
fossil info release
Results in the following input:
uuid: d0753799e447b795933e9f266233767d84aa1d84 2010-11-01 14:23:35 UTC
parent: 4e1241f3236236187ad2a8f205323c05b98c9895 2010-10-31 21:51:11 UTC
child: 4a094f46ade70bd9d1e4ffa48cbe94b4d3750aef 2010-11-01 18:52:37 UTC
child: f4033ec09ee6bb2a73fa588c217527a1f311bd27 2010-11-01 23:38:34 UTC
tags: trunk, release
comment: Fix a typo in the file format documentation reported on the
Tcl/Tk chatroom. (user: drh)
There are multiple check-ins that are tagged with "release" but (as of this writing) the [d0753799e44] check-in is the most recent so it is the one that is selected.
Note that unlike other command DVCSes, 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.
Note also that there can (in theory) be an ambiguity between tag names and canonical names. Suppose, for example, you had a check-in with the canonical name deed28aa99a835f01fa06d5b4a41ecc2121bf419 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:
fossil info tag:deed2
The "tag:deed2" name will refer to the most recent check-in tagged with "deed2" not to the check-in whose canonical name begins with "deed2".
Whole Branches
Usually when a branch name is specified, it means the latest check-in on that branch. But for some commands (ex: 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.
Timestamps
A timestamp in one of the formats shown below means the most recent check-in that occurs no later than the timestamp given:
- YYYY-MM-DD
- YYYY-MM-DD HH:MM
- YYYY-MM-DD HH:MM:SS
- YYYY-MM-DD HH:MM:SS.SSS
The space between the day and the year can optionally be replaced by an uppercase T and the entire timestamp can optionally be followed by "z" or "Z". 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.
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 "Z" 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 "Z" suffix means to interpret that particular timestamp using UTC instead of local time.
For an example of how timestamps are useful, consider the homepage for the Fossil website itself:
http://www.fossil-scm.org/fossil/doc/trunk/www/index.wiki
The bold component of that URL is a check-in name. To see what the Fossil website looked like on January 1, 2009, one has merely to change the URL to the following:
http://www.fossil-scm.org/fossil/doc/2009-01-01/www/index.wiki
Tag And Timestamp
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:
fossil update trunk:2010-07-01T14:30
Would cause Fossil to update the working check-out to be the most recent check-in on the trunk that is not more recent that 14:30 (UTC) on July 1, 2010.
Root Of A Branch
A branch name that begins with the "root:" prefix refers to the last check-in in 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":
fossil diff --from root:xyzzy --to xyzzy
Special Tags
The tag "tip" means the most recent check-in. The "tip" tag is roughly equivalent to the timestamp tag "5000-01-01".
If the command is being run from a working check-out (not against a bare repository) then a few extra tags apply. The "current" tag means the current check-out. The "next" tag means the youngest child of the current check-out. And the "previous" or "prev" tag means the primary (non-merge) parent of the current check-out.
For embedded documentation, the tag "ckout" means the version as present in the local source tree on disk, provided that the web server is started using "fossil ui" or "fossil server" from within the source tree. This tag can be used to preview local changes to documentation before committing them. It does not apply to CLI commands.
Additional Examples
To view the changes in the most recent check-in prior to the version currently checked out:
fossil diff --from previous --to current
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:
fossil diff --from release --to trunk