Fossil SCM
Moved the "snapshot" term in the glossary down into a footnote because it's got assorted problems, making it a much worse overall synonym for "version" even than "UUID".
Commit
733ef88ab88e7a3d0293e9228db540d6d6e6318a6f2ed6c8f168505365694982
Parent
58030a789bbf9f0…
1 file changed
+46
-34
+46
-34
| --- www/glossary.md | ||
| +++ www/glossary.md | ||
| @@ -199,20 +199,23 @@ | ||
| 199 | 199 | move right 0.05 |
| 200 | 200 | box invis "clones of Fossil itself, SQLite, etc." ljust |
| 201 | 201 | ``` |
| 202 | 202 | |
| 203 | 203 | [asdis]: /help?cmd=autosync |
| 204 | -[backup]: ./backup.md | |
| 205 | -[CAP]: ./cap-theorem.md | |
| 206 | -[cloned]: /help?cmd=clone | |
| 207 | -[pull]: /help?cmd=pull | |
| 208 | -[push]: /help?cmd=push | |
| 209 | -[svrcmd]: /help?cmd=server | |
| 210 | -[sync]: /help?cmd=sync | |
| 204 | +[backup]: ./backup.md | |
| 205 | +[CAP]: ./cap-theorem.md | |
| 206 | +[cloned]: /help?cmd=clone | |
| 207 | +[pull]: /help?cmd=pull | |
| 208 | +[push]: /help?cmd=push | |
| 209 | +[svrcmd]: /help?cmd=server | |
| 210 | +[sync]: /help?cmd=sync | |
| 211 | + | |
| 212 | +[repository]: #repo | |
| 213 | +[repositories]: #repo | |
| 211 | 214 | |
| 212 | 215 | |
| 213 | -## Version / Revision / Hash / UUID / Snapshot <a id="version" name="hash"></a> | |
| 216 | +## Version / Revision / Hash / UUID <a id="version" name="hash"></a> | |
| 214 | 217 | |
| 215 | 218 | These terms all mean the same thing: a long hexadecimal |
| 216 | 219 | [SHA hash value](./hashes.md) that uniquely identifies a particular |
| 217 | 220 | [check-in](#ci). |
| 218 | 221 | |
| @@ -249,19 +252,12 @@ | ||
| 249 | 252 | hash twice as large as a proper UUID. Alas, the term will never be |
| 250 | 253 | fully obliterated from use since there are columns in the Fossil |
| 251 | 254 | repository format that use the obsolete term; we cannot change this |
| 252 | 255 | without breaking backwards compatibility.) |
| 253 | 256 | |
| 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).) | |
| 257 | +You will find all of these synonyms used in the Fossil documentation. | |
| 258 | +Some day we may settle on a single term, but it doesn’t seem likely. | |
| 263 | 259 | |
| 264 | 260 | [CVS]: https://en.wikipedia.org/wiki/Concurrent_Versions_System |
| 265 | 261 | [hash]: #version |
| 266 | 262 | [RCS]: https://en.wikipedia.org/wiki/Revision_Control_System |
| 267 | 263 | [ruuid]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random) |
| @@ -271,51 +267,67 @@ | ||
| 271 | 267 | |
| 272 | 268 | |
| 273 | 269 | ## Check-in <a id="check-in" name="ci"></a> |
| 274 | 270 | |
| 275 | 271 | 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 | |
| 272 | +[repository]; as such, it is sometimes called a “commit” instead. A | |
| 273 | +check-in is a snapshot of the project at an instant in time, as seen from | |
| 278 | 274 | a single [check-out’s](#co) perspective. It is sometimes styled |
| 279 | 275 | “`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 | |
| 276 | +[valid check-in name][ciname] can be used. | |
| 277 | + | |
| 278 | +* There is a harmless conflation of terms here: any of the various | |
| 279 | + synonyms for [version] may be used where “check-in” is more accurate, | |
| 280 | + and vice versa, because there is a 1:1 relation between them. A | |
| 281 | + check-in *has* a version, but a version suffices to uniquely look up | |
| 282 | + a particular commit.[^snapshot] | |
| 283 | + | |
| 284 | +* Combining both sets of synonyms results in a list of terms that is | |
| 285 | + confusing to new Fossil users, but it’s easy | |
| 289 | 286 | enough to internalize the concepts. [Committing][commit] creates a |
| 290 | 287 | *commit.* It may also be said to create a checked-in *version* of a |
| 291 | 288 | particular *revision* of the project’s files, thus creating an |
| 292 | 289 | immutable *snapshot* of the project’s state at the time of the |
| 293 | 290 | commit. Fossil users find each of these different words for the |
| 294 | 291 | same concept useful for expressive purposes among ourselves, but to |
| 295 | 292 | Fossil proper, they all mean the same thing. |
| 296 | 293 | |
| 297 | - You will find all of these synonyms used in the Fossil documentation. | |
| 298 | - Some day we may settle on a single term, but it doesn’t seem likely. | |
| 299 | - | |
| 300 | 294 | * Check-ins are immutable. |
| 301 | 295 | |
| 302 | 296 | * Check-ins exist only inside the repository. Contrast a |
| 303 | 297 | [check-out](#co). |
| 304 | 298 | |
| 305 | 299 | * Check-ins may have [one or more names][ciname], but only the |
| 306 | 300 | [hash] is globally unique, across all time; we call it the check-in’s |
| 307 | 301 | canonical name. The other names are either imprecise, contextual, or |
| 308 | - change their meaning over time and across [repositories](#repo). | |
| 302 | + change their meaning over time and across [repositories]. | |
| 303 | + | |
| 304 | +[^snapshot]: You may sometimes see the term “snapshot” used as a synonym | |
| 305 | + for a check-in or the version number identifying said check-in. We | |
| 306 | + must warn against this usage because there is a potential confusion | |
| 307 | + here: [the `stash` command][stash] uses the term “snapshot,” as does | |
| 308 | + [the `undo` system][undo] to make a distinction with check-ins. | |
| 309 | + Nevertheless, there is a conceptual overlap here between Fossil and | |
| 310 | + systems that do use the term “snapshot,” the primary distinction being | |
| 311 | + that Fossil will capture only changes to files you’ve [added][add] to | |
| 312 | + the [repository], not to everything in [the check-out directory](#co) | |
| 313 | + at the time of the snapshot. (Thus [the `extras` command][extras].) | |
| 314 | + Contrast a snapshot taken by a virtual machine system or a | |
| 315 | + [snapshotting file system][snfs], which captures changes to everything | |
| 316 | + on the managed storage volume. | |
| 309 | 317 | |
| 318 | +[add]: /help?cmd=add | |
| 310 | 319 | [ciname]: ./checkin_names.wiki |
| 320 | +[extras]: /help?cmd=extras | |
| 321 | +[stash]: /help?cmd=stash | |
| 322 | +[undo]: /help?cmd=undo | |
| 311 | 323 | |
| 312 | 324 | |
| 313 | 325 | |
| 314 | 326 | ## Check-out <a id="check-out" name="co"></a> |
| 315 | 327 | |
| 316 | -A set of files extracted from a [repository](#repo) that represent a | |
| 328 | +A set of files extracted from a [repository] that represent a | |
| 317 | 329 | particular [check-in](#ci) of the [project](#project). |
| 318 | 330 | |
| 319 | 331 | * Unlike a check-in, a check-out is mutable. It may start out as a |
| 320 | 332 | version of a particular check-in extracted from the repository, but |
| 321 | 333 | the user is then free to make modifications to the checked-out |
| @@ -441,11 +453,11 @@ | ||
| 441 | 453 | |
| 442 | 454 | ## <a id="caps"></a>Capabilities |
| 443 | 455 | |
| 444 | 456 | Fossil includes a powerful [role-based access control system][rbac] |
| 445 | 457 | which affects which users have which capabilities within a given |
| 446 | -[repository](#repo). You can read more about this complex topic | |
| 458 | +[repository]. You can read more about this complex topic | |
| 447 | 459 | [here](./caps/). |
| 448 | 460 | |
| 449 | 461 | Some people — and indeed certain parts of Fossil’s own code — use the |
| 450 | 462 | term “permissions” instead, but since [operating system file permissions |
| 451 | 463 | also play into this](./caps/#webonly), we prefer the term “capabilities” |
| 452 | 464 |
| --- www/glossary.md | |
| +++ www/glossary.md | |
| @@ -199,20 +199,23 @@ | |
| 199 | move right 0.05 |
| 200 | box invis "clones of Fossil itself, SQLite, etc." ljust |
| 201 | ``` |
| 202 | |
| 203 | [asdis]: /help?cmd=autosync |
| 204 | [backup]: ./backup.md |
| 205 | [CAP]: ./cap-theorem.md |
| 206 | [cloned]: /help?cmd=clone |
| 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 | |
| @@ -249,19 +252,12 @@ | |
| 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) |
| @@ -271,51 +267,67 @@ | |
| 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 |
| 293 | commit. Fossil users find each of these different words for the |
| 294 | same concept useful for expressive purposes among ourselves, but to |
| 295 | Fossil proper, they all mean the same thing. |
| 296 | |
| 297 | You will find all of these synonyms used in the Fossil documentation. |
| 298 | Some day we may settle on a single term, but it doesn’t seem likely. |
| 299 | |
| 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 | |
| 312 | |
| 313 | |
| 314 | ## Check-out <a id="check-out" name="co"></a> |
| 315 | |
| 316 | A set of files extracted from a [repository](#repo) that represent a |
| 317 | particular [check-in](#ci) of the [project](#project). |
| 318 | |
| 319 | * Unlike a check-in, a check-out is mutable. It may start out as a |
| 320 | version of a particular check-in extracted from the repository, but |
| 321 | the user is then free to make modifications to the checked-out |
| @@ -441,11 +453,11 @@ | |
| 441 | |
| 442 | ## <a id="caps"></a>Capabilities |
| 443 | |
| 444 | Fossil includes a powerful [role-based access control system][rbac] |
| 445 | which affects which users have which capabilities within a given |
| 446 | [repository](#repo). You can read more about this complex topic |
| 447 | [here](./caps/). |
| 448 | |
| 449 | Some people — and indeed certain parts of Fossil’s own code — use the |
| 450 | term “permissions” instead, but since [operating system file permissions |
| 451 | also play into this](./caps/#webonly), we prefer the term “capabilities” |
| 452 |
| --- www/glossary.md | |
| +++ www/glossary.md | |
| @@ -199,20 +199,23 @@ | |
| 199 | move right 0.05 |
| 200 | box invis "clones of Fossil itself, SQLite, etc." ljust |
| 201 | ``` |
| 202 | |
| 203 | [asdis]: /help?cmd=autosync |
| 204 | [backup]: ./backup.md |
| 205 | [CAP]: ./cap-theorem.md |
| 206 | [cloned]: /help?cmd=clone |
| 207 | [pull]: /help?cmd=pull |
| 208 | [push]: /help?cmd=push |
| 209 | [svrcmd]: /help?cmd=server |
| 210 | [sync]: /help?cmd=sync |
| 211 | |
| 212 | [repository]: #repo |
| 213 | [repositories]: #repo |
| 214 | |
| 215 | |
| 216 | ## Version / Revision / Hash / UUID <a id="version" name="hash"></a> |
| 217 | |
| 218 | These terms all mean the same thing: a long hexadecimal |
| 219 | [SHA hash value](./hashes.md) that uniquely identifies a particular |
| 220 | [check-in](#ci). |
| 221 | |
| @@ -249,19 +252,12 @@ | |
| 252 | hash twice as large as a proper UUID. Alas, the term will never be |
| 253 | fully obliterated from use since there are columns in the Fossil |
| 254 | repository format that use the obsolete term; we cannot change this |
| 255 | without breaking backwards compatibility.) |
| 256 | |
| 257 | You will find all of these synonyms used in the Fossil documentation. |
| 258 | Some day we may settle on a single term, but it doesn’t seem likely. |
| 259 | |
| 260 | [CVS]: https://en.wikipedia.org/wiki/Concurrent_Versions_System |
| 261 | [hash]: #version |
| 262 | [RCS]: https://en.wikipedia.org/wiki/Revision_Control_System |
| 263 | [ruuid]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random) |
| @@ -271,51 +267,67 @@ | |
| 267 | |
| 268 | |
| 269 | ## Check-in <a id="check-in" name="ci"></a> |
| 270 | |
| 271 | A [version] of the project’s files that have been committed to the |
| 272 | [repository]; as such, it is sometimes called a “commit” instead. A |
| 273 | check-in is a snapshot of the project at an instant in time, as seen from |
| 274 | a single [check-out’s](#co) perspective. It is sometimes styled |
| 275 | “`CHECKIN`”, especially in command documentation where any |
| 276 | [valid check-in name][ciname] can be used. |
| 277 | |
| 278 | * There is a harmless conflation of terms here: any of the various |
| 279 | synonyms for [version] may be used where “check-in” is more accurate, |
| 280 | and vice versa, because there is a 1:1 relation between them. A |
| 281 | check-in *has* a version, but a version suffices to uniquely look up |
| 282 | a particular commit.[^snapshot] |
| 283 | |
| 284 | * Combining both sets of synonyms results in a list of terms that is |
| 285 | confusing to new Fossil users, but it’s easy |
| 286 | enough to internalize the concepts. [Committing][commit] creates a |
| 287 | *commit.* It may also be said to create a checked-in *version* of a |
| 288 | particular *revision* of the project’s files, thus creating an |
| 289 | immutable *snapshot* of the project’s state at the time of the |
| 290 | commit. Fossil users find each of these different words for the |
| 291 | same concept useful for expressive purposes among ourselves, but to |
| 292 | Fossil proper, they all mean the same thing. |
| 293 | |
| 294 | * Check-ins are immutable. |
| 295 | |
| 296 | * Check-ins exist only inside the repository. Contrast a |
| 297 | [check-out](#co). |
| 298 | |
| 299 | * Check-ins may have [one or more names][ciname], but only the |
| 300 | [hash] is globally unique, across all time; we call it the check-in’s |
| 301 | canonical name. The other names are either imprecise, contextual, or |
| 302 | change their meaning over time and across [repositories]. |
| 303 | |
| 304 | [^snapshot]: You may sometimes see the term “snapshot” used as a synonym |
| 305 | for a check-in or the version number identifying said check-in. We |
| 306 | must warn against this usage because there is a potential confusion |
| 307 | here: [the `stash` command][stash] uses the term “snapshot,” as does |
| 308 | [the `undo` system][undo] to make a distinction with check-ins. |
| 309 | Nevertheless, there is a conceptual overlap here between Fossil and |
| 310 | systems that do use the term “snapshot,” the primary distinction being |
| 311 | that Fossil will capture only changes to files you’ve [added][add] to |
| 312 | the [repository], not to everything in [the check-out directory](#co) |
| 313 | at the time of the snapshot. (Thus [the `extras` command][extras].) |
| 314 | Contrast a snapshot taken by a virtual machine system or a |
| 315 | [snapshotting file system][snfs], which captures changes to everything |
| 316 | on the managed storage volume. |
| 317 | |
| 318 | [add]: /help?cmd=add |
| 319 | [ciname]: ./checkin_names.wiki |
| 320 | [extras]: /help?cmd=extras |
| 321 | [stash]: /help?cmd=stash |
| 322 | [undo]: /help?cmd=undo |
| 323 | |
| 324 | |
| 325 | |
| 326 | ## Check-out <a id="check-out" name="co"></a> |
| 327 | |
| 328 | A set of files extracted from a [repository] that represent a |
| 329 | particular [check-in](#ci) of the [project](#project). |
| 330 | |
| 331 | * Unlike a check-in, a check-out is mutable. It may start out as a |
| 332 | version of a particular check-in extracted from the repository, but |
| 333 | the user is then free to make modifications to the checked-out |
| @@ -441,11 +453,11 @@ | |
| 453 | |
| 454 | ## <a id="caps"></a>Capabilities |
| 455 | |
| 456 | Fossil includes a powerful [role-based access control system][rbac] |
| 457 | which affects which users have which capabilities within a given |
| 458 | [repository]. You can read more about this complex topic |
| 459 | [here](./caps/). |
| 460 | |
| 461 | Some people — and indeed certain parts of Fossil’s own code — use the |
| 462 | term “permissions” instead, but since [operating system file permissions |
| 463 | also play into this](./caps/#webonly), we prefer the term “capabilities” |
| 464 |