Fossil SCM

Second-pass edit on www/hashes.md: more definite stances on things now that we have a ruling on the debate, and less flagellation all around.

wyoung 2020-05-28 19:47 trunk

Commit 3d808c4d0c71b5e1b428aecb9c9f1f69cd67b0c6fb131cd9fcbcccd131e4fb8a

Parent 364307951cf5224…

1 file changed +89 -88

~ www/hashes.md

M www/hashes.md

+89 -88

		--- www/hashes.md
		+++ www/hashes.md
		@@ -1,154 +1,155 @@
1	1	# Hashes: Fossil Artifact Identification
2	2
3	3	All artifacts in Fossil are identified by a unique hash, currently using
4	4	[the SHA3 algorithm by default][hpol], but historically using the SHA1
5		-algorithm. Therefore, there are two full-length hash formats used by
6		-Fossil:
	5	+algorithm:
7	6
8	7	<table border="1" cellspacing="0" cellpadding="10">
9		-<tr><th>Algorithm<th>Raw Bits<th>Hexadecimal digits
10		-<tr><td>SHA3-256<td>256<td>64
11		-<tr><td>SHA1<td>160<td>40
	8	+<tr><th>Algorithm<</th><th>Raw Bits</th> <th>Hexadecimal digits</th></tr>
	9	+<tr><td>SHA3-256</td> <td>256</td> <td>64</td></tr>
	10	+<tr><td>SHA1</td> <td>160</td> <td>40</td></tr>
