Fossil SCM

New document, "Hashes: Fossil Artifact Identification", which attempts to break down the HASH vs VERSION vs commit ID vs NAME vs UUID mess. It also serves to document my current understanding of all the ways "UUID" is currently misused, but because it is only documenting the current state of things, it's safe to put it on trunk. (Changes to cope with that particular slice of the mess will appaar later, on a branch.)

wyoung 2020-05-27 22:05 trunk
Commit 33bec291b02fed8752444510dd19115385ee491dec857498e93ad46cf35c73b0
Parent 74a7309aad8d296…
2 files changed +82 +1
+ www/hashes.md ~ www/mkindex.tcl
A www/hashes.md
+82
--- a/www/hashes.md
+++ b/www/hashes.md
@@ -0,0 +1,82 @@
1
+# Hashes: Fossil Artifact Idei# Hashes: Fossil Artifact Identification
2
+
3
+All artifacts in Fossil are identified by a unique hash, currently using
4
+[the SHA3 algorithm by default][hpol], but histori. Therefore, there are two full-length hash formats used by
5
+Fossilcal| Algorithm | Raw Bits | Hex ASCII Bytes |
6
+|-----------|----------|-----------------|
7
+| SHA3-256 | 256 | 64 |
8
+| SHA1 | 1>SHA1<td>160<td>40<tr><td>SHA1</td> <td>160</td> <td>40</td></tr>
9
+</table> | 40 |
10
+
11
+There are many types of artifacts in Fossil: commits (a.k.a. check-ins),
12
+tickets, ticket comments, wiki articles, forum postings, file data
13
+belonging to check-ins, etc. ([More info...](./concepts.wiki#artifacts)).
14
+
15
+There is a looterms we try to use consistently, though we have
16
+not always succeeded. We cover each of those termse this leaks out
17
+s
18
+parts of the Fossil UI, which we cover in the sections below.
19
+
20
+
21
+## Names
22
+
23
+Several Fossil interfaces accept [a wide variety of check-in
24
+names][cin]: commit
25
+
26
+Artifact hashes are na
27
+
28
+## <a id="ues. We use
29
+the broader termshes are onl, and we use the
30
+e use
31
+the broad term “namee specific terms when we mean one particular type of NAME.
32
+
33
+
34
+## Versions
35
+
36
+When an artifact hash refers to a specific commit, Fossil sometimes
37
+calls it a This is a
38
+�s docs, UI, from, let us say, a wiki
39
+type of artifact hash, dssil sometimes
40
+calls it a “VERSION,” a “commit ID,” or a “check-in ID.”
41
+We may eventually settle on one of these terms, but all three are type of artifact hash, distinct
42
+from, let us say, a wiki article artifact hash.
43
+
44
+A unique prefix of a VERSION hash is itself a VERSION. That is, if your
45
+repository has exactly one commit artifact with a hash prefix nconventional Use Of The Term "UUID"
46
+
47
+"UUID" is an acronym for "Univerially Unique Identifier". Hashes
48
+geneUIDs: An Unfortunate Historical Artifact
49
+
50
+Historically, Fossil incorrectly used the term “[UUID][uuid]” where it
51
+should use the term “artifact hash” instead. There are two primary
52
+problems with miscallingtly, though we have
53
+not UUIDs:
54
+
55
+1. UUIDs are always 128 bits in length — 32 hex ASCII bytes — making
56
+ them shorter than any actual Fossil artifact hash.
57
+
58
+2. k-in
59
+names][cin]: comecessarily highly pseudorandom blobs, but only
60
+ [version 4 UUIDs][v4] are pseudorandom in the same way. Other UUID
61
+ types have non-random meanings for certain subgroups of the bits,
62
+ restrictions thattly, though we have
63
+not always meet.
64
+
65
+Therefore, no Fossil hash can ever be a proper UUID.
66
+
67
+Nevertheless, there are several places in Fossil where we still use the
68
+term UUID, primarily fd@v3,J:of these uses flow 2e@wU,E:Someday we maya@zb,H:influenced (e.g.
69
+q@~T,I: by making Fossil
70
+p@10_,G:coincident with
71
+r@11e,X: columns. Until
72
+then, Fossil will2C@14w,8:misnamed3W@176,o:we decide to rename these DB columns,
73
+we will keep H@1B0,K:internal identifiers6x@1Bo,3s:There are also some temporary tables that misuse “UUID” in this way.
74
+(`description.uuid`, `timeline.uuid`, `xmark.uuid`, etc.) There’s a good
75
+chance we’ll fix these before we fix the on-disk DB schema since no
76
+other code can depend on them5r@1Ih,C:“wrong.”d@1Of,27:misuse. Later, we
77
+may provide a parallel interface — e.g. `$tkt_hash` in this case — and
78
+drop mention of the old interface from theG@r0,K:but still
79
+support it11@1Ph,3:mis4D@1Qi,1B:misuse here for now, then possibly provide a backwards-compatible fix
80
+later84@1VE,2R:[uuid]: https://en.wikipedia.org/wiki/Universally_unique_identifier
81
+[v4]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)
82
+407YV;
--- a/www/hashes.md
+++ b/www/hashes.md
@@ -0,0 +1,82 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
--- a/www/hashes.md
+++ b/www/hashes.md
@@ -0,0 +1,82 @@
1 # Hashes: Fossil Artifact Idei# Hashes: Fossil Artifact Identification
2
3 All artifacts in Fossil are identified by a unique hash, currently using
4 [the SHA3 algorithm by default][hpol], but histori. Therefore, there are two full-length hash formats used by
5 Fossilcal| Algorithm | Raw Bits | Hex ASCII Bytes |
6 |-----------|----------|-----------------|
7 | SHA3-256 | 256 | 64 |
8 | SHA1 | 1>SHA1<td>160<td>40<tr><td>SHA1</td> <td>160</td> <td>40</td></tr>
9 </table> | 40 |
10
11 There are many types of artifacts in Fossil: commits (a.k.a. check-ins),
12 tickets, ticket comments, wiki articles, forum postings, file data
13 belonging to check-ins, etc. ([More info...](./concepts.wiki#artifacts)).
14
15 There is a looterms we try to use consistently, though we have
16 not always succeeded. We cover each of those termse this leaks out
17 s
18 parts of the Fossil UI, which we cover in the sections below.
19
20
21 ## Names
22
23 Several Fossil interfaces accept [a wide variety of check-in
24 names][cin]: commit
25
26 Artifact hashes are na
27
28 ## <a id="ues. We use
29 the broader termshes are onl, and we use the
30 e use
31 the broad term “namee specific terms when we mean one particular type of NAME.
32
33
34 ## Versions
35
36 When an artifact hash refers to a specific commit, Fossil sometimes
37 calls it a This is a
38 �s docs, UI, from, let us say, a wiki
39 type of artifact hash, dssil sometimes
40 calls it a “VERSION,” a “commit ID,” or a “check-in ID.”
41 We may eventually settle on one of these terms, but all three are type of artifact hash, distinct
42 from, let us say, a wiki article artifact hash.
43
44 A unique prefix of a VERSION hash is itself a VERSION. That is, if your
45 repository has exactly one commit artifact with a hash prefix nconventional Use Of The Term "UUID"
46
47 "UUID" is an acronym for "Univerially Unique Identifier". Hashes
48 geneUIDs: An Unfortunate Historical Artifact
49
50 Historically, Fossil incorrectly used the term “[UUID][uuid]” where it
51 should use the term “artifact hash” instead. There are two primary
52 problems with miscallingtly, though we have
53 not UUIDs:
54
55 1. UUIDs are always 128 bits in length — 32 hex ASCII bytes — making
56 them shorter than any actual Fossil artifact hash.
57
58 2. k-in
59 names][cin]: comecessarily highly pseudorandom blobs, but only
60 [version 4 UUIDs][v4] are pseudorandom in the same way. Other UUID
61 types have non-random meanings for certain subgroups of the bits,
62 restrictions thattly, though we have
63 not always meet.
64
65 Therefore, no Fossil hash can ever be a proper UUID.
66
67 Nevertheless, there are several places in Fossil where we still use the
68 term UUID, primarily fd@v3,J:of these uses flow 2e@wU,E:Someday we maya@zb,H:influenced (e.g.
69 q@~T,I: by making Fossil
70 p@10_,G:coincident with
71 r@11e,X: columns. Until
72 then, Fossil will2C@14w,8:misnamed3W@176,o:we decide to rename these DB columns,
73 we will keep H@1B0,K:internal identifiers6x@1Bo,3s:There are also some temporary tables that misuse “UUID” in this way.
74 (`description.uuid`, `timeline.uuid`, `xmark.uuid`, etc.) There’s a good
75 chance we’ll fix these before we fix the on-disk DB schema since no
76 other code can depend on them5r@1Ih,C:“wrong.”d@1Of,27:misuse. Later, we
77 may provide a parallel interface — e.g. `$tkt_hash` in this case — and
78 drop mention of the old interface from theG@r0,K:but still
79 support it11@1Ph,3:mis4D@1Qi,1B:misuse here for now, then possibly provide a backwards-compatible fix
80 later84@1VE,2R:[uuid]: https://en.wikipedia.org/wiki/Universally_unique_identifier
81 [v4]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)
82 407YV;
M www/mkindex.tcl
+1
--- www/mkindex.tcl
+++ www/mkindex.tcl
@@ -53,10 +53,11 @@
5353
 globs.md {File Name Glob Patterns}
5454
 gitusers.md {Hints For Users With Git Experience}
5555
 grep.md {Fossil grep vs POSIX grep}
5656
 hacker-howto.wiki {Hacker How-To}
5757
 hacker-howto.wiki {Fossil Developers Guide}
58
+ hashes.md {Hashes: Fossil Artifact Identification}
5859
 hashpolicy.wiki {Hash Policy: Choosing Between SHA1 and SHA3-256}
5960
 /help {Lists of Commands and Webpages}
6061
 hints.wiki {Fossil Tips And Usage Hints}
6162
 history.md {The Purpose And History Of Fossil}
6263
 index.wiki {Home Page}
6364
--- www/mkindex.tcl
+++ www/mkindex.tcl
@@ -53,10 +53,11 @@
53 globs.md {File Name Glob Patterns}
54 gitusers.md {Hints For Users With Git Experience}
55 grep.md {Fossil grep vs POSIX grep}
56 hacker-howto.wiki {Hacker How-To}
57 hacker-howto.wiki {Fossil Developers Guide}
 
58 hashpolicy.wiki {Hash Policy: Choosing Between SHA1 and SHA3-256}
59 /help {Lists of Commands and Webpages}
60 hints.wiki {Fossil Tips And Usage Hints}
61 history.md {The Purpose And History Of Fossil}
62 index.wiki {Home Page}
63
--- www/mkindex.tcl
+++ www/mkindex.tcl
@@ -53,10 +53,11 @@
53 globs.md {File Name Glob Patterns}
54 gitusers.md {Hints For Users With Git Experience}
55 grep.md {Fossil grep vs POSIX grep}
56 hacker-howto.wiki {Hacker How-To}
57 hacker-howto.wiki {Fossil Developers Guide}
58 hashes.md {Hashes: Fossil Artifact Identification}
59 hashpolicy.wiki {Hash Policy: Choosing Between SHA1 and SHA3-256}
60 /help {Lists of Commands and Webpages}
61 hints.wiki {Fossil Tips And Usage Hints}
62 history.md {The Purpose And History Of Fossil}
63 index.wiki {Home Page}
64

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button