From 4f49b16079b27d7ce633619e4cddfdf2bffbc952 Mon Sep 17 00:00:00 2001 From: cashmere Date: Fri, 4 Sep 2026 09:05:24 +0200 Subject: initial commit --- www/checkin_names.wiki | 316 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 316 insertions(+) create mode 100644 www/checkin_names.wiki (limited to 'www/checkin_names.wiki') diff --git a/www/checkin_names.wiki b/www/checkin_names.wiki new file mode 100644 index 0000000..f3d8758 --- /dev/null +++ b/www/checkin_names.wiki @@ -0,0 +1,316 @@ +Check-in Names + +
+Quick Reference + +
+ +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: + +
+fossil info checkin-name
+
+ +You are perhaps reading this page from the following URL: + + +https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki + + +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. + +

Canonical Check-in Name

+ +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: + +
+fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9
+
+ +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: + +
+fossil info e5a734a19a9
+fossil info E5a734A
+fossil info e5a7
+
+ +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. + +

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, the most recent check-in that +is tagged with "release" as of this writing is [b98ce23d4fc]. +The command: + +
+fossil info release
+
+ +…results in the following output: + +
+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)
+
+ +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. + + +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: + +
+fossil info tag:deed2
+
+ +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". + +

Whole Branches

+ +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. + +

Timestamps

+ +A timestamp in one of the formats shown below means the most recent +check-in that occurs no later than the timestamp given: + + 1. YYYY-MM-DD + 2. YYYY-MM-DD HH:MM + 3. YYYY-MM-DD HH:MM:SS + 4. YYYY-MM-DD HH:MM:SS.SSS + 5. YYYYMMDD + 6. YYYYMMDDHHMM + 7. YYYYMMDDHHMMSS + +In the second through the fourth forms, +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. 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 "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. + +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: + +
+https://fossil-scm.org/home/doc/trunk/www/index.wiki
+
+ +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: + +
+https://fossil-scm.org/home/doc/2009-01-01/www/index.wiki
+
+ +(Note that this won't roll you back to the skin and other +cosmetic configurations as of that date. It also won't change screens +like the timeline, which has an independent date selector.) + +

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 than 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 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": + +
+fossil diff --from root:xyzzy --to xyzzy
+
+ + +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 "merge-in:" instead of +"root:" 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. + + +The prefix "start:" gives the first check-in of the named branch. + +The prefixes "root:", "start:", and "merge-in:" +can be chained: one can say for example + +
+fossil info merge-in:xyzzy:2022-03-01
+
+ +to get information about the most recent merge-in point on the branch +"xyzzy" that happened on or before March 1, 2022. + +

Special Tags

+ +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 +/info URLs: + +
+http://localhost:8080/info/tip
+
+ +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 fossil info command, +but not in an /info 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 +/doc URLs. + + +

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

Resolution Order

+ +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. + +
-- cgit v1.3.1