diff options
Diffstat (limited to 'www/checkin_names.wiki')
| -rw-r--r-- | www/checkin_names.wiki | 316 |
1 files changed, 316 insertions, 0 deletions
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 @@ +<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 information 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> |