initial commitHEADmaster

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>