12	11	</table>
13	12
14	13	There are many types of artifacts in Fossil: commits (a.k.a. check-ins),
15	14	tickets, ticket comments, wiki articles, forum postings, file data
16	15	belonging to check-ins, etc. ([More info...](./concepts.wiki#artifacts)).
17	16
18	17	There is a loose hierarchy of terms used instead of “hash” in various
19		-parts of the Fossil UI, terms we try to use consistently, though we have
20		-not always succeeded. We cover each of those terms in the sections
21		-below.
	18	+parts of the Fossil UI, which we cover in the sections below.
22	19
23	20
24	21	## Names
25	22
26	23	Several Fossil interfaces accept [a wide variety of check-in
27	24	names][cin]: commit artifact hashes, ISO8601 date strings, branch names,
28		-etc.
	25	+etc. Fossil interfaces that accept any of these options usually
	26	+document the parameter as “NAME”, so we will use that form to refer to
	27	+this specialized use.
29	28
30		-Artifact hashes are names, but not all names are artifact hashes. We use
31		-the broader term to refer to the whole class of options, and we use the
32		-specific terms when we mean one particular type of name.
	29	+Artifact hashes are only one of many different types of NAME. We use
	30	+the broad term “NAME” to refer to the whole class of options. We use
	31	+more specific terms when we mean one particular type of NAME.
33	32
34	33
35	34	## Versions
36	35
37	36	When an artifact hash refers to a specific commit, Fossil sometimes
38		-calls it a “VERSION,” a “commit ID,” or a “check-in ID.” This is a
39		-specific type of artifact hash, distinct from, let us say, a wiki
40		-article artifact hash.
41		-
	37	+calls it a “VERSION,” a “commit ID,” or a “check-in ID.”
42	38	We may eventually settle on one of these terms, but all three are
43	39	currently in common use within Fossil’s docs, UI, and programming
44	40	interfaces.
	41	+
	42	+A VERSION is a specific type of artifact hash, distinct
	43	+from, let us say, a wiki article artifact hash.
45	44
46	45	A unique prefix of a VERSION hash is itself a VERSION. That is, if your
47	46	repository has exactly one commit artifact with a hash prefix of
48	47	“abc123”, then that is a valid version string as long as it remains
49	48	unambiguous.
50	49
51	50
52	51
53		-## <a id="uvh"></a>Unconventional Use Of The Term "UUID"
54		-
55		-"UUID" is an acronym for "Univerially Unique Identifier". Hashes
56		-generated by SHA1 or SHA3-256 are universally unique (in practice,
57		-if not in theory) and they identify a particular artifact, and so
58		-it seems reasonable to refer to artifact hashes as UUIDs.
59		-
60		-However, the term UUID has acquired a much stricter meaning than its
61		-name alone implies. Purists insist that UUIDs must be exactly 128 bits,
62		-that they must be displayed in a particular hexadecimal format that includes
63		-dashes at proscribed intervals, and that they must have four particular bits
64		-set aside to indicate the "type" of UUID. Fossil artifact hashes do not
65		-comply with any of these supplemental requirements, and so are not UUIDs
66		-in the strictest sense of the word. But the artifact hashes in Fossil are
67		-literally "univerally unique identifiers", and so they are sometimes
68		-called "UUIDs" anyhow.
69		-
70		-Some readers are greatly annoyed by Fossil's use of "UUID" in its most
71		-literal sense. To those readers, the designer apologizes, and seeks your
72		-mercy by noting that when the term "UUID" first began to be used by Fossil,
73		-only SHA1 was supported and so all the artifact hashes were 128 bits, making
74		-them close to, if not exactly, in compliance with the rigid definition
75		-of the term. For his misuse of the term "UUID", the designer has been
76		-frequently rebuked.
77		-Some efforts have been made, over the ensuing years, to avoid and replace
78		-"UUID" in newer code and documentation.
79		-But it does not seem like such a serious issue as to require an immediate
80		-purge of the term from existing documentation, code, and database schemas,
81		-as some have suggested. Hence, the unconventional use of the term "UUID"
82		-lingers on in Fossil. Let new readers beware.
83		-
84		-Places where the non-conforming use of "UUID" persists in Fossil are
85		-discussed in the sequel.
	52	+## <a id="uvh"></a>UUIDs
	53	+
	54	+Fossil uses the term “UUID” as a short alias for “artifact hash” in its
	55	+internals. There are a few places where this leaks out into external
	56	+interfaces, which we cover in the sections below. Going forward, we
	57	+prefer one of the terms above in public interfaces instead.
	58	+
	59	+Whether this short alias is correct is debateable.
	60	+
	61	+One argument is that since "UUID" is an acronym for “Univerially Unique
	62	+Identifier,” and both SHA1 and SHA3-256 are larger and stronger than the
	63	+128-bit algorithms used by “proper” UUIDs, Fossil artifact hashes are
	64	+more universally unique. It is therefore quibbling to say that Fossil
	65	+UUIDs are not actually UUIDs. One wag suggested that Fossil artifact
	66	+hashes be called MUIDs: multiversally unique IDs.
	67	+
	68	+The common counterargument is that the acronym “UUID” was created for [a
	69	+particular type of universally-unique ID][uuid], with particular ASCII
	70	+and bitfield formats, and with particular meaning given to certain of
	71	+its bits. In that sense, no Fossil “UUID” can be used as a proper UUID.
	72	+
	73	+Be warned: attempting to advance the second position on the Fossil
	74	+discussion forum will get you nowhere at this late date. We’ve had the
	75	+debates, we’ve done the engineering, and we’ve made our evaluation. It’s
	76	+a settled matter: internally within Fossil, “UUID” is defined as in this
	77	+section’s leading paragraph.
	78	+
	79	+To those who remain unconvinced, “fixing” this would require touching
	80	+almost every source code file in Fossil in a total of about a thousand
	81	+separate locations. (Not exaggeration, actual data.) This would be a
	82	+massive undertaking simply to deal with a small matter of terminology,
	83	+with a high risk of creating bugs and downstream incompatibilities.
	84	+Therefore, we are highly unlikely to change this ourselves, and we are
	85	+also unlikely to accept a patch that attempts to fix it.
86	86
87	87
88	88	### Repository DB Schema
89	89
90		-Almost all remaining uses of the term "UUID" in Fossil derive
91		-from the `blob.uuid` table column. This is
92		-a key lookup column in the most important persistent Fossil DB table, so
93		-it influences broad swaths of the Fossil internals.
94		-
95		-It is theoretically possible to rename this column and those it has
96		-influenced (e.g. `purgeitem.uuid`, `shun.uuid`, and `ticket.tkt_uuid`)
97		-by making Fossil detect the outdated schema and silently upgrade it,
98		-coincident with updating all of the SQL in Fossil that refers to these
99		-columns. But that is a large and error-prone edit that does
100		-serve any pressing need, and so is unlikely to happen any time soon.
101		-Hence, Fossil will likely continue to have “UUID” all through its internals.
102		-
103		-In order to avoid needless terminology conflicts, Fossil code that
104		-refers to these columns also uses some variant of “UUID.” For
105		-example, C code that refers to SQL result data on `blob.uuid` usually
106		-calls the variable `zUuid`. Another example is the internal function
107		-`uuid_to_rid()`. Until and unless the columns are renamed,
108		-these associated function names will likely also go unchanged.
	90	+The primary place where you find "UUID" in Fossil is in the `blob.uuid`
	91	+table column, in code dealing with that column, and in code manipulating
	92	+other data that refers to that column. This is a key lookup column
	93	+in the most important Fossil DB table, so it influences broad swaths of
	94	+the Fossil internals.
	95	+
	96	+For example, C code that refers to SQL result data on `blob.uuid`
	97	+usually calls the variable `zUuid`. That value may then be inserted into
	98	+a table like `ticket.tkt_uuid`, creating a reference back to
	99	+`blob.uuid`, and then be passed to a function like `uuid_to_rid()`.
	100	+There is no point renaming a single one of these in isolation: it would
	101	+create needless terminology conflicts, making the code hard to read and
	102	+understand, risking the creation of new bugs.
109	103
110	104	You may have local SQL code that digs into the repository DB using these
111		-column names. If so, be warned: we are not inclined to consider
112		-existence of such code sufficient reason to avoid renaming the columns.
113		-The Fossil repository DB schema is not considered an external user
114		-interface, and internal interfaces are subject to change at any time. We
115		-suggest switching to a more stable API: the JSON API, `/timeline.rss`,
116		-TH1, etc.
	105	+column names. While you may rest easy, assured now that we are highly
	106	+unlikely to ever rename these columns, the Fossil repository DB schema
	107	+is not considered an external user interface, and internal interfaces
	108	+are subject to change at any time. We suggest switching to a more stable
	109	+API: [the JSON API][japi], [`timeline.rss`][trss], [TH1][th1], etc.
117	110
118	111
119	112	### TH1 Scripting Interfaces
120	113
121		-Some [TH1](./th1.md) interfaces use “UUID” where they actually mean some
122		-kind of hash. For example, the `$tkt_uuid` variable, available via TH1
123		-when [customizing Fossil’s ticket system][ctkt].
124		-
125		-Because this is considered a public programming interface, we are
126		-unwilling to unilaterally rename such TH1 variables, even though they
127		-are "wrong". For now, we are simply documenting the unconventional
128		-terminology.
	114	+Some [TH1][th1] interfaces expose Fossil internals flowing from
	115	+`blob.uuid`, so “UUID” is a short alias for “artifact hash” in TH1. For
	116	+example, the `$tkt_uuid` variable — available when [customizing
	117	+the ticket system][ctkt] — is a ticket artifact hash, exposing the
	118	+`ticket.tkt_uuid` column, which has a SQL relation to `blob.uuid`.
	119	+
	120	+TH1 is a longstanding public programming interface. We cannot rename its
	121	+interfaces without breaking existing TH1 Fossil customizations. We are
	122	+also unlikely to provide a parallel set of variables with “better”
	123	+names, since that would create a mismatch with respect to the internals
	124	+they expose, creating a different sort of developer confusion in its
	125	+place.
129	126
130	127
131	128	### JSON API Parameters and Outputs
132	129
133		-The JSON API frequently uses the term “UUID” in the same sort of way,
134		-most commonly in [artifact][jart] and [timeline][jtim] APIs. As with the
135		-prior case, we can’t fix these without breaking code that uses the JSON
136		-API as originally designed, so our solutions are the same: document the
137		-unconventional usage.
	130	+[The JSON API][japi] frequently uses the term “UUID” in the same sort of way,
	131	+most commonly in [artifact][jart] and [timeline][jtim] APIs. As with
	132	+TH1, we can’t change this without breaking code that uses the JSON
	133	+API as originally designed, so we take the same stance.
138	134
139	135
140	136	### `manifest.uuid`
141	137
142	138	If you have [the `manifest` setting][mset] enabled, Fossil writes a file
143	139	called `manifest.uuid` at the root of the check-out tree containing the
144	140	commit hash for the current checked-out version. Because this is a
145		-public interface, we are unwilling to rename the file for correctness.
	141	+public interface that existing code depends on, we are unwilling to
	142	+rename the file.
146	143
147	144
148	145	[cin]: ./checkin_names.wiki
149	146	[ctkt]: ./custom_ticket.wiki
150	147	[hpol]: ./hashpolicy.wiki
	148	+[japi]: ./json-api/
151	149	[jart]: ./json-api/api-artifact.md
152	150	[jtim]: ./json-api/api-timeline.md
153	151	[mset]: /help?cmd=manifest
	152	+[th1]: ./th1.md
	153	+[trss]: /help?cmd=/timeline.rss
154	154	[tvb]: ./branching.wiki
	155	+[uuid]: https://en.wikipedia.org/wiki/Universally_unique_identifier
155	156

	--- www/hashes.md
	+++ www/hashes.md
	@@ -1,154 +1,155 @@
1	# 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 historically using the SHA1
5	algorithm. Therefore, there are two full-length hash formats used by
6	Fossil:
7
8	<table border="1" cellspacing="0" cellpadding="10">
9	<tr><th>Algorithm<th>Raw Bits<th>Hexadecimal digits
10	<tr><td>SHA3-256<td>256<td>64
11	<tr><td>SHA1<td>160<td>40
12	</table>
13
14	There are many types of artifacts in Fossil: commits (a.k.a. check-ins),
15	tickets, ticket comments, wiki articles, forum postings, file data
16	belonging to check-ins, etc. ([More info...](./concepts.wiki#artifacts)).
17
18	There is a loose hierarchy of terms used instead of “hash” in various
19	parts of the Fossil UI, terms we try to use consistently, though we have
20	not always succeeded. We cover each of those terms in the sections
21	below.
22
23
24	## Names
25
26	Several Fossil interfaces accept [a wide variety of check-in
27	names][cin]: commit artifact hashes, ISO8601 date strings, branch names,
28	etc.


29
30	Artifact hashes are names, but not all names are artifact hashes. We use
31	the broader term to refer to the whole class of options, and we use the
32	specific terms when we mean one particular type of name.
33
34
35	## Versions
36
37	When an artifact hash refers to a specific commit, Fossil sometimes
38	calls it a “VERSION,” a “commit ID,” or a “check-in ID.” This is a
39	specific type of artifact hash, distinct from, let us say, a wiki
40	article artifact hash.
41
42	We may eventually settle on one of these terms, but all three are
43	currently in common use within Fossil’s docs, UI, and programming
44	interfaces.



45
46	A unique prefix of a VERSION hash is itself a VERSION. That is, if your
47	repository has exactly one commit artifact with a hash prefix of
48	“abc123”, then that is a valid version string as long as it remains
49	unambiguous.
50
51
52
53	## <a id="uvh"></a>Unconventional Use Of The Term "UUID"
54
55	"UUID" is an acronym for "Univerially Unique Identifier". Hashes
56	generated by SHA1 or SHA3-256 are universally unique (in practice,
57	if not in theory) and they identify a particular artifact, and so
58	it seems reasonable to refer to artifact hashes as UUIDs.
59
60	However, the term UUID has acquired a much stricter meaning than its
61	name alone implies. Purists insist that UUIDs must be exactly 128 bits,
62	that they must be displayed in a particular hexadecimal format that includes
63	dashes at proscribed intervals, and that they must have four particular bits
64	set aside to indicate the "type" of UUID. Fossil artifact hashes do not
65	comply with any of these supplemental requirements, and so are not UUIDs
66	in the strictest sense of the word. But the artifact hashes in Fossil are
67	literally "univerally unique identifiers", and so they are sometimes
68	called "UUIDs" anyhow.
69
70	Some readers are greatly annoyed by Fossil's use of "UUID" in its most
71	literal sense. To those readers, the designer apologizes, and seeks your
72	mercy by noting that when the term "UUID" first began to be used by Fossil,
73	only SHA1 was supported and so all the artifact hashes were 128 bits, making
74	them close to, if not exactly, in compliance with the rigid definition
75	of the term. For his misuse of the term "UUID", the designer has been
76	frequently rebuked.
77	Some efforts have been made, over the ensuing years, to avoid and replace
78	"UUID" in newer code and documentation.
79	But it does not seem like such a serious issue as to require an immediate
80	purge of the term from existing documentation, code, and database schemas,
81	as some have suggested. Hence, the unconventional use of the term "UUID"
82	lingers on in Fossil. Let new readers beware.
83
84	Places where the non-conforming use of "UUID" persists in Fossil are
85	discussed in the sequel.

86
87
88	### Repository DB Schema
89
90	Almost all remaining uses of the term "UUID" in Fossil derive
91	from the `blob.uuid` table column. This is
92	a key lookup column in the most important persistent Fossil DB table, so
93	it influences broad swaths of the Fossil internals.
94
95	It is theoretically possible to rename this column and those it has
96	influenced (e.g. `purgeitem.uuid`, `shun.uuid`, and `ticket.tkt_uuid`)
97	by making Fossil detect the outdated schema and silently upgrade it,
98	coincident with updating all of the SQL in Fossil that refers to these
99	columns. But that is a large and error-prone edit that does
100	serve any pressing need, and so is unlikely to happen any time soon.
101	Hence, Fossil will likely continue to have “UUID” all through its internals.
102
103	In order to avoid needless terminology conflicts, Fossil code that
104	refers to these columns also uses some variant of “UUID.” For
105	example, C code that refers to SQL result data on `blob.uuid` usually
106	calls the variable `zUuid`. Another example is the internal function
107	`uuid_to_rid()`. Until and unless the columns are renamed,
108	these associated function names will likely also go unchanged.
109
110	You may have local SQL code that digs into the repository DB using these
111	column names. If so, be warned: we are not inclined to consider
112	existence of such code sufficient reason to avoid renaming the columns.
113	The Fossil repository DB schema is not considered an external user
114	interface, and internal interfaces are subject to change at any time. We
115	suggest switching to a more stable API: the JSON API, `/timeline.rss`,
116	TH1, etc.
117
118
119	### TH1 Scripting Interfaces
120
121	Some [TH1](./th1.md) interfaces use “UUID” where they actually mean some
122	kind of hash. For example, the `$tkt_uuid` variable, available via TH1
123	when [customizing Fossil’s ticket system][ctkt].
124
125	Because this is considered a public programming interface, we are
126	unwilling to unilaterally rename such TH1 variables, even though they
127	are "wrong". For now, we are simply documenting the unconventional
128	terminology.




129
130
131	### JSON API Parameters and Outputs
132
133	The JSON API frequently uses the term “UUID” in the same sort of way,
134	most commonly in [artifact][jart] and [timeline][jtim] APIs. As with the
135	prior case, we can’t fix these without breaking code that uses the JSON
136	API as originally designed, so our solutions are the same: document the
137	unconventional usage.
138
139
140	### `manifest.uuid`
141
142	If you have [the `manifest` setting][mset] enabled, Fossil writes a file
143	called `manifest.uuid` at the root of the check-out tree containing the
144	commit hash for the current checked-out version. Because this is a
145	public interface, we are unwilling to rename the file for correctness.

146
147
148	[cin]: ./checkin_names.wiki
149	[ctkt]: ./custom_ticket.wiki
150	[hpol]: ./hashpolicy.wiki

151	[jart]: ./json-api/api-artifact.md
152	[jtim]: ./json-api/api-timeline.md
153	[mset]: /help?cmd=manifest


154	[tvb]: ./branching.wiki

155

	--- www/hashes.md
	+++ www/hashes.md
	@@ -1,154 +1,155 @@
1	# 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 historically using the SHA1
5	algorithm:

6
7	<table border="1" cellspacing="0" cellpadding="10">
8	<tr><th>Algorithm<</th><th>Raw Bits</th> <th>Hexadecimal digits</th></tr>
9	<tr><td>SHA3-256</td> <td>256</td> <td>64</td></tr>
10	<tr><td>SHA1</td> <td>160</td> <td>40</td></tr>
11	</table>
12
13	There are many types of artifacts in Fossil: commits (a.k.a. check-ins),
14	tickets, ticket comments, wiki articles, forum postings, file data
15	belonging to check-ins, etc. ([More info...](./concepts.wiki#artifacts)).
16
17	There is a loose hierarchy of terms used instead of “hash” in various
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 artifact hashes, ISO8601 date strings, branch names,
25	etc. Fossil interfaces that accept any of these options usually
26	document the parameter as “NAME”, so we will use that form to refer to
27	this specialized use.
28
29	Artifact hashes are only one of many different types of NAME. We use
30	the broad term “NAME” to refer to the whole class of options. We use
31	more 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 “VERSION,” a “commit ID,” or a “check-in ID.”



38	We may eventually settle on one of these terms, but all three are
39	currently in common use within Fossil’s docs, UI, and programming
40	interfaces.
41
42	A VERSION is a specific type of artifact hash, distinct
43	from, let us say, a wiki article artifact hash.
44
45	A unique prefix of a VERSION hash is itself a VERSION. That is, if your
46	repository has exactly one commit artifact with a hash prefix of
47	“abc123”, then that is a valid version string as long as it remains
48	unambiguous.
49
50
51
52	## <a id="uvh"></a>UUIDs
53
54	Fossil uses the term “UUID” as a short alias for “artifact hash” in its
55	internals. There are a few places where this leaks out into external
56	interfaces, which we cover in the sections below. Going forward, we
57	prefer one of the terms above in public interfaces instead.
58
59	Whether this short alias is correct is debateable.
60
61	One argument is that since "UUID" is an acronym for “Univerially Unique
62	Identifier,” and both SHA1 and SHA3-256 are larger and stronger than the
63	128-bit algorithms used by “proper” UUIDs, Fossil artifact hashes are
64	more universally unique. It is therefore quibbling to say that Fossil
65	UUIDs are not actually UUIDs. One wag suggested that Fossil artifact
66	hashes be called MUIDs: multiversally unique IDs.
67
68	The common counterargument is that the acronym “UUID” was created for [a
69	particular type of universally-unique ID][uuid], with particular ASCII
70	and bitfield formats, and with particular meaning given to certain of
71	its bits. In that sense, no Fossil “UUID” can be used as a proper UUID.
72
73	Be warned: attempting to advance the second position on the Fossil
74	discussion forum will get you nowhere at this late date. We’ve had the
75	debates, we’ve done the engineering, and we’ve made our evaluation. It’s
76	a settled matter: internally within Fossil, “UUID” is defined as in this
77	section’s leading paragraph.
78
79	To those who remain unconvinced, “fixing” this would require touching
80	almost every source code file in Fossil in a total of about a thousand
81	separate locations. (Not exaggeration, actual data.) This would be a
82	massive undertaking simply to deal with a small matter of terminology,
83	with a high risk of creating bugs and downstream incompatibilities.
84	Therefore, we are highly unlikely to change this ourselves, and we are
85	also unlikely to accept a patch that attempts to fix it.
86
87
88	### Repository DB Schema
89
90	The primary place where you find "UUID" in Fossil is in the `blob.uuid`
91	table column, in code dealing with that column, and in code manipulating
92	other data that refers to that column. This is a key lookup column
93	in the most important Fossil DB table, so it influences broad swaths of
94	the Fossil internals.
95
96	For example, C code that refers to SQL result data on `blob.uuid`
97	usually calls the variable `zUuid`. That value may then be inserted into
98	a table like `ticket.tkt_uuid`, creating a reference back to
99	`blob.uuid`, and then be passed to a function like `uuid_to_rid()`.
100	There is no point renaming a single one of these in isolation: it would
101	create needless terminology conflicts, making the code hard to read and
102	understand, risking the creation of new bugs.






103
104	You may have local SQL code that digs into the repository DB using these
105	column names. While you may rest easy, assured now that we are highly
106	unlikely to ever rename these columns, the Fossil repository DB schema
107	is not considered an external user interface, and internal interfaces
108	are subject to change at any time. We suggest switching to a more stable
109	API: [the JSON API][japi], [`timeline.rss`][trss], [TH1][th1], etc.

110
111
112	### TH1 Scripting Interfaces
113
114	Some [TH1][th1] interfaces expose Fossil internals flowing from
115	`blob.uuid`, so “UUID” is a short alias for “artifact hash” in TH1. For
116	example, the `$tkt_uuid` variable — available when [customizing
117	the ticket system][ctkt] — is a ticket artifact hash, exposing the
118	`ticket.tkt_uuid` column, which has a SQL relation to `blob.uuid`.
119
120	TH1 is a longstanding public programming interface. We cannot rename its
121	interfaces without breaking existing TH1 Fossil customizations. We are
122	also unlikely to provide a parallel set of variables with “better”
123	names, since that would create a mismatch with respect to the internals
124	they expose, creating a different sort of developer confusion in its
125	place.
126
127
128	### JSON API Parameters and Outputs
129
130	[The JSON API][japi] frequently uses the term “UUID” in the same sort of way,
131	most commonly in [artifact][jart] and [timeline][jtim] APIs. As with
132	TH1, we can’t change this without breaking code that uses the JSON
133	API as originally designed, so we take the same stance.

134
135
136	### `manifest.uuid`
137
138	If you have [the `manifest` setting][mset] enabled, Fossil writes a file
139	called `manifest.uuid` at the root of the check-out tree containing the
140	commit hash for the current checked-out version. Because this is a
141	public interface that existing code depends on, we are unwilling to
142	rename the file.
143
144
145	[cin]: ./checkin_names.wiki
146	[ctkt]: ./custom_ticket.wiki
147	[hpol]: ./hashpolicy.wiki
148	[japi]: ./json-api/
149	[jart]: ./json-api/api-artifact.md
150	[jtim]: ./json-api/api-timeline.md
151	[mset]: /help?cmd=manifest
152	[th1]: ./th1.md
153	[trss]: /help?cmd=/timeline.rss
154	[tvb]: ./branching.wiki
155	[uuid]: https://en.wikipedia.org/wiki/Universally_unique_identifier
156

Fossil SCM

Keyboard Shortcuts