Fossil SCM
Expanded the "version/revision/UUID/snapshot" discussion in the glossary into a separate term since these aren't strict synonyms for "check-in", the definition which previously hosted this topic.
Commit
58030a789bbf9f0fc5108028c4c5796bbf60150423bd04d828e593462c9e4c96
Parent
23b91f379458129…
1 file changed
+76
-11
+76
-11
| --- www/glossary.md | ||
| +++ www/glossary.md | ||
| @@ -207,21 +207,86 @@ | ||
| 207 | 207 | [pull]: /help?cmd=pull |
| 208 | 208 | [push]: /help?cmd=push |
| 209 | 209 | [svrcmd]: /help?cmd=server |
| 210 | 210 | [sync]: /help?cmd=sync |
| 211 | 211 | |
| 212 | + | |
| 213 | +## Version / Revision / Hash / UUID / Snapshot <a id="version" name="hash"></a> | |
| 214 | + | |
| 215 | +These terms all mean the same thing: a long hexadecimal | |
| 216 | +[SHA hash value](./hashes.md) that uniquely identifies a particular | |
| 217 | +[check-in](#ci). | |
| 218 | + | |
| 219 | +We’ve listed the alternatives in decreasing preference order: | |
| 220 | + | |
| 221 | +* **Version** and **revision** are near-synonyms in common usage. | |
| 222 | + Fossil’s code and documentation use both interchangeably because | |
| 223 | + Fossil was created to manage the development of the SQLite project, | |
| 224 | + which formerly used [CVS], the Concurrent Versions System. CVS in | |
| 225 | + turn started out as a front-end to [RCS], the Revision Control | |
| 226 | + System, but even though CVS uses “version” in its name, it numbers | |
| 227 | + check-ins using a system derived from RCS’s scheme, which it calls | |
| 228 | + “Revisions” in user-facing output. Fossil inherits this confusion | |
| 229 | + honestly. | |
| 230 | + | |
| 231 | +* **Hash** refers to the [SHA1 or SHA3-256 hash](./hashes.md) of the | |
| 232 | + content of the checked-in data, uniquely identifying that version of | |
| 233 | + the managed files. It is a strictly correct synonym, used more often | |
| 234 | + in low-level contexts than the term “version.” | |
| 235 | + | |
| 236 | +* **UUID** is a deprecated term still found in many parts of the | |
| 237 | + Fossil internals and (decreasingly) its documentation. The problem | |
| 238 | + with using this as a synonym for a Fossil-managed version of the | |
| 239 | + managed files is that there are [standards][UUID] defining the | |
| 240 | + format of a “UUID,” none of which Fossil follows, not even the | |
| 241 | + [version 4][ruuid] (random) format, the type of UUID closest in | |
| 242 | + meaning and usage to a Fossil hash.(^A pre-Fossil 2.0 style SHA1 | |
| 243 | + hash is 160 bits, not the 128 bits many people expect for a proper | |
| 244 | + UUID, and even if you truncate it to 128 bits to create a “good | |
| 245 | + enough” version prefix, the 6 bits reserved in the UUID format for | |
| 246 | + the variant code cannot make a correct declaration except by a | |
| 247 | + random 1:64 chance. The SHA3-256 option allowed in Fossil 2.0 and | |
| 248 | + higher doesn’t help with this confusion, making a Fossil version | |
| 249 | + hash twice as large as a proper UUID. Alas, the term will never be | |
| 250 | + fully obliterated from use since there are columns in the Fossil | |
| 251 | + repository format that use the obsolete term; we cannot change this | |
| 252 | + without breaking backwards compatibility.) | |
| 253 | + | |
| 254 | +* **Snapshot** isn’t confusing, but it isn’t used often within the | |
| 255 | + Fossil community. We add it to the list here mainly because there’s | |
| 256 | + a conceptual overlap here with systems that *do* use the terms. The | |
| 257 | + primary distinction between a Fossil “snapshot” and the sort taken | |
| 258 | + by a virtual machine system or a [snapshotting file system][snfs] is | |
| 259 | + that Fossil will capture only changes to files you’ve | |
| 260 | + [added](/help?cmd=add) to the [repository](#repo), not to everything | |
| 261 | + in [the check-out directory](#co) at the time of the snapshot. (Thus | |
| 262 | + [the `extras` command](/help?cmd=extras).) | |
| 263 | + | |
| 264 | +[CVS]: https://en.wikipedia.org/wiki/Concurrent_Versions_System | |
| 265 | +[hash]: #version | |
| 266 | +[RCS]: https://en.wikipedia.org/wiki/Revision_Control_System | |
| 267 | +[ruuid]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random) | |
| 268 | +[snfs]: https://en.wikipedia.org/wiki/Snapshot_(computer_storage)#File_systems | |
| 269 | +[UUID]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random) | |
| 270 | +[version]: #version | |
| 271 | + | |
| 212 | 272 | |
| 213 | 273 | ## Check-in <a id="check-in" name="ci"></a> |
| 214 | 274 | |
| 215 | -A version of the project’s files that have been committed to the | |
| 216 | -repository. It is a snapshot of the project at an instant in time, as | |
| 217 | -seen from a single [check-out’s](#co) perspective. Synonyms: version, | |
| 218 | -snapshot, revision, commit. Sometimes styled “`CHECKIN`”, especially in | |
| 219 | -command documentation where any [valid checkin name][ciname] can be | |
| 220 | -used. | |
| 221 | - | |
| 222 | -* The long list of synonyms is confusing to new Fossil users, | |
| 275 | +A [version] of the project’s files that have been committed to the | |
| 276 | +repository; as such, it is sometimes called a “commit” instead. A | |
| 277 | +checkin is a snapshot of the project at an instant in time, as seen from | |
| 278 | +a single [check-out’s](#co) perspective. It is sometimes styled | |
| 279 | +“`CHECKIN`”, especially in command documentation where any | |
| 280 | +[valid checkin name][ciname] can be used. | |
| 281 | + | |
| 282 | +* There is a conflation of terms here: any of the various synonyms for | |
| 283 | + [version] may be used where “check-in” is more accurate, and vice | |
| 284 | + versa. This is because a check-in *has* a version, but a version | |
| 285 | + suffices to uniquely look up a particular commit. | |
| 286 | + | |
| 287 | +* The resulting long list of synonyms is confusing to new Fossil users, | |
| 223 | 288 | particularly the noun sense of the word “commit,” but it’s easy |
| 224 | 289 | enough to internalize the concepts. [Committing][commit] creates a |
| 225 | 290 | *commit.* It may also be said to create a checked-in *version* of a |
| 226 | 291 | particular *revision* of the project’s files, thus creating an |
| 227 | 292 | immutable *snapshot* of the project’s state at the time of the |
| @@ -235,12 +300,12 @@ | ||
| 235 | 300 | * Check-ins are immutable. |
| 236 | 301 | |
| 237 | 302 | * Check-ins exist only inside the repository. Contrast a |
| 238 | 303 | [check-out](#co). |
| 239 | 304 | |
| 240 | -* Check-ins may have [one or more names][ciname], but only the SHA | |
| 241 | - hash is globally unique, across all time; we call it the check-in’s | |
| 305 | +* Check-ins may have [one or more names][ciname], but only the | |
| 306 | + [hash] is globally unique, across all time; we call it the check-in’s | |
| 242 | 307 | canonical name. The other names are either imprecise, contextual, or |
| 243 | 308 | change their meaning over time and across [repositories](#repo). |
| 244 | 309 | |
| 245 | 310 | [ciname]: ./checkin_names.wiki |
| 246 | 311 | |
| @@ -263,11 +328,11 @@ | ||
| 263 | 328 | |
| 264 | 329 | * Check-outs relate to repositories in a one-to-many fashion: it is |
| 265 | 330 | common to have a single repo clone on a machine but to have it |
| 266 | 331 | [open] in [multiple working directories][mwd]. Check-out directories |
| 267 | 332 | are associated with the repos they were created from by settings |
| 268 | - stored in the check-out drectory. This is in the `.fslckout` file on | |
| 333 | + stored in the check-out directory. This is in the `.fslckout` file on | |
| 269 | 334 | POSIX type systems, but for historical compatibility reasons, it’s |
| 270 | 335 | called `_FOSSIL_` by native Windows builds of Fossil. |
| 271 | 336 | |
| 272 | 337 | (Contrast the Cygwin and WSL Fossil binaries, which use POSIX file |
| 273 | 338 | naming rules.) |
| 274 | 339 |
| --- www/glossary.md | |
| +++ www/glossary.md | |
| @@ -207,21 +207,86 @@ | |
| 207 | [pull]: /help?cmd=pull |
| 208 | [push]: /help?cmd=push |
| 209 | [svrcmd]: /help?cmd=server |
| 210 | [sync]: /help?cmd=sync |
| 211 | |
| 212 | |
| 213 | ## Check-in <a id="check-in" name="ci"></a> |
| 214 | |
| 215 | A version of the project’s files that have been committed to the |
| 216 | repository. It is a snapshot of the project at an instant in time, as |
| 217 | seen from a single [check-out’s](#co) perspective. Synonyms: version, |
| 218 | snapshot, revision, commit. Sometimes styled “`CHECKIN`”, especially in |
| 219 | command documentation where any [valid checkin name][ciname] can be |
| 220 | used. |
| 221 | |
| 222 | * The long list of synonyms is confusing to new Fossil users, |
| 223 | particularly the noun sense of the word “commit,” but it’s easy |
| 224 | enough to internalize the concepts. [Committing][commit] creates a |
| 225 | *commit.* It may also be said to create a checked-in *version* of a |
| 226 | particular *revision* of the project’s files, thus creating an |
| 227 | immutable *snapshot* of the project’s state at the time of the |
| @@ -235,12 +300,12 @@ | |
| 235 | * Check-ins are immutable. |
| 236 | |
| 237 | * Check-ins exist only inside the repository. Contrast a |
| 238 | [check-out](#co). |
| 239 | |
| 240 | * Check-ins may have [one or more names][ciname], but only the SHA |
| 241 | hash is globally unique, across all time; we call it the check-in’s |
| 242 | canonical name. The other names are either imprecise, contextual, or |
| 243 | change their meaning over time and across [repositories](#repo). |
| 244 | |
| 245 | [ciname]: ./checkin_names.wiki |
| 246 | |
| @@ -263,11 +328,11 @@ | |
| 263 | |
| 264 | * Check-outs relate to repositories in a one-to-many fashion: it is |
| 265 | common to have a single repo clone on a machine but to have it |
| 266 | [open] in [multiple working directories][mwd]. Check-out directories |
| 267 | are associated with the repos they were created from by settings |
| 268 | stored in the check-out drectory. This is in the `.fslckout` file on |
| 269 | POSIX type systems, but for historical compatibility reasons, it’s |
| 270 | called `_FOSSIL_` by native Windows builds of Fossil. |
| 271 | |
| 272 | (Contrast the Cygwin and WSL Fossil binaries, which use POSIX file |
| 273 | naming rules.) |
| 274 |
| --- www/glossary.md | |
| +++ www/glossary.md | |
| @@ -207,21 +207,86 @@ | |
| 207 | [pull]: /help?cmd=pull |
| 208 | [push]: /help?cmd=push |
| 209 | [svrcmd]: /help?cmd=server |
| 210 | [sync]: /help?cmd=sync |
| 211 | |
| 212 | |
| 213 | ## Version / Revision / Hash / UUID / Snapshot <a id="version" name="hash"></a> |
| 214 | |
| 215 | These terms all mean the same thing: a long hexadecimal |
| 216 | [SHA hash value](./hashes.md) that uniquely identifies a particular |
| 217 | [check-in](#ci). |
| 218 | |
| 219 | We’ve listed the alternatives in decreasing preference order: |
| 220 | |
| 221 | * **Version** and **revision** are near-synonyms in common usage. |
| 222 | Fossil’s code and documentation use both interchangeably because |
| 223 | Fossil was created to manage the development of the SQLite project, |
| 224 | which formerly used [CVS], the Concurrent Versions System. CVS in |
| 225 | turn started out as a front-end to [RCS], the Revision Control |
| 226 | System, but even though CVS uses “version” in its name, it numbers |
| 227 | check-ins using a system derived from RCS’s scheme, which it calls |
| 228 | “Revisions” in user-facing output. Fossil inherits this confusion |
| 229 | honestly. |
| 230 | |
| 231 | * **Hash** refers to the [SHA1 or SHA3-256 hash](./hashes.md) of the |
| 232 | content of the checked-in data, uniquely identifying that version of |
| 233 | the managed files. It is a strictly correct synonym, used more often |
| 234 | in low-level contexts than the term “version.” |
| 235 | |
| 236 | * **UUID** is a deprecated term still found in many parts of the |
| 237 | Fossil internals and (decreasingly) its documentation. The problem |
| 238 | with using this as a synonym for a Fossil-managed version of the |
| 239 | managed files is that there are [standards][UUID] defining the |
| 240 | format of a “UUID,” none of which Fossil follows, not even the |
| 241 | [version 4][ruuid] (random) format, the type of UUID closest in |
| 242 | meaning and usage to a Fossil hash.(^A pre-Fossil 2.0 style SHA1 |
| 243 | hash is 160 bits, not the 128 bits many people expect for a proper |
| 244 | UUID, and even if you truncate it to 128 bits to create a “good |
| 245 | enough” version prefix, the 6 bits reserved in the UUID format for |
| 246 | the variant code cannot make a correct declaration except by a |
| 247 | random 1:64 chance. The SHA3-256 option allowed in Fossil 2.0 and |
| 248 | higher doesn’t help with this confusion, making a Fossil version |
| 249 | hash twice as large as a proper UUID. Alas, the term will never be |
| 250 | fully obliterated from use since there are columns in the Fossil |
| 251 | repository format that use the obsolete term; we cannot change this |
| 252 | without breaking backwards compatibility.) |
| 253 | |
| 254 | * **Snapshot** isn’t confusing, but it isn’t used often within the |
| 255 | Fossil community. We add it to the list here mainly because there’s |
| 256 | a conceptual overlap here with systems that *do* use the terms. The |
| 257 | primary distinction between a Fossil “snapshot” and the sort taken |
| 258 | by a virtual machine system or a [snapshotting file system][snfs] is |
| 259 | that Fossil will capture only changes to files you’ve |
| 260 | [added](/help?cmd=add) to the [repository](#repo), not to everything |
| 261 | in [the check-out directory](#co) at the time of the snapshot. (Thus |
| 262 | [the `extras` command](/help?cmd=extras).) |
| 263 | |
| 264 | [CVS]: https://en.wikipedia.org/wiki/Concurrent_Versions_System |
| 265 | [hash]: #version |
| 266 | [RCS]: https://en.wikipedia.org/wiki/Revision_Control_System |
| 267 | [ruuid]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random) |
| 268 | [snfs]: https://en.wikipedia.org/wiki/Snapshot_(computer_storage)#File_systems |
| 269 | [UUID]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random) |
| 270 | [version]: #version |
| 271 | |
| 272 | |
| 273 | ## Check-in <a id="check-in" name="ci"></a> |
| 274 | |
| 275 | A [version] of the project’s files that have been committed to the |
| 276 | repository; as such, it is sometimes called a “commit” instead. A |
| 277 | checkin is a snapshot of the project at an instant in time, as seen from |
| 278 | a single [check-out’s](#co) perspective. It is sometimes styled |
| 279 | “`CHECKIN`”, especially in command documentation where any |
| 280 | [valid checkin name][ciname] can be used. |
| 281 | |
| 282 | * There is a conflation of terms here: any of the various synonyms for |
| 283 | [version] may be used where “check-in” is more accurate, and vice |
| 284 | versa. This is because a check-in *has* a version, but a version |
| 285 | suffices to uniquely look up a particular commit. |
| 286 | |
| 287 | * The resulting long list of synonyms is confusing to new Fossil users, |
| 288 | particularly the noun sense of the word “commit,” but it’s easy |
| 289 | enough to internalize the concepts. [Committing][commit] creates a |
| 290 | *commit.* It may also be said to create a checked-in *version* of a |
| 291 | particular *revision* of the project’s files, thus creating an |
| 292 | immutable *snapshot* of the project’s state at the time of the |
| @@ -235,12 +300,12 @@ | |
| 300 | * Check-ins are immutable. |
| 301 | |
| 302 | * Check-ins exist only inside the repository. Contrast a |
| 303 | [check-out](#co). |
| 304 | |
| 305 | * Check-ins may have [one or more names][ciname], but only the |
| 306 | [hash] is globally unique, across all time; we call it the check-in’s |
| 307 | canonical name. The other names are either imprecise, contextual, or |
| 308 | change their meaning over time and across [repositories](#repo). |
| 309 | |
| 310 | [ciname]: ./checkin_names.wiki |
| 311 | |
| @@ -263,11 +328,11 @@ | |
| 328 | |
| 329 | * Check-outs relate to repositories in a one-to-many fashion: it is |
| 330 | common to have a single repo clone on a machine but to have it |
| 331 | [open] in [multiple working directories][mwd]. Check-out directories |
| 332 | are associated with the repos they were created from by settings |
| 333 | stored in the check-out directory. This is in the `.fslckout` file on |
| 334 | POSIX type systems, but for historical compatibility reasons, it’s |
| 335 | called `_FOSSIL_` by native Windows builds of Fossil. |
| 336 | |
| 337 | (Contrast the Cygwin and WSL Fossil binaries, which use POSIX file |
| 338 | naming rules.) |
| 339 |