Fossil SCM
Assorted minor fixes and tweaks to the check-in names doc
Commit
68a78b895e91f10d97ff33c5ea8e143ef32a6c8b1b600f345baed3b4b6a6df90
Parent
6c2b5bafb6820af…
1 file changed
+46
-40
+46
-40
| --- www/checkin_names.wiki | ||
| +++ www/checkin_names.wiki | ||
| @@ -15,18 +15,18 @@ | ||
| 15 | 15 | <ul> |
| 16 | 16 | <li> <b>tip</b> |
| 17 | 17 | <li> <b>current</b> |
| 18 | 18 | <li> <b>next</b> |
| 19 | 19 | <li> <b>previous</b> or <b>prev</b> |
| 20 | -<li> <b>ckout</b> (<a href='./embeddeddocs.wiki'>embedded docs</a> only) | |
| 20 | +<li> <b>ckout</b> (<a href='./embeddeddoc.wiki'>embedded docs</a> only) | |
| 21 | 21 | </ul> |
| 22 | 22 | </ul> |
| 23 | 23 | </td></tr> |
| 24 | 24 | </table> |
| 25 | -Many Fossil [/help|commands] and [./webui.wiki | web-interface] URLs accept | |
| 25 | +Many Fossil [/help|commands] and [./webui.wiki | web interface] URLs accept | |
| 26 | 26 | check-in names as an argument. For example, the "[/help/info|info]" command |
| 27 | -accepts an optional check-in name to identify the specific checkout | |
| 27 | +accepts an optional check-in name to identify the specific check-in | |
| 28 | 28 | about which information is desired: |
| 29 | 29 | |
| 30 | 30 | <blockquote> |
| 31 | 31 | <tt>fossil info</tt> <i>checkin-name</i> |
| 32 | 32 | </blockquote> |
| @@ -45,18 +45,18 @@ | ||
| 45 | 45 | document describes the various methods. |
| 46 | 46 | |
| 47 | 47 | <h2 id="canonical">Canonical Check-in Name</h2> |
| 48 | 48 | |
| 49 | 49 | The canonical name of a check-in is the hash of its |
| 50 | -[./fileformat.wiki#manifest | manifest] expressed as a 40-or-more character | |
| 51 | -lowercase hexadecimal number. For example: | |
| 50 | +[./fileformat.wiki#manifest | manifest] expressed as a | |
| 51 | +[./hashes.md | long lowercase hexadecimal number]. For example: | |
| 52 | 52 | |
| 53 | 53 | <blockquote><pre> |
| 54 | 54 | fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9 |
| 55 | 55 | </pre></blockquote> |
| 56 | 56 | |
| 57 | -The full 40+ character hash is unwieldy to remember and type, though, | |
| 57 | +The full 40 or 64 character hash is unwieldy to remember and type, though, | |
| 58 | 58 | so Fossil also accepts a unique prefix of the hash, using any combination |
| 59 | 59 | of upper and lower case letters, as long as the prefix is at least 4 |
| 60 | 60 | characters long. Hence the following commands all |
| 61 | 61 | accomplish the same thing as the above: |
| 62 | 62 | |
| @@ -64,50 +64,47 @@ | ||
| 64 | 64 | fossil info e5a734a19a9 |
| 65 | 65 | fossil info E5a734A |
| 66 | 66 | fossil info e5a7 |
| 67 | 67 | </blockquote> |
| 68 | 68 | |
| 69 | -Many web-interface screens identify check-ins by 10- or 16-character | |
| 69 | +Many web interface screens identify check-ins by 10- or 16-character | |
| 70 | 70 | prefix of canonical name. |
| 71 | 71 | |
| 72 | 72 | <h2 id="tags">Tags And Branch Names</h2> |
| 73 | 73 | |
| 74 | 74 | Using a tag or branch name where a check-in name is expected causes |
| 75 | 75 | Fossil to choose the most recent check-in with that tag or branch name. |
| 76 | -So, for example, as of this writing the most recent check-in that | |
| 77 | -is tagged with "release" is [d0753799e44]. | |
| 78 | -So the command: | |
| 76 | +So for example, the most recent check-in that | |
| 77 | +is tagged with "release" as of this writing is [b98ce23d4fc]. | |
| 78 | +The command: | |
| 79 | 79 | |
| 80 | 80 | <blockquote><pre> |
| 81 | 81 | fossil info release |
| 82 | 82 | </pre></blockquote> |
| 83 | 83 | |
| 84 | -Results in the following input: | |
| 84 | +…results in the following output: | |
| 85 | 85 | |
| 86 | 86 | <blockquote><pre> |
| 87 | -uuid: d0753799e447b795933e9f266233767d84aa1d84 2010-11-01 14:23:35 UTC | |
| 88 | -parent: 4e1241f3236236187ad2a8f205323c05b98c9895 2010-10-31 21:51:11 UTC | |
| 89 | -child: 4a094f46ade70bd9d1e4ffa48cbe94b4d3750aef 2010-11-01 18:52:37 UTC | |
| 90 | -child: f4033ec09ee6bb2a73fa588c217527a1f311bd27 2010-11-01 23:38:34 UTC | |
| 91 | -tags: trunk, release | |
| 92 | -comment: Fix a typo in the file format documentation reported on the | |
| 93 | - Tcl/Tk chatroom. (user: drh) | |
| 87 | +hash: b98ce23d4fc3b734cdc058ee8a67e6dad675ca13 2020-08-20 13:27:04 UTC | |
| 88 | +parent: 40feec329163103293d98dfcc2d119d1a16b227a 2020-08-20 13:01:51 UTC | |
| 89 | +tags: release, branch-2.12, version-2.12.1 | |
| 90 | +comment: Version 2.12.1 (user: drh) | |
| 94 | 91 | </pre></blockquote> |
| 95 | 92 | |
| 96 | 93 | There are multiple check-ins that are tagged with "release" but |
| 97 | -(as of this writing) the [d0753799e44] | |
| 94 | +(as of this writing) the [b98ce23d4fc] | |
| 98 | 95 | check-in is the most recent so it is the one that is selected. |
| 99 | 96 | |
| 100 | -Note that unlike other command DVCSes, a "branch" in Fossil | |
| 101 | -is not anything special; it is simply a sequence of check-ins that | |
| 102 | -share a common tag. So the same mechanism that resolves tag names | |
| 97 | +Note that unlike some other version control systems, a "branch" in Fossil | |
| 98 | +is not anything special: it is simply a sequence of check-ins that | |
| 99 | +share a common tag, so the same mechanism that resolves tag names | |
| 103 | 100 | also resolves branch names. |
| 104 | 101 | |
| 105 | 102 | <a id="tagpfx"></a> |
| 106 | -Note also that there can (in theory) be an ambiguity between tag names | |
| 103 | +Note also that there can — in theory, if rarely in practice — be an ambiguity between tag names | |
| 107 | 104 | and canonical names. Suppose, for example, you had a check-in with |
| 108 | -the canonical name deed28aa99a835f01fa06d5b4a41ecc2121bf419 and you | |
| 105 | +the canonical name deed28aa99… and you | |
| 109 | 106 | also happened to have tagged a different check-in with "deed2". If |
| 110 | 107 | you use the "deed2" name, does it choose the canonical name or the tag |
| 111 | 108 | name? In such cases, you can prefix the tag name with "tag:". |
| 112 | 109 | For example: |
| 113 | 110 | |
| @@ -114,17 +111,17 @@ | ||
| 114 | 111 | <blockquote><tt> |
| 115 | 112 | fossil info tag:deed2 |
| 116 | 113 | </tt></blockquote> |
| 117 | 114 | |
| 118 | 115 | The "tag:deed2" name will refer to the most recent check-in |
| 119 | -tagged with "deed2" not to the | |
| 116 | +tagged with "deed2" rather than the | |
| 120 | 117 | check-in whose canonical name begins with "deed2". |
| 121 | 118 | |
| 122 | 119 | <h2 id="whole-branches">Whole Branches</h2> |
| 123 | 120 | |
| 124 | 121 | Usually when a branch name is specified, it means the latest check-in on |
| 125 | -that branch. But for some commands (ex: [/help/purge|purge]) a branch name | |
| 122 | +that branch, but for some commands (ex: [/help/purge|purge]) a branch name | |
| 126 | 123 | on the argument means the earliest connected check-in on the branch. This |
| 127 | 124 | seems confusing when being explained here, but it works out to be intuitive |
| 128 | 125 | in practice. |
| 129 | 126 | |
| 130 | 127 | For example, the command "fossil purge XYZ" means to purge the check-in XYZ |
| @@ -153,11 +150,11 @@ | ||
| 153 | 150 | 6. <i>YYYYMMDDHHMM</i> |
| 154 | 151 | 7. <i>YYYYMMDDHHMMSS</i> |
| 155 | 152 | |
| 156 | 153 | In the second through the fourth forms, |
| 157 | 154 | the space between the day and the year can optionally be |
| 158 | -replaced by an uppercase <b>T</b> and the entire timestamp can | |
| 155 | +replaced by an uppercase <b>T</b>, and the entire timestamp can | |
| 159 | 156 | optionally be followed by "<b>z</b>" or "<b>Z</b>". In the fourth |
| 160 | 157 | form with fractional seconds, any number of digits may follow the |
| 161 | 158 | decimal point, though due to precision limits only the first three |
| 162 | 159 | digits will be significant. The final three pure-digit forms |
| 163 | 160 | without punctuation are only valid if the number they encode is |
| @@ -164,11 +161,11 @@ | ||
| 164 | 161 | not also the prefix of an artifact hash. |
| 165 | 162 | |
| 166 | 163 | In its default configuration, Fossil interprets and displays all dates |
| 167 | 164 | in Universal Coordinated Time (UTC). This tends to work the best for |
| 168 | 165 | distributed projects where participants are scattered around the globe. |
| 169 | -But there is an option on the Admin/Timeline page of the web-interface to | |
| 166 | +But there is an option on the Admin/Timeline page of the web interface to | |
| 170 | 167 | switch to local time. The "<b>Z</b>" suffix on a timestamp check-in |
| 171 | 168 | name is meaningless if Fossil is in the default mode of using UTC for |
| 172 | 169 | everything, but if Fossil has been switched to local time mode, then the |
| 173 | 170 | "<b>Z</b>" suffix means to interpret that particular timestamp using |
| 174 | 171 | UTC instead of local time. |
| @@ -186,17 +183,21 @@ | ||
| 186 | 183 | |
| 187 | 184 | <blockquote> |
| 188 | 185 | http://www.fossil-scm.org/fossil/doc/<b>trunk</b>/www/index.wiki |
| 189 | 186 | </blockquote> |
| 190 | 187 | |
| 191 | -The bold component of that URL is a check-in name. To see what the | |
| 192 | -Fossil website looked like on January 1, 2009, one has merely to change | |
| 188 | +The bold component of that URL is a check-in name. To see the stored | |
| 189 | +content of the Fossil website repository as of January 1, 2009, one has merely to change | |
| 193 | 190 | the URL to the following: |
| 194 | 191 | |
| 195 | 192 | <blockquote> |
| 196 | 193 | http://www.fossil-scm.org/fossil/doc/<b>2009-01-01</b>/www/index.wiki |
| 197 | 194 | </blockquote> |
| 195 | + | |
| 196 | +(Note that this won't roll you back to the <i>skin</i> and other | |
| 197 | +cosmetic configurations as of that date. It also won't change screens | |
| 198 | +like the timeline, which has an independent date selector.) | |
| 198 | 199 | |
| 199 | 200 | <h2 id="tag-ts">Tag And Timestamp</h2> |
| 200 | 201 | |
| 201 | 202 | A check-in name can also take the form of a tag or branch name followed by |
| 202 | 203 | a colon and then a timestamp. The combination means to take the most |
| @@ -206,39 +207,44 @@ | ||
| 206 | 207 | <blockquote> |
| 207 | 208 | fossil update trunk:2010-07-01T14:30 |
| 208 | 209 | </blockquote> |
| 209 | 210 | |
| 210 | 211 | Would cause Fossil to update the working check-out to be the most recent |
| 211 | -check-in on the trunk that is not more recent that 14:30 (UTC) on | |
| 212 | +check-in on the trunk that is not more recent than 14:30 (UTC) on | |
| 212 | 213 | July 1, 2010. |
| 213 | 214 | |
| 214 | 215 | <h2 id="root">Root Of A Branch</h2> |
| 215 | 216 | |
| 216 | 217 | A branch name that begins with the "<tt>root:</tt>" prefix refers to the |
| 217 | -last check-in in the parent branch prior to the beginning of the branch. | |
| 218 | +last check-in on the parent branch prior to the beginning of the branch. | |
| 218 | 219 | Such a label is useful, for example, in computing all diffs for a single |
| 219 | 220 | branch. The following example will show all changes in the hypothetical |
| 220 | 221 | branch "xyzzy": |
| 221 | 222 | |
| 222 | 223 | <blockquote> |
| 223 | 224 | fossil diff --from root:xyzzy --to xyzzy |
| 224 | 225 | </blockquote> |
| 225 | 226 | |
| 226 | 227 | <a id="merge-in"></a> |
| 227 | -A branch name that begins with the "<tt>merge-in:</tt>" prefix refers not | |
| 228 | -to the root of the branch, but to the most recent merge-in for that branch | |
| 229 | -from its parent. The most recent merge-in is the version to diff the branch | |
| 230 | -against in order to see all changes in just the branch itself, omitting | |
| 228 | +That doesn't do what you might expect after you merge the parent | |
| 229 | +branch's changes into the child branch: the above command will include | |
| 230 | +changes made on the parent branch as well. | |
| 231 | + | |
| 232 | +You can solve this by using the prefix "<tt>merge-in:</tt>" instead of | |
| 233 | +"<tt>root:</tt>" to tell Fossil to find | |
| 234 | +the most recent merge-in point for that branch. | |
| 235 | +The resulting diff will then show only the changes in | |
| 236 | +the branch itself, omitting | |
| 231 | 237 | any changes that have already been merged in from the parent branch. |
| 232 | 238 | |
| 233 | 239 | |
| 234 | 240 | <h2 id="special">Special Tags</h2> |
| 235 | 241 | |
| 236 | -The tag "tip" means the most recent check-in. The "tip" tag is roughly | |
| 237 | -equivalent to the timestamp tag "5000-01-01". | |
| 242 | +The tag "tip" means the most recent check-in. The "tip" tag is practically | |
| 243 | +equivalent to the timestamp "9999-12-31". | |
| 238 | 244 | |
| 239 | -This special name works anywhere you can pass a "NAME", such as in in | |
| 245 | +This special name works anywhere you can pass a "NAME", such as with | |
| 240 | 246 | <tt>/info</tt> URLs: |
| 241 | 247 | |
| 242 | 248 | <blockquote><pre> |
| 243 | 249 | http://localhost:8080/info/tip |
| 244 | 250 | </pre></blockquote> |
| @@ -285,11 +291,11 @@ | ||
| 285 | 291 | # Exact matches on [#special | the special names] |
| 286 | 292 | # [#timestamps | Timestamps], with preference to ISO8601 forms |
| 287 | 293 | # [#tagpfx | tag:TAGNAME] |
| 288 | 294 | # [#root | root:BRANCH] |
| 289 | 295 | # [#merge-in | merge-in:BRANCH] |
| 290 | - # [#tag-ts | TAG:timestamp] | |
| 296 | + # [#tag-ts | TAGNAME:timestamp] | |
| 291 | 297 | # Full artifact hash or hash prefix. |
| 292 | 298 | # Any other type of symbolic name that Fossil extracts from |
| 293 | 299 | artifacts. |
| 294 | 300 | |
| 295 | 301 | <div style="height:40em" id="this-space-intentionally-left-blank"></div> |
| 296 | 302 |
| --- www/checkin_names.wiki | |
| +++ www/checkin_names.wiki | |
| @@ -15,18 +15,18 @@ | |
| 15 | <ul> |
| 16 | <li> <b>tip</b> |
| 17 | <li> <b>current</b> |
| 18 | <li> <b>next</b> |
| 19 | <li> <b>previous</b> or <b>prev</b> |
| 20 | <li> <b>ckout</b> (<a href='./embeddeddocs.wiki'>embedded docs</a> only) |
| 21 | </ul> |
| 22 | </ul> |
| 23 | </td></tr> |
| 24 | </table> |
| 25 | Many Fossil [/help|commands] and [./webui.wiki | web-interface] URLs accept |
| 26 | check-in names as an argument. For example, the "[/help/info|info]" command |
| 27 | accepts an optional check-in name to identify the specific checkout |
| 28 | about which information is desired: |
| 29 | |
| 30 | <blockquote> |
| 31 | <tt>fossil info</tt> <i>checkin-name</i> |
| 32 | </blockquote> |
| @@ -45,18 +45,18 @@ | |
| 45 | document describes the various methods. |
| 46 | |
| 47 | <h2 id="canonical">Canonical Check-in Name</h2> |
| 48 | |
| 49 | The canonical name of a check-in is the hash of its |
| 50 | [./fileformat.wiki#manifest | manifest] expressed as a 40-or-more character |
| 51 | lowercase hexadecimal number. For example: |
| 52 | |
| 53 | <blockquote><pre> |
| 54 | fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9 |
| 55 | </pre></blockquote> |
| 56 | |
| 57 | The full 40+ character hash is unwieldy to remember and type, though, |
| 58 | so Fossil also accepts a unique prefix of the hash, using any combination |
| 59 | of upper and lower case letters, as long as the prefix is at least 4 |
| 60 | characters long. Hence the following commands all |
| 61 | accomplish the same thing as the above: |
| 62 | |
| @@ -64,50 +64,47 @@ | |
| 64 | fossil info e5a734a19a9 |
| 65 | fossil info E5a734A |
| 66 | fossil info e5a7 |
| 67 | </blockquote> |
| 68 | |
| 69 | Many web-interface screens identify check-ins by 10- or 16-character |
| 70 | prefix of canonical name. |
| 71 | |
| 72 | <h2 id="tags">Tags And Branch Names</h2> |
| 73 | |
| 74 | Using a tag or branch name where a check-in name is expected causes |
| 75 | Fossil to choose the most recent check-in with that tag or branch name. |
| 76 | So, for example, as of this writing the most recent check-in that |
| 77 | is tagged with "release" is [d0753799e44]. |
| 78 | So the command: |
| 79 | |
| 80 | <blockquote><pre> |
| 81 | fossil info release |
| 82 | </pre></blockquote> |
| 83 | |
| 84 | Results in the following input: |
| 85 | |
| 86 | <blockquote><pre> |
| 87 | uuid: d0753799e447b795933e9f266233767d84aa1d84 2010-11-01 14:23:35 UTC |
| 88 | parent: 4e1241f3236236187ad2a8f205323c05b98c9895 2010-10-31 21:51:11 UTC |
| 89 | child: 4a094f46ade70bd9d1e4ffa48cbe94b4d3750aef 2010-11-01 18:52:37 UTC |
| 90 | child: f4033ec09ee6bb2a73fa588c217527a1f311bd27 2010-11-01 23:38:34 UTC |
| 91 | tags: trunk, release |
| 92 | comment: Fix a typo in the file format documentation reported on the |
| 93 | Tcl/Tk chatroom. (user: drh) |
| 94 | </pre></blockquote> |
| 95 | |
| 96 | There are multiple check-ins that are tagged with "release" but |
| 97 | (as of this writing) the [d0753799e44] |
| 98 | check-in is the most recent so it is the one that is selected. |
| 99 | |
| 100 | Note that unlike other command DVCSes, a "branch" in Fossil |
| 101 | is not anything special; it is simply a sequence of check-ins that |
| 102 | share a common tag. So the same mechanism that resolves tag names |
| 103 | also resolves branch names. |
| 104 | |
| 105 | <a id="tagpfx"></a> |
| 106 | Note also that there can (in theory) be an ambiguity between tag names |
| 107 | and canonical names. Suppose, for example, you had a check-in with |
| 108 | the canonical name deed28aa99a835f01fa06d5b4a41ecc2121bf419 and you |
| 109 | also happened to have tagged a different check-in with "deed2". If |
| 110 | you use the "deed2" name, does it choose the canonical name or the tag |
| 111 | name? In such cases, you can prefix the tag name with "tag:". |
| 112 | For example: |
| 113 | |
| @@ -114,17 +111,17 @@ | |
| 114 | <blockquote><tt> |
| 115 | fossil info tag:deed2 |
| 116 | </tt></blockquote> |
| 117 | |
| 118 | The "tag:deed2" name will refer to the most recent check-in |
| 119 | tagged with "deed2" not to the |
| 120 | check-in whose canonical name begins with "deed2". |
| 121 | |
| 122 | <h2 id="whole-branches">Whole Branches</h2> |
| 123 | |
| 124 | Usually when a branch name is specified, it means the latest check-in on |
| 125 | that branch. But for some commands (ex: [/help/purge|purge]) a branch name |
| 126 | on the argument means the earliest connected check-in on the branch. This |
| 127 | seems confusing when being explained here, but it works out to be intuitive |
| 128 | in practice. |
| 129 | |
| 130 | For example, the command "fossil purge XYZ" means to purge the check-in XYZ |
| @@ -153,11 +150,11 @@ | |
| 153 | 6. <i>YYYYMMDDHHMM</i> |
| 154 | 7. <i>YYYYMMDDHHMMSS</i> |
| 155 | |
| 156 | In the second through the fourth forms, |
| 157 | the space between the day and the year can optionally be |
| 158 | replaced by an uppercase <b>T</b> and the entire timestamp can |
| 159 | optionally be followed by "<b>z</b>" or "<b>Z</b>". In the fourth |
| 160 | form with fractional seconds, any number of digits may follow the |
| 161 | decimal point, though due to precision limits only the first three |
| 162 | digits will be significant. The final three pure-digit forms |
| 163 | without punctuation are only valid if the number they encode is |
| @@ -164,11 +161,11 @@ | |
| 164 | not also the prefix of an artifact hash. |
| 165 | |
| 166 | In its default configuration, Fossil interprets and displays all dates |
| 167 | in Universal Coordinated Time (UTC). This tends to work the best for |
| 168 | distributed projects where participants are scattered around the globe. |
| 169 | But there is an option on the Admin/Timeline page of the web-interface to |
| 170 | switch to local time. The "<b>Z</b>" suffix on a timestamp check-in |
| 171 | name is meaningless if Fossil is in the default mode of using UTC for |
| 172 | everything, but if Fossil has been switched to local time mode, then the |
| 173 | "<b>Z</b>" suffix means to interpret that particular timestamp using |
| 174 | UTC instead of local time. |
| @@ -186,17 +183,21 @@ | |
| 186 | |
| 187 | <blockquote> |
| 188 | http://www.fossil-scm.org/fossil/doc/<b>trunk</b>/www/index.wiki |
| 189 | </blockquote> |
| 190 | |
| 191 | The bold component of that URL is a check-in name. To see what the |
| 192 | Fossil website looked like on January 1, 2009, one has merely to change |
| 193 | the URL to the following: |
| 194 | |
| 195 | <blockquote> |
| 196 | http://www.fossil-scm.org/fossil/doc/<b>2009-01-01</b>/www/index.wiki |
| 197 | </blockquote> |
| 198 | |
| 199 | <h2 id="tag-ts">Tag And Timestamp</h2> |
| 200 | |
| 201 | A check-in name can also take the form of a tag or branch name followed by |
| 202 | a colon and then a timestamp. The combination means to take the most |
| @@ -206,39 +207,44 @@ | |
| 206 | <blockquote> |
| 207 | fossil update trunk:2010-07-01T14:30 |
| 208 | </blockquote> |
| 209 | |
| 210 | Would cause Fossil to update the working check-out to be the most recent |
| 211 | check-in on the trunk that is not more recent that 14:30 (UTC) on |
| 212 | July 1, 2010. |
| 213 | |
| 214 | <h2 id="root">Root Of A Branch</h2> |
| 215 | |
| 216 | A branch name that begins with the "<tt>root:</tt>" prefix refers to the |
| 217 | last check-in in the parent branch prior to the beginning of the branch. |
| 218 | Such a label is useful, for example, in computing all diffs for a single |
| 219 | branch. The following example will show all changes in the hypothetical |
| 220 | branch "xyzzy": |
| 221 | |
| 222 | <blockquote> |
| 223 | fossil diff --from root:xyzzy --to xyzzy |
| 224 | </blockquote> |
| 225 | |
| 226 | <a id="merge-in"></a> |
| 227 | A branch name that begins with the "<tt>merge-in:</tt>" prefix refers not |
| 228 | to the root of the branch, but to the most recent merge-in for that branch |
| 229 | from its parent. The most recent merge-in is the version to diff the branch |
| 230 | against in order to see all changes in just the branch itself, omitting |
| 231 | any changes that have already been merged in from the parent branch. |
| 232 | |
| 233 | |
| 234 | <h2 id="special">Special Tags</h2> |
| 235 | |
| 236 | The tag "tip" means the most recent check-in. The "tip" tag is roughly |
| 237 | equivalent to the timestamp tag "5000-01-01". |
| 238 | |
| 239 | This special name works anywhere you can pass a "NAME", such as in in |
| 240 | <tt>/info</tt> URLs: |
| 241 | |
| 242 | <blockquote><pre> |
| 243 | http://localhost:8080/info/tip |
| 244 | </pre></blockquote> |
| @@ -285,11 +291,11 @@ | |
| 285 | # Exact matches on [#special | the special names] |
| 286 | # [#timestamps | Timestamps], with preference to ISO8601 forms |
| 287 | # [#tagpfx | tag:TAGNAME] |
| 288 | # [#root | root:BRANCH] |
| 289 | # [#merge-in | merge-in:BRANCH] |
| 290 | # [#tag-ts | TAG:timestamp] |
| 291 | # Full artifact hash or hash prefix. |
| 292 | # Any other type of symbolic name that Fossil extracts from |
| 293 | artifacts. |
| 294 | |
| 295 | <div style="height:40em" id="this-space-intentionally-left-blank"></div> |
| 296 |
| --- www/checkin_names.wiki | |
| +++ www/checkin_names.wiki | |
| @@ -15,18 +15,18 @@ | |
| 15 | <ul> |
| 16 | <li> <b>tip</b> |
| 17 | <li> <b>current</b> |
| 18 | <li> <b>next</b> |
| 19 | <li> <b>previous</b> or <b>prev</b> |
| 20 | <li> <b>ckout</b> (<a href='./embeddeddoc.wiki'>embedded docs</a> only) |
| 21 | </ul> |
| 22 | </ul> |
| 23 | </td></tr> |
| 24 | </table> |
| 25 | Many Fossil [/help|commands] and [./webui.wiki | web interface] URLs accept |
| 26 | check-in names as an argument. For example, the "[/help/info|info]" command |
| 27 | accepts an optional check-in name to identify the specific check-in |
| 28 | about which information is desired: |
| 29 | |
| 30 | <blockquote> |
| 31 | <tt>fossil info</tt> <i>checkin-name</i> |
| 32 | </blockquote> |
| @@ -45,18 +45,18 @@ | |
| 45 | document describes the various methods. |
| 46 | |
| 47 | <h2 id="canonical">Canonical Check-in Name</h2> |
| 48 | |
| 49 | The canonical name of a check-in is the hash of its |
| 50 | [./fileformat.wiki#manifest | manifest] expressed as a |
| 51 | [./hashes.md | long lowercase hexadecimal number]. For example: |
| 52 | |
| 53 | <blockquote><pre> |
| 54 | fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9 |
| 55 | </pre></blockquote> |
| 56 | |
| 57 | The full 40 or 64 character hash is unwieldy to remember and type, though, |
| 58 | so Fossil also accepts a unique prefix of the hash, using any combination |
| 59 | of upper and lower case letters, as long as the prefix is at least 4 |
| 60 | characters long. Hence the following commands all |
| 61 | accomplish the same thing as the above: |
| 62 | |
| @@ -64,50 +64,47 @@ | |
| 64 | fossil info e5a734a19a9 |
| 65 | fossil info E5a734A |
| 66 | fossil info e5a7 |
| 67 | </blockquote> |
| 68 | |
| 69 | Many web interface screens identify check-ins by 10- or 16-character |
| 70 | prefix of canonical name. |
| 71 | |
| 72 | <h2 id="tags">Tags And Branch Names</h2> |
| 73 | |
| 74 | Using a tag or branch name where a check-in name is expected causes |
| 75 | Fossil to choose the most recent check-in with that tag or branch name. |
| 76 | So for example, the most recent check-in that |
| 77 | is tagged with "release" as of this writing is [b98ce23d4fc]. |
| 78 | The command: |
| 79 | |
| 80 | <blockquote><pre> |
| 81 | fossil info release |
| 82 | </pre></blockquote> |
| 83 | |
| 84 | …results in the following output: |
| 85 | |
| 86 | <blockquote><pre> |
| 87 | hash: b98ce23d4fc3b734cdc058ee8a67e6dad675ca13 2020-08-20 13:27:04 UTC |
| 88 | parent: 40feec329163103293d98dfcc2d119d1a16b227a 2020-08-20 13:01:51 UTC |
| 89 | tags: release, branch-2.12, version-2.12.1 |
| 90 | comment: Version 2.12.1 (user: drh) |
| 91 | </pre></blockquote> |
| 92 | |
| 93 | There are multiple check-ins that are tagged with "release" but |
| 94 | (as of this writing) the [b98ce23d4fc] |
| 95 | check-in is the most recent so it is the one that is selected. |
| 96 | |
| 97 | Note that unlike some other version control systems, a "branch" in Fossil |
| 98 | is not anything special: it is simply a sequence of check-ins that |
| 99 | share a common tag, so the same mechanism that resolves tag names |
| 100 | also resolves branch names. |
| 101 | |
| 102 | <a id="tagpfx"></a> |
| 103 | Note also that there can — in theory, if rarely in practice — be an ambiguity between tag names |
| 104 | and canonical names. Suppose, for example, you had a check-in with |
| 105 | the canonical name deed28aa99… and you |
| 106 | also happened to have tagged a different check-in with "deed2". If |
| 107 | you use the "deed2" name, does it choose the canonical name or the tag |
| 108 | name? In such cases, you can prefix the tag name with "tag:". |
| 109 | For example: |
| 110 | |
| @@ -114,17 +111,17 @@ | |
| 111 | <blockquote><tt> |
| 112 | fossil info tag:deed2 |
| 113 | </tt></blockquote> |
| 114 | |
| 115 | The "tag:deed2" name will refer to the most recent check-in |
| 116 | tagged with "deed2" rather than the |
| 117 | check-in whose canonical name begins with "deed2". |
| 118 | |
| 119 | <h2 id="whole-branches">Whole Branches</h2> |
| 120 | |
| 121 | Usually when a branch name is specified, it means the latest check-in on |
| 122 | that branch, but for some commands (ex: [/help/purge|purge]) a branch name |
| 123 | on the argument means the earliest connected check-in on the branch. This |
| 124 | seems confusing when being explained here, but it works out to be intuitive |
| 125 | in practice. |
| 126 | |
| 127 | For example, the command "fossil purge XYZ" means to purge the check-in XYZ |
| @@ -153,11 +150,11 @@ | |
| 150 | 6. <i>YYYYMMDDHHMM</i> |
| 151 | 7. <i>YYYYMMDDHHMMSS</i> |
| 152 | |
| 153 | In the second through the fourth forms, |
| 154 | the space between the day and the year can optionally be |
| 155 | replaced by an uppercase <b>T</b>, and the entire timestamp can |
| 156 | optionally be followed by "<b>z</b>" or "<b>Z</b>". In the fourth |
| 157 | form with fractional seconds, any number of digits may follow the |
| 158 | decimal point, though due to precision limits only the first three |
| 159 | digits will be significant. The final three pure-digit forms |
| 160 | without punctuation are only valid if the number they encode is |
| @@ -164,11 +161,11 @@ | |
| 161 | not also the prefix of an artifact hash. |
| 162 | |
| 163 | In its default configuration, Fossil interprets and displays all dates |
| 164 | in Universal Coordinated Time (UTC). This tends to work the best for |
| 165 | distributed projects where participants are scattered around the globe. |
| 166 | But there is an option on the Admin/Timeline page of the web interface to |
| 167 | switch to local time. The "<b>Z</b>" suffix on a timestamp check-in |
| 168 | name is meaningless if Fossil is in the default mode of using UTC for |
| 169 | everything, but if Fossil has been switched to local time mode, then the |
| 170 | "<b>Z</b>" suffix means to interpret that particular timestamp using |
| 171 | UTC instead of local time. |
| @@ -186,17 +183,21 @@ | |
| 183 | |
| 184 | <blockquote> |
| 185 | http://www.fossil-scm.org/fossil/doc/<b>trunk</b>/www/index.wiki |
| 186 | </blockquote> |
| 187 | |
| 188 | The bold component of that URL is a check-in name. To see the stored |
| 189 | content of the Fossil website repository as of January 1, 2009, one has merely to change |
| 190 | the URL to the following: |
| 191 | |
| 192 | <blockquote> |
| 193 | http://www.fossil-scm.org/fossil/doc/<b>2009-01-01</b>/www/index.wiki |
| 194 | </blockquote> |
| 195 | |
| 196 | (Note that this won't roll you back to the <i>skin</i> and other |
| 197 | cosmetic configurations as of that date. It also won't change screens |
| 198 | like the timeline, which has an independent date selector.) |
| 199 | |
| 200 | <h2 id="tag-ts">Tag And Timestamp</h2> |
| 201 | |
| 202 | A check-in name can also take the form of a tag or branch name followed by |
| 203 | a colon and then a timestamp. The combination means to take the most |
| @@ -206,39 +207,44 @@ | |
| 207 | <blockquote> |
| 208 | fossil update trunk:2010-07-01T14:30 |
| 209 | </blockquote> |
| 210 | |
| 211 | Would cause Fossil to update the working check-out to be the most recent |
| 212 | check-in on the trunk that is not more recent than 14:30 (UTC) on |
| 213 | July 1, 2010. |
| 214 | |
| 215 | <h2 id="root">Root Of A Branch</h2> |
| 216 | |
| 217 | A branch name that begins with the "<tt>root:</tt>" prefix refers to the |
| 218 | last check-in on the parent branch prior to the beginning of the branch. |
| 219 | Such a label is useful, for example, in computing all diffs for a single |
| 220 | branch. The following example will show all changes in the hypothetical |
| 221 | branch "xyzzy": |
| 222 | |
| 223 | <blockquote> |
| 224 | fossil diff --from root:xyzzy --to xyzzy |
| 225 | </blockquote> |
| 226 | |
| 227 | <a id="merge-in"></a> |
| 228 | That doesn't do what you might expect after you merge the parent |
| 229 | branch's changes into the child branch: the above command will include |
| 230 | changes made on the parent branch as well. |
| 231 | |
| 232 | You can solve this by using the prefix "<tt>merge-in:</tt>" instead of |
| 233 | "<tt>root:</tt>" to tell Fossil to find |
| 234 | the most recent merge-in point for that branch. |
| 235 | The resulting diff will then show only the changes in |
| 236 | the branch itself, omitting |
| 237 | any changes that have already been merged in from the parent branch. |
| 238 | |
| 239 | |
| 240 | <h2 id="special">Special Tags</h2> |
| 241 | |
| 242 | The tag "tip" means the most recent check-in. The "tip" tag is practically |
| 243 | equivalent to the timestamp "9999-12-31". |
| 244 | |
| 245 | This special name works anywhere you can pass a "NAME", such as with |
| 246 | <tt>/info</tt> URLs: |
| 247 | |
| 248 | <blockquote><pre> |
| 249 | http://localhost:8080/info/tip |
| 250 | </pre></blockquote> |
| @@ -285,11 +291,11 @@ | |
| 291 | # Exact matches on [#special | the special names] |
| 292 | # [#timestamps | Timestamps], with preference to ISO8601 forms |
| 293 | # [#tagpfx | tag:TAGNAME] |
| 294 | # [#root | root:BRANCH] |
| 295 | # [#merge-in | merge-in:BRANCH] |
| 296 | # [#tag-ts | TAGNAME:timestamp] |
| 297 | # Full artifact hash or hash prefix. |
| 298 | # Any other type of symbolic name that Fossil extracts from |
| 299 | artifacts. |
| 300 | |
| 301 | <div style="height:40em" id="this-space-intentionally-left-blank"></div> |
| 302 |