Fossil SCM

fossil-scm / www / fileformat.wiki

Source Blame History 960 lines

16e703b…	drh	1	<title>Fossil File Formats</title>
f94f7e5…	drh	2
7c2577b…	drh	3	The global state of a fossil repository is kept simple so that it can
f47b705…	jan.nijtmans	4	endure in useful form for decades or centuries.
adc0b3b…	drh	5	A fossil repository is intended to be readable,
7c2577b…	drh	6	searchable, and extensible by people not yet born.
adc0b3b…	drh	7
efb759a…	drh	8	The global state of a fossil repository is an unordered
adc0b3b…	drh	9	set of <i>artifacts</i>.
f94f7e5…	drh	10	An artifact might be a source code file, the text of a wiki page,
fd9b7bd…	drh	11	part of a trouble ticket, a description of a check-in including all
fd9b7bd…	drh	12	the files in that check-in with the check-in comment and so forth.
fd9b7bd…	drh	13	Artifacts are broadly grouped into two types: content artifacts and
fd9b7bd…	drh	14	structural artifacts. Content artifacts are the raw project source-code
fd9b7bd…	drh	15	files that are checked into the repository. Structural artifacts have
fd9b7bd…	drh	16	special formatting rules and are used to show the relationships between
fd9b7bd…	drh	17	other artifacts in the repository. It is possible for an artifact to
fd9b7bd…	drh	18	be both a structure artifact and a content artifact, though this is
fd9b7bd…	drh	19	rare. Artifacts can be text or binary.
7c2577b…	drh	20
f47b705…	jan.nijtmans	21	In addition to the global state,
efb759a…	drh	22	each fossil repository also contains local state.
efb759a…	drh	23	The local state consists of web-page formatting
efb759a…	drh	24	preferences, authorized users, ticket display and reporting formats,
efb759a…	drh	25	and so forth. The global state is shared in common among all
efb759a…	drh	26	repositories for the same project, whereas the local state is often
efb759a…	drh	27	different in separate repositories.
efb759a…	drh	28	The local state is not versioned and is not synchronized
efb759a…	drh	29	with the global state.
efb759a…	drh	30	The local state is not composed of artifacts and is not intended to be enduring.
efb759a…	drh	31	This document is concerned with global state only. Local state is only
efb759a…	drh	32	mentioned here in order to distinguish it from global state.
7c2577b…	drh	33
93cee1f…	wyoung	34	<h2 id="names">1.0 Artifact Names</h2>
fd9b7bd…	drh	35
fd9b7bd…	drh	36	Each artifact in the repository is named by a hash of its content.
fd9b7bd…	drh	37	No prefixes, suffixes, or other information is added to an artifact before
fd9b7bd…	drh	38	the hash is computed. The artifact name is just the (lower-case
fd9b7bd…	drh	39	hexadecimal) hash of the raw artifact.
fd9b7bd…	drh	40
796db89…	drh	41	Fossil currently computes artifact names using either SHA1 or SHA3-256. It
796db89…	drh	42	is relatively easy to add new algorithms in the future, but there are no
b098c93…	jan.nijtmans	43	plans to do so at this time.
796db89…	drh	44
b098c93…	jan.nijtmans	45	When referring to artifacts in using tty commands or webpage URLs, it is
fd9b7bd…	drh	46	sufficient to specify a unique prefix for the artifact name. If the input
fd9b7bd…	drh	47	prefix is not unique, Fossil will show an error. Within a structural
fd9b7bd…	drh	48	artifact, however, all references to other artifacts must be the complete
fd9b7bd…	drh	49	hash.
fd9b7bd…	drh	50
fd9b7bd…	drh	51	Prior to Fossil version 2.0, all names were formed from the SHA1 hash of
fd9b7bd…	drh	52	the artifact. The key innovation in Fossil 2.0 was adding support for
fd9b7bd…	drh	53	alternative hash algorithms.
fd9b7bd…	drh	54
93cee1f…	wyoung	55	<h2 id="structural">2.0 Structural Artifacts</h2>
fd9b7bd…	drh	56
796db89…	drh	57	A structural artifact is an artifact with a particular format
fd9b7bd…	drh	58	that is used to define the relationships between other artifacts in the
fd9b7bd…	drh	59	repository.
fd9b7bd…	drh	60	Fossil recognizes the following kinds of structural
fd9b7bd…	drh	61	artifacts:
f94f7e5…	drh	62
f94f7e5…	drh	63	<ul>
7c2577b…	drh	64	<li> [#manifest \| Manifests] </li>
7c2577b…	drh	65	<li> [#cluster \| Clusters] </li>
26a82dd…	stephan	66	<li> [#ctrl \| Control (a.k.a. Tag) Artifacts] </li>
7c2577b…	drh	67	<li> [#wikichng \| Wiki Pages] </li>
7c2577b…	drh	68	<li> [#tktchng \| Ticket Changes] </li>
6c73d1b…	BMorgat	69	<li> [#attachment \| Attachments] </li>
bd50848…	drh	70	<li> [#event \| TechNotes] </li>
99fcc43…	drh	71	<li> [#forum \| Forum Posts] </li>
f94f7e5…	drh	72	</ul>
f94f7e5…	drh	73
99fcc43…	drh	74	These eight structural artifact types are described in subsections below.
c8893c6…	drh	75
cc21489…	drh	76	Structural artifacts are UTF-8 text. The artifact may be PGP clearsigned.
fd9b7bd…	drh	77	After removal of the PGP clearsign header and suffix (if any) a structural
fd9b7bd…	drh	78	artifact consists of one or more "cards" separated by a single newline
fd9b7bd…	drh	79	(ASCII: 0x0a) character. Each card begins with a single
fd9b7bd…	drh	80	character "card type". Zero or more arguments may follow
fd9b7bd…	drh	81	the card type. All arguments are separated from each other
fd9b7bd…	drh	82	and from the card-type character by a single space
fd9b7bd…	drh	83	character. There is no surplus white space between arguments
fd9b7bd…	drh	84	and no leading or trailing whitespace except for the newline
fd9b7bd…	drh	85	character that acts as the card separator. All cards must be in strict
023fdde…	drh	86	lexicographical order (except for an
023fdde…	drh	87	[./fileformat.wiki#outofordercards\|historical bug compatibility]).
023fdde…	drh	88	There may not be any duplicate cards.
fd9b7bd…	drh	89
fd9b7bd…	drh	90	In the current implementation (as of 2017-02-27) the artifacts that
f7d7ce3…	drh	91	make up a fossil repository are stored as delta- and zlib-compressed
c8893c6…	drh	92	blobs in an <a href="http://www.sqlite.org/">SQLite</a> database. This
c8893c6…	drh	93	is an implementation detail and might change in a future release. For
c8893c6…	drh	94	the purpose of this article "file format" means the format of the artifacts,
c8893c6…	drh	95	not how the artifacts are stored on disk. It is the artifact format that
c8893c6…	drh	96	is intended to be enduring. The specifics of how artifacts are stored on
c664695…	drh	97	disk, though stable, is not intended to live as long as the
7c2577b…	drh	98	artifact format.
c8893c6…	drh	99
93cee1f…	wyoung	100	<h3 id="manifest">2.1 The Manifest</h3>
fd9b7bd…	drh	101
fd9b7bd…	drh	102	A manifest defines a check-in.
fd9b7bd…	drh	103	A manifest contains a list of artifacts for
c8893c6…	drh	104	each file in the project and the corresponding filenames, as
fd9b7bd…	drh	105	well as information such as parent check-ins, the username of the
904ee40…	drh	106	programmer who created the check-in, the date and time when
904ee40…	drh	107	the check-in was created, and any check-in comments associated
7c2577b…	drh	108	with the check-in.
7c2577b…	drh	109
f94f7e5…	drh	110	Allowed cards in the manifest are as follows:
f94f7e5…	drh	111
d8e2a3b…	wyoung	112	<div class="indent">
d13054c…	drh	113	<b>B</b> <i>baseline-manifest</i><br>
f94f7e5…	drh	114	<b>C</b> <i>checkin-comment</i><br>
f94f7e5…	drh	115	<b>D</b> <i>time-and-date-stamp</i><br>
fd9b7bd…	drh	116	<b>F</b> <i>filename</i> ?<i>hash</i>? ?<i>permissions</i>? ?<i>old-name</i>?<br>
4dcea80…	drh	117	<b>N</b> <i>mimetype</i><br>
fd9b7bd…	drh	118	<b>P</b> <i>artifact-hash</i>+<br>
fd9b7bd…	drh	119	<b>Q</b> (<b>+</b>\|<b>-</b>)<i>artifact-hash</i> ?<i>artifact-hash</i>?<br>
f94f7e5…	drh	120	<b>R</b> <i>repository-checksum</i><br>
4e9522a…	mistachkin	121	<b>T</b> (<b>+</b>\|<b>-</b>\|<b></b>)<i>tag-name</i> <b></b> ?<i>value</i>?<br>
f94f7e5…	drh	122	<b>U</b> <i>user-login</i><br>
f94f7e5…	drh	123	<b>Z</b> <i>manifest-checksum</i>
d8e2a3b…	wyoung	124	</div>
f94f7e5…	drh	125
a1437b2…	wyoung	126	A manifest may optionally have a single <b>B</b> card. The <b>B</b> card specifies
d13054c…	drh	127	another manifest that serves as the "baseline" for this manifest. A
a1437b2…	wyoung	128	manifest that has a <b>B</b> card is called a delta-manifest and a manifest
a1437b2…	wyoung	129	that omits the <b>B</b> card is a baseline-manifest. The other manifest
a1437b2…	wyoung	130	identified by the argument of the <b>B</b> card must be a baseline-manifest.
fe38a76…	drh	131	A baseline-manifest records the complete contents of a check-in.
f47b705…	jan.nijtmans	132	A delta-manifest records only changes from its baseline.
fe38a76…	drh	133
a1437b2…	wyoung	134	A manifest must have exactly one <b>C</b> card. The sole argument to
a1437b2…	wyoung	135	the <b>C</b> card is a check-in comment that describes the check-in that
f94f7e5…	drh	136	the manifest defines. The check-in comment is text. The following
f94f7e5…	drh	137	escape sequences are applied to the text:
f94f7e5…	drh	138	A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A
f47b705…	jan.nijtmans	139	newline (ASCII 0x0a) is "\n" (ASCII 0x5C, x6E). A backslash
f94f7e5…	drh	140	(ASCII 0x5C) is represented as two backslashes "\\". Apart from
f94f7e5…	drh	141	space and newline, no other whitespace characters are allowed in
f94f7e5…	drh	142	the check-in comment. Nor are any unprintable characters allowed
f94f7e5…	drh	143	in the comment.
f94f7e5…	drh	144
a1437b2…	wyoung	145	A manifest must have exactly one <b>D</b> card. The sole argument to
a1437b2…	wyoung	146	the <b>D</b> card is a date-time stamp in the ISO8601 format. The
f94f7e5…	drh	147	date and time should be in coordinated universal time (UTC).
722d7ca…	drh	148	The format one of:
722d7ca…	drh	149
d8e2a3b…	wyoung	150	<pre class="indent"><i>YYYY-MM-DD<b>T</b>HH:MM:SS
d8e2a3b…	wyoung	151	YYYY-MM-DD<b>T</b>HH:MM:SS.SSS</i></pre>
007c32b…	stephan	152
a1437b2…	wyoung	153	A manifest has zero or more <b>F</b> cards. Each <b>F</b> card identifies a file
007c32b…	stephan	154	that is part of the check-in. There are one, two, three, or four
007c32b…	stephan	155	arguments. The first argument is the pathname of the file in the
007c32b…	stephan	156	check-in relative to the root of the project file hierarchy. No ".."
007c32b…	stephan	157	or "." directories are allowed within the filename. Space characters
a1437b2…	wyoung	158	are escaped as in <b>C</b> card comment text. Backslash characters and
007c32b…	stephan	159	newlines are not allowed within filenames. The directory separator
007c32b…	stephan	160	character is a forward slash (ASCII 0x2F). The second argument to the
a1437b2…	wyoung	161	<b>F</b> card is the lower-case hexadecimal artifact hash of
007c32b…	stephan	162	the content artifact. The second argument is required for baseline
007c32b…	stephan	163	manifests but is optional for delta manifests. When the second
a1437b2…	wyoung	164	argument to the <b>F</b> card is omitted, it means that the file has been
007c32b…	stephan	165	deleted relative to the baseline (files removed in baseline manifests
a1437b2…	wyoung	166	versions are <em>not</em> added as <b>F</b> cards). The optional 3rd argument
007c32b…	stephan	167	defines any special access permissions associated with the file. This
007c32b…	stephan	168	can be defined as "x" to mean that the file is executable or "l"
007c32b…	stephan	169	(small letter ell) to mean a symlink. All files are always readable
007c32b…	stephan	170	and writable. This can be expressed by "w" permission if desired but
007c32b…	stephan	171	is optional. The file format might be extended with new permission
007c32b…	stephan	172	letters in the future. The optional 4th argument is the name of the
007c32b…	stephan	173	same file as it existed in the parent check-in. If the name of the
007c32b…	stephan	174	file is unchanged from its parent, then the 4th argument is omitted.
007c32b…	stephan	175
a1437b2…	wyoung	176	A manifest has zero or one <b>N</b> cards. The <b>N</b> card specifies the mimetype for the
a1437b2…	wyoung	177	text in the comment of the <b>C</b> card. If the <b>N</b> card is omitted, a default mimetype
1ec8dee…	drh	178	is used. Note that the <b>N</b> card has never actually been used by
1ec8dee…	drh	179	any Fossil implementation. The implementation has always interpreted
1ec8dee…	drh	180	check-in comments according to the [/wiki_rules\|Fossil Wiki formatting rules].
1ec8dee…	drh	181	There are no current plans to ever change that.
9c2116a…	andygoth	182
a1437b2…	wyoung	183	A manifest has zero or one <b>P</b> cards. Most manifests have one <b>P</b> card.
a1437b2…	wyoung	184	The <b>P</b> card has a varying number of arguments that
9c2116a…	andygoth	185	define other manifests from which the current manifest
fd9b7bd…	drh	186	is derived. Each argument is a lowercase
fd9b7bd…	drh	187	hexadecimal artifact hash of a predecessor manifest. All arguments
a1437b2…	wyoung	188	to the <b>P</b> card must be unique within that card.
fd9b7bd…	drh	189	The first argument is the artifact hash of the direct ancestor of the manifest.
f94f7e5…	drh	190	Other arguments define manifests with which the first was
f94f7e5…	drh	191	merged to yield the current manifest. Most manifests have
a1437b2…	wyoung	192	a <b>P</b> card with a single argument. The first manifest in the
a1437b2…	wyoung	193	project has no ancestors and thus has no <b>P</b> card or (depending
a1437b2…	wyoung	194	on the Fossil version) an empty <b>P</b> card (no arguments).
904ee40…	drh	195
a1437b2…	wyoung	196	A manifest has zero or more <b>Q</b> cards. A <b>Q</b> card is similar to a <b>P</b> card
7fcbbb1…	drh	197	in that it defines a predecessor to the current check-in. But
a1437b2…	wyoung	198	whereas a <b>P</b> card defines the immediate ancestor or a merge
a1437b2…	wyoung	199	ancestor, the <b>Q</b> card is used to identify a single check-in or a small
7fcbbb1…	drh	200	range of check-ins which were cherry-picked for inclusion in or
b00e462…	andreask	201	exclusion from the current manifest. The first argument of
a1437b2…	wyoung	202	the <b>Q</b> card is the artifact ID of another manifest (the "target")
f47b705…	jan.nijtmans	203	which has had its changes included or excluded in the current manifest.
f7d7ce3…	drh	204	The target is preceded by "+" or "-" to show inclusion or
7fcbbb1…	drh	205	exclusion, respectively. The optional second argument to the
a1437b2…	wyoung	206	<b>Q</b> card is another manifest artifact ID which is the "baseline"
7fcbbb1…	drh	207	for the cherry-pick. If omitted, the baseline is the primary
7fcbbb1…	drh	208	parent of the target. The
7fcbbb1…	drh	209	changes included or excluded consist of all changes moving from
f47b705…	jan.nijtmans	210	the baseline to the target.
7fcbbb1…	drh	211
a1437b2…	wyoung	212	The <b>Q</b> card was added to the interface specification on 2011-02-26.
a1437b2…	wyoung	213	Older versions of Fossil will reject manifests that contain <b>Q</b> cards.
7fcbbb1…	drh	214
a1437b2…	wyoung	215	A manifest may optionally have a single <b>R</b> card. The <b>R</b> card has
f47b705…	jan.nijtmans	216	a single argument which is the MD5 checksum of all files in
904ee40…	drh	217	the check-in except the manifest itself. The checksum is expressed
9c2116a…	andygoth	218	as 32 characters of lowercase hexadecimal. The checksum is
904ee40…	drh	219	computed as follows: For each file in the check-in (except for
f47b705…	jan.nijtmans	220	the manifest itself) in strict sorted lexicographical order,
f94f7e5…	drh	221	take the pathname of the file relative to the root of the
f94f7e5…	drh	222	repository, append a single space (ASCII 0x20), the
f94f7e5…	drh	223	size of the file in ASCII decimal, a single newline
f94f7e5…	drh	224	character (ASCII 0x0A), and the complete text of the file.
44b02c3…	BMorgat	225	Compute the MD5 checksum of the result.
f94f7e5…	drh	226
a1437b2…	wyoung	227	A manifest might contain one or more <b>T</b> cards used to set
d96c4a4…	drh	228	[./branching.wiki#tags \| tags or properties]
a1437b2…	wyoung	229	on the check-in. The format of the <b>T</b> card is the same as
c664695…	drh	230	described in <i>Control Artifacts</i> section below, except that the
882f7a5…	jan.nijtmans	231	second argument is the single character "<b>*</b>" instead of an
c664695…	drh	232	artifact ID. The <b>*</b> in place of the artifact ID indicates that
c664695…	drh	233	the tag or property applies to the current artifact. It is not
c664695…	drh	234	possible to encode the current artifact ID as part of an artifact,
c664695…	drh	235	since the act of inserting the artifact ID would change the artifact ID,
a1437b2…	wyoung	236	hence a <b>*</b> is used to represent "self". <b>T</b> cards are typically
c664695…	drh	237	added to manifests in order to set the <b>branch</b> property and a
c664695…	drh	238	symbolic name when the check-in is intended to start a new branch.
c664695…	drh	239
a1437b2…	wyoung	240	Each manifest has a single <b>U</b> card. The argument to the <b>U</b> card is
f94f7e5…	drh	241	the login of the user who created the manifest. The login name
f94f7e5…	drh	242	is encoded using the same character escapes as is used for the
a1437b2…	wyoung	243	check-in comment argument to the <b>C</b> card.
7c2577b…	drh	244
a1437b2…	wyoung	245	A manifest must have a single <b>Z</b> card as its last line. The argument
a1437b2…	wyoung	246	to the <b>Z</b> card is a 32-character lowercase hexadecimal MD5 hash
f47b705…	jan.nijtmans	247	of all prior lines of the manifest up to and including the newline
fd9b7bd…	drh	248	character that immediately precedes the "Z", excluding any PGP
a1437b2…	wyoung	249	clear-signing prefix. The <b>Z</b> card is
f94f7e5…	drh	250	a sanity check to prove that the manifest is well-formed and
f94f7e5…	drh	251	consistent.
adc0b3b…	drh	252
7c2577b…	drh	253	A sample manifest from Fossil itself can be seen
16e703b…	drh	254	[/artifact/28987096ac \| here].
adc0b3b…	drh	255
93cee1f…	wyoung	256	<h3 id="cluster">2.2 Clusters</h3>
16e703b…	drh	257
f1b148d…	andybradford	258	A cluster is an artifact that declares the existence of other artifacts.
f47b705…	jan.nijtmans	259	Clusters are used during repository synchronization to help
adc0b3b…	drh	260	reduce network traffic. As such, clusters are an optimization and
adc0b3b…	drh	261	may be removed from a repository without loss or damage to the
adc0b3b…	drh	262	underlying project code.
7c2577b…	drh	263
f94f7e5…	drh	264	Allowed cards in the cluster are as follows:
f94f7e5…	drh	265
d8e2a3b…	wyoung	266	<div class="indent">
e8c4f69…	drh	267	<b>M</b> <i>artifact-id</i><br />
f94f7e5…	drh	268	<b>Z</b> <i>checksum</i>
d8e2a3b…	wyoung	269	</div>
f94f7e5…	drh	270
a1437b2…	wyoung	271	A cluster contains one or more <b>M</b> cards followed by a single <b>Z</b> card.
a1437b2…	wyoung	272	Each <b>M</b> card has a single argument which is the artifact ID of
a1437b2…	wyoung	273	another artifact in the repository. The <b>Z</b> card works exactly like
a1437b2…	wyoung	274	the <b>Z</b> card of a manifest. The argument to the <b>Z</b> card is the
f94f7e5…	drh	275	lower-case hexadecimal representation of the MD5 checksum of all
a1437b2…	wyoung	276	prior cards in the cluster. The <b>Z</b> card is required.
7c2577b…	drh	277
7c2577b…	drh	278	An example cluster from Fossil can be seen
7c2577b…	drh	279	[/artifact/d03dbdd73a2a8 \| here].
7c2577b…	drh	280
26a82dd…	stephan	281	<h3 id="ctrl">2.3 Control (a.k.a. Tag) Artifacts</h3>
7c2577b…	drh	282
f94f7e5…	drh	283	Control artifacts are used to assign properties to other artifacts
26a82dd…	stephan	284	within the repository. Allowed cards in a control artifact are as
26a82dd…	stephan	285	follows:
fd9b7bd…	drh	286
d8e2a3b…	wyoung	287	<div class="indent">
f94f7e5…	drh	288	<b>D</b> <i>time-and-date-stamp</i><br />
4e9522a…	mistachkin	289	<b>T</b> (<b>+</b>\|<b>-</b>\|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br />
7c2577b…	drh	290	<b>U</b> <i>user-name</i><br />
f94f7e5…	drh	291	<b>Z</b> <i>checksum</i><br />
d8e2a3b…	wyoung	292	</div>
26a82dd…	stephan	293
26a82dd…	stephan	294	Control articles are also referred to as Tag artifacts, but tags can
26a82dd…	stephan	295	also be applied via other artifact types, as described in
26a82dd…	stephan	296	[#summary\|the Card Summary table].
a1437b2…	wyoung	297
a1437b2…	wyoung	298	A control artifact must have one <b>D</b> card, one <b>U</b> card, one <b>Z</b> card and
a1437b2…	wyoung	299	one or more <b>T</b> cards. No other cards or other text is
f94f7e5…	drh	300	allowed in a control artifact. Control artifacts might be PGP
7c2577b…	drh	301	clearsigned.
7c2577b…	drh	302
a1437b2…	wyoung	303	The <b>D</b> card and the <b>Z</b> card of a control artifact are the same
7c2577b…	drh	304	as in a manifest.
7c2577b…	drh	305
a1437b2…	wyoung	306	The <b>T</b> card represents a [./branching.wiki#tags \| tag or property]
d96c4a4…	drh	307	that is applied to
a1437b2…	wyoung	308	some other artifact. The <b>T</b> card has two or three values. The
565c217…	stephan	309	second argument is the lowercase artifact ID of the artifact
f94f7e5…	drh	310	to which the tag is to be applied. The
f94f7e5…	drh	311	first value is the tag name. The first character of the tag
80f89e3…	drh	312	is either "+", "-", or "*". The "+" means the tag should be added
f94f7e5…	drh	313	to the artifact. The "-" means the tag should be removed.
f94f7e5…	drh	314	The "*" character means the tag should be added to the artifact
fe38a76…	drh	315	and all direct descendants (but not descendants through a merge) down
f47b705…	jan.nijtmans	316	to but not including the first descendant that contains a
f7d7ce3…	drh	317	more recent "-", "*", or "+" tag with the same name.
f94f7e5…	drh	318	The optional third argument is the value of the tag. A tag
fe38a76…	drh	319	without a value is a Boolean.
f94f7e5…	drh	320
7c2577b…	drh	321	When two or more tags with the same name are applied to the
f94f7e5…	drh	322	same artifact, the tag with the latest (most recent) date is
7c2577b…	drh	323	used.
904ee40…	drh	324
7c2577b…	drh	325	Some tags have special meaning. The "comment" tag when applied
904ee40…	drh	326	to a check-in will override the check-in comment of that check-in
7c2577b…	drh	327	for display purposes. The "user" tag overrides the name of the
7c2577b…	drh	328	check-in user. The "date" tag overrides the check-in date.
7c2577b…	drh	329	The "branch" tag sets the name of the branch that at check-in
7c2577b…	drh	330	belongs to. Symbolic tags begin with the "sym-" prefix.
7c2577b…	drh	331
a1437b2…	wyoung	332	The <b>U</b> card is the name of the user that created the control
a1437b2…	wyoung	333	artifact. The <b>Z</b> card is the usual required artifact checksum.
7c2577b…	drh	334
b1600a2…	stephan	335	An example control artifact can be seen [/info/9d302ccda8 \| here].
7c2577b…	drh	336
7c2577b…	drh	337
93cee1f…	wyoung	338	<h3 id="wikichng">2.4 Wiki Pages</h3>
7c2577b…	drh	339
fd9b7bd…	drh	340	A wiki artifact defines a single version of a
fd9b7bd…	drh	341	single wiki page.
fd9b7bd…	drh	342	Wiki artifacts accept
7c2577b…	drh	343	the following card types:
7c2577b…	drh	344
d8e2a3b…	wyoung	345	<div class="indent">
cad57db…	drh	346	<b>C</b> <i>change-comment</i><br>
f94f7e5…	drh	347	<b>D</b> <i>time-and-date-stamp</i><br />
f94f7e5…	drh	348	<b>L</b> <i>wiki-title</i><br />
4dcea80…	drh	349	<b>N</b> <i>mimetype</i><br />
e8c4f69…	drh	350	<b>P</b> <i>parent-artifact-id</i>+<br />
e8c4f69…	drh	351	<b>U</b> <i>user-name</i><br />
e8c4f69…	drh	352	<b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br />
e8c4f69…	drh	353	<b>Z</b> <i>checksum</i>
d8e2a3b…	wyoung	354	</div>
f47b705…	jan.nijtmans	355
a1437b2…	wyoung	356	The <b>D</b> card is the date and time when the wiki page was edited.
a1437b2…	wyoung	357	The <b>P</b> card specifies the parent wiki pages, if any. The <b>L</b> card
a1437b2…	wyoung	358	gives the name of the wiki page. The optional <b>N</b> card specifies
a1437b2…	wyoung	359	the mimetype of the wiki text. If the <b>N</b> card is omitted, the
f47b705…	jan.nijtmans	360	mimetype is assumed to be text/x-fossil-wiki.
a1437b2…	wyoung	361	The <b>U</b> card specifies the login
a1437b2…	wyoung	362	of the user who made this edit to the wiki page. The <b>Z</b> card is
f7d7ce3…	drh	363	the usual checksum over the entire artifact and is required.
f7d7ce3…	drh	364
a1437b2…	wyoung	365	The <b>W</b> card is used to specify the text of the wiki page. The
a1437b2…	wyoung	366	argument to the <b>W</b> card is an integer which is the number of bytes
e8c4f69…	drh	367	of text in the wiki page. That text follows the newline character
a1437b2…	wyoung	368	that terminates the <b>W</b> card. The wiki text is always followed by one
7c2577b…	drh	369	extra newline.
a1437b2…	wyoung	370
cad57db…	drh	371	The <b>C</b> card on a wiki page is optional. The argument is a comment
285430a…	drh	372	that explains why the changes were made. The ability to have a <b>C</b>
cad57db…	drh	373	card on a wiki page artifact was added on 2019-12-02 at the suggestion
fd1282e…	drh	374	of user George Krivov and is not currently used or generated by the
cad57db…	drh	375	implementation. Older versions of Fossil will reject a wiki-page
cad57db…	drh	376	artifact that includes a <b>C</b> card.
cad57db…	drh	377
7c2577b…	drh	378	An example wiki artifact can be seen
d96c4a4…	drh	379	[/artifact?name=7b2f5fd0e0&txt=1 \| here].
7c2577b…	drh	380
93cee1f…	wyoung	381	<h3 id="tktchng">2.5 Ticket Changes</h3>
7c2577b…	drh	382
7c2577b…	drh	383	A ticket-change artifact represents a change to a trouble ticket.
7c2577b…	drh	384	The following cards are allowed on a ticket change artifact:
7c2577b…	drh	385
d8e2a3b…	wyoung	386	<div class="indent">
e8c4f69…	drh	387	<b>D</b> <i>time-and-date-stamp</i><br />
efb759a…	drh	388	<b>J</b> ?<b>+</b>?<i>name</i> ?<i>value</i>?<br />
e8c4f69…	drh	389	<b>K</b> <i>ticket-id</i><br />
e8c4f69…	drh	390	<b>U</b> <i>user-name</i><br />
e8c4f69…	drh	391	<b>Z</b> <i>checksum</i>
d8e2a3b…	wyoung	392	</div>
7c2577b…	drh	393
a1437b2…	wyoung	394	The <b>D</b> card is the usual date and time stamp and represents the point
a1437b2…	wyoung	395	in time when the change was entered. The <b>U</b> card is the login of the
a1437b2…	wyoung	396	programmer who entered this change. The <b>Z</b> card is the required checksum over
7c2577b…	drh	397	the entire artifact.
7c2577b…	drh	398
81ad6e2…	drh	399	Every ticket has a distinct ticket-id:
81ad6e2…	drh	400	40-character lower-case hexadecimal number.
a1437b2…	wyoung	401	The ticket-id is given in the <b>K</b> card. A ticket exists if it contains one or
e8c4f69…	drh	402	more changes. The first "change" to a ticket is what brings the
7c2577b…	drh	403	ticket into existence.
efb759a…	drh	404
a1437b2…	wyoung	405	<b>J</b> cards specify changes to the "value" of "fields" in the ticket.
a1437b2…	wyoung	406	If the <i>value</i> parameter of the <b>J</b> card is omitted, then the
efb759a…	drh	407	field is set to an empty string.
285430a…	drh	408	Each fossil server has a ticket configuration which specifies the fields it
efb759a…	drh	409	understands. The ticket configuration is part of the local state for
efb759a…	drh	410	the repository and thus can vary from one repository to another.
285430a…	drh	411	Hence a <b>J</b> card might specify a <i>field</i> that does not exist in the
a1437b2…	wyoung	412	local ticket configuration. If a <b>J</b> card specifies a <i>field</i> that
a1437b2…	wyoung	413	is not in the local configuration, then that <b>J</b> card
7c2577b…	drh	414	is simply ignored.
efb759a…	drh	415
a1437b2…	wyoung	416	The first argument of the <b>J</b> card is the field name. The second
e8c4f69…	drh	417	value is the field value. If the field name begins with "+" then
e8c4f69…	drh	418	the value is appended to the prior value. Otherwise, the value
a1437b2…	wyoung	419	on the <b>J</b> card replaces any previous value of the field.
e8c4f69…	drh	420	The field name and value are both encoded using the character
a1437b2…	wyoung	421	escapes defined for the <b>C</b> card of a manifest.
7c2577b…	drh	422
7c2577b…	drh	423	An example ticket-change artifact can be seen
7c2577b…	drh	424	[/artifact/91f1ec6af053 \| here].
7c2577b…	drh	425
93cee1f…	wyoung	426	<h3 id="attachment">2.6 Attachments</h3>
7c2577b…	drh	427
7c2577b…	drh	428	An attachment artifact associates some other artifact that is the
f47b705…	jan.nijtmans	429	attachment (the source artifact) with a ticket or wiki page or
bd50848…	drh	430	technical note to which
7c2577b…	drh	431	the attachment is connected (the target artifact).
7c2577b…	drh	432	The following cards are allowed on an attachment artifact:
7c2577b…	drh	433
d8e2a3b…	wyoung	434	<div class="indent">
d96c4a4…	drh	435	<b>A</b> <i>filename target</i> ?<i>source</i>?<br />
d96c4a4…	drh	436	<b>C</b> <i>comment</i><br />
7c2577b…	drh	437	<b>D</b> <i>time-and-date-stamp</i><br />
4dcea80…	drh	438	<b>N</b> <i>mimetype</i><br />
7c2577b…	drh	439	<b>U</b> <i>user-name</i><br />
7c2577b…	drh	440	<b>Z</b> <i>checksum</i>
d8e2a3b…	wyoung	441	</div>
7c2577b…	drh	442
a1437b2…	wyoung	443	The <b>A</b> card specifies a filename for the attachment in its first argument.
a1437b2…	wyoung	444	The second argument to the <b>A</b> card is the name of the wiki page or
bd50848…	drh	445	ticket or technical note to which the attachment is connected. The
565c217…	stephan	446	third argument is either missing or else it is the lower-case artifact
7c2577b…	drh	447	ID of the attachment itself. A missing third argument means that the
7c2577b…	drh	448	attachment should be deleted.
7c2577b…	drh	449
a1437b2…	wyoung	450	The <b>C</b> card is an optional comment describing what the attachment is about.
a1437b2…	wyoung	451	The <b>C</b> card is optional, but there can only be one.
7c2577b…	drh	452
a1437b2…	wyoung	453	A single <b>D</b> card is required to give the date and time when the attachment
7c2577b…	drh	454	was applied.
7c2577b…	drh	455
a1437b2…	wyoung	456	There may be zero or one <b>N</b> cards. The <b>N</b> card specifies the mimetype of the
a1437b2…	wyoung	457	comment text provided in the <b>C</b> card. If the <b>N</b> card is omitted, the <b>C</b> card
4dcea80…	drh	458	mimetype is taken to be text/plain.
4dcea80…	drh	459
a1437b2…	wyoung	460	A single <b>U</b> card gives the name of the user who added the attachment.
a1437b2…	wyoung	461	If an attachment is added anonymously, then the <b>U</b> card may be omitted.
bd50848…	drh	462
a1437b2…	wyoung	463	The <b>Z</b> card is the usual checksum over the rest of the attachment artifact.
a1437b2…	wyoung	464	The <b>Z</b> card is required.
bd50848…	drh	465
bd50848…	drh	466
93cee1f…	wyoung	467	<h3 id="event">2.7 Technical Notes</h3>
bd50848…	drh	468
bd50848…	drh	469	A technical note or "technote" artifact (formerly known as an "event" artifact)
bd50848…	drh	470	associates a timeline comment and a page of text
bd50848…	drh	471	(similar to a wiki page) with a point in time. Technotes can be used
d96c4a4…	drh	472	to record project milestones, release notes, blog entries, process
d96c4a4…	drh	473	checkpoints, or news articles.
285430a…	drh	474	The following cards are allowed on a technote artifact:
d96c4a4…	drh	475
d8e2a3b…	wyoung	476	<div class="indent">
d96c4a4…	drh	477	<b>C</b> <i>comment</i><br>
d96c4a4…	drh	478	<b>D</b> <i>time-and-date-stamp</i><br />
bd50848…	drh	479	<b>E</b> <i>technote-time</i> <i>technote-id</i><br />
4dcea80…	drh	480	<b>N</b> <i>mimetype</i><br />
d96c4a4…	drh	481	<b>P</b> <i>parent-artifact-id</i>+<br />
4e9522a…	mistachkin	482	<b>T</b> <b>+</b><i>tag-name</i> <b>*</b> ?<i>value</i>?<br />
d96c4a4…	drh	483	<b>U</b> <i>user-name</i><br />
d96c4a4…	drh	484	<b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br />
d96c4a4…	drh	485	<b>Z</b> <i>checksum</i>
d8e2a3b…	wyoung	486	</div>
bd50848…	drh	487
a1437b2…	wyoung	488	The <b>C</b> card contains text that is displayed on the timeline for the
a1437b2…	wyoung	489	technote. The <b>C</b> card is optional, but there can only be one.
bd50848…	drh	490
a1437b2…	wyoung	491	A single <b>D</b> card is required to give the date and time when the
bd50848…	drh	492	technote artifact was created. This is different from the time at which
bd50848…	drh	493	the technote appears on the timeline.
bd50848…	drh	494
a1437b2…	wyoung	495	A single <b>E</b> card gives the time of the technote (the point on the timeline
bd50848…	drh	496	where the technote is displayed) and a unique identifier for the technote.
bd50848…	drh	497	When there are multiple artifacts with the same technote-id, the one with
a1437b2…	wyoung	498	the most recent <b>D</b> card is the only one used. The technote-id must be a
d96c4a4…	drh	499	40-character lower-case hexadecimal string.
d96c4a4…	drh	500
a1437b2…	wyoung	501	The optional <b>N</b> card specifies the mimetype of the text of the technote
a1437b2…	wyoung	502	that is contained in the <b>W</b> card. If the <b>N</b> card is omitted, then the
a1437b2…	wyoung	503	<b>W</b> card text mimetype is assumed to be text/x-fossil-wiki, which is the
4dcea80…	drh	504	Fossil wiki format.
4dcea80…	drh	505
a1437b2…	wyoung	506	The optional <b>P</b> card specifies a prior technote with the same technote-id
a1437b2…	wyoung	507	from which the current technote is an edit. The <b>P</b> card is a hint to the
bd50848…	drh	508	system that it might be space efficient to store one technote as a delta of
bd50848…	drh	509	the other.
d96c4a4…	drh	510
a1437b2…	wyoung	511	A technote might contain one or more <b>T</b> cards used to set
d96c4a4…	drh	512	[./branching.wiki#tags \| tags or properties]
a1437b2…	wyoung	513	on the technote. The format of the <b>T</b> card is the same as
d96c4a4…	drh	514	described in [#ctrl \| Control Artifacts] section above, except that the
882f7a5…	jan.nijtmans	515	second argument is the single character "<b>*</b>" instead of an
d96c4a4…	drh	516	artifact ID and the name is always prefaced by "<b>+</b>".
d96c4a4…	drh	517	The <b>*</b> in place of the artifact ID indicates that
d96c4a4…	drh	518	the tag or property applies to the current artifact. It is not
d96c4a4…	drh	519	possible to encode the current artifact ID as part of an artifact,
d96c4a4…	drh	520	since the act of inserting the artifact ID would change the artifact ID,
d96c4a4…	drh	521	hence a <b>*</b> is used to represent "self". The "<b>+</b>" on the
285430a…	drh	522	name means that tags can only be "add" and they can only be non-propagating
a1437b2…	wyoung	523	tags. In a technote, <b>T</b> cards are normally used to set the background
d96c4a4…	drh	524	display color for timelines.
d96c4a4…	drh	525
285430a…	drh	526	The optional <b>U</b> card gives the name of the user who entered the technote.
99fcc43…	drh	527
a1437b2…	wyoung	528	A single <b>W</b> card provides wiki text for the document associated with the
a1437b2…	wyoung	529	technote. The format of the <b>W</b> card is exactly the same as for a
99fcc43…	drh	530	[#wikichng \| wiki artifact].
99fcc43…	drh	531
a1437b2…	wyoung	532	The <b>Z</b> card is the required checksum over the rest of the artifact.
99fcc43…	drh	533
93cee1f…	wyoung	534	<h3 id="forum">2.8 Forum Posts</h3>
99fcc43…	drh	535
e2751b1…	jan.nijtmans	536	Forum posts are intended as a mechanism for users and developers to
15b2034…	wyoung	537	discuss a project. Forum posts are like messages on a mailing list.
99fcc43…	drh	538
99fcc43…	drh	539	The following cards are allowed on an forum post artifact:
99fcc43…	drh	540
d8e2a3b…	wyoung	541	<div class="indent">
99fcc43…	drh	542	<b>D</b> <i>time-and-date-stamp</i><br />
99fcc43…	drh	543	<b>G</b> <i>thread-root</i><br />
99fcc43…	drh	544	<b>H</b> <i>thread-title</i><br />
99fcc43…	drh	545	<b>I</b> <i>in-reply-to</i><br />
99fcc43…	drh	546	<b>N</b> <i>mimetype</i><br />
99fcc43…	drh	547	<b>P</b> <i>parent-artifact-id</i><br />
99fcc43…	drh	548	<b>U</b> <i>user-name</i><br />
99fcc43…	drh	549	<b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br />
99fcc43…	drh	550	<b>Z</b> <i>checksum</i>
d8e2a3b…	wyoung	551	</div>
99fcc43…	drh	552
a1437b2…	wyoung	553	Every forum post must have either one <b>I</b> card and one <b>G</b> card
e2751b1…	jan.nijtmans	554	or one <b>H</b> card.
99fcc43…	drh	555	Forum posts are organized into topic threads. The initial
a1437b2…	wyoung	556	post for a thread (the root post) has an <b>H</b> card giving the title or
a1437b2…	wyoung	557	subject for that thread. The argument to the <b>H</b> card is a string
a1437b2…	wyoung	558	in the same format as a comment string in a <b>C</b> card.
a1437b2…	wyoung	559	All follow-up posts have an <b>I</b> card that
99fcc43…	drh	560	indicates which prior post in the same thread the current forum
a1437b2…	wyoung	561	post is replying to, and a <b>G</b> card specifying the root post for
273dd80…	andygoth	562	the entire thread. The argument to <b>G</b> and <b>I</b> cards is the
99fcc43…	drh	563	artifact hash for the prior forum post to which the card refers.
99fcc43…	drh	564
99fcc43…	drh	565	In theory, it is sufficient for follow-up posts to have only an
a1437b2…	wyoung	566	<b>I</b> card, since the <b>G</b> card value could be computed by following a
a1437b2…	wyoung	567	chain of <b>I</b> cards. However, the <b>G</b> card is required in order to
99fcc43…	drh	568	associate the artifact with a forum thread in the case where an
a1437b2…	wyoung	569	intermediate artifact in the <b>I</b> card chain is shunned or otherwise
99fcc43…	drh	570	becomes unreadable.
99fcc43…	drh	571
a1437b2…	wyoung	572	A single <b>D</b> card is required to give the date and time when the
99fcc43…	drh	573	forum post was created.
99fcc43…	drh	574
a1437b2…	wyoung	575	The optional <b>N</b> card specifies the mimetype of the text of the technote
a1437b2…	wyoung	576	that is contained in the <b>W</b> card. If the <b>N</b> card is omitted, then the
a1437b2…	wyoung	577	<b>W</b> card text mimetype is assumed to be text/x-fossil-wiki, which is the
99fcc43…	drh	578	Fossil wiki format.
99fcc43…	drh	579
a1437b2…	wyoung	580	The optional <b>P</b> card specifies a prior forum post for which this
99fcc43…	drh	581	forum post is an edit. For display purposes, only the child post
99fcc43…	drh	582	is shown, though the historical post is retained as a record.
a1437b2…	wyoung	583	If <b>P</b> cards are used and there exist multiple versions of the same
a1437b2…	wyoung	584	forum post, then <b>I</b> cards for other artifacts refer to whichever
99fcc43…	drh	585	version of the post was current at the time the reply was made,
a1437b2…	wyoung	586	but <b>G</b> cards refer to the initial, unedited root post for the thread.
a1437b2…	wyoung	587	Thus, following the chain of <b>I</b> cards back to the root of the thread
a1437b2…	wyoung	588	may land on a different post than the one given in the <b>G</b> card.
a1437b2…	wyoung	589	However, following the chain of <b>I</b> cards back to the thread root,
a1437b2…	wyoung	590	then following <b>P</b> cards back to the initial version of the thread
a1437b2…	wyoung	591	root must give the same artifact as is provided by the <b>G</b> card,
a1437b2…	wyoung	592	otherwise the artifact containing the <b>G</b> card is considered invalid
99fcc43…	drh	593	and should be ignored.
99fcc43…	drh	594
a1437b2…	wyoung	595	In general, <b>P</b> cards may contain multiple arguments, indicating a
99fcc43…	drh	596	merge. But since forum posts cannot be merged, the
a1437b2…	wyoung	597	<b>P</b> card of a forum post may only contain a single argument.
99fcc43…	drh	598
a1437b2…	wyoung	599	The <b>U</b> card gives name of the user who entered the forum post.
d96c4a4…	drh	600
a1437b2…	wyoung	601	A single <b>W</b> card provides wiki text for the forum post.
a1437b2…	wyoung	602	The format of the <b>W</b> card is exactly the same as for a
d96c4a4…	drh	603	[#wikichng \| wiki artifact].
d96c4a4…	drh	604
a1437b2…	wyoung	605	The <b>Z</b> card is the required checksum over the rest of the artifact.
80bf17c…	stephan	606
559047a…	stephan	607
93cee1f…	wyoung	608	<h2 id="summary">3.0 Card Summary</h2>
559047a…	stephan	609
80bf17c…	stephan	610	The following table summarizes the various kinds of cards that appear
559047a…	stephan	611	on Fossil artifacts. A blank entry means that combination of card and
559047a…	stephan	612	artifact is not legal. A number or range of numbers indicates the number
559047a…	stephan	613	of times a card may (or must) appear in the corresponding artifact type.
559047a…	stephan	614	e.g. a value of 1 indicates a required unique card and 1+ indicates that one
559047a…	stephan	615	or more such cards are required.
559047a…	stephan	616
8a1ba49…	wyoung	617	<table>
559047a…	stephan	618	<tr>
8a1ba49…	wyoung	619	<th>⇩ Card Format / Used By ⇨</th>
7c2577b…	drh	620	<th>Manifest</th>
7c2577b…	drh	621	<th>Cluster</th>
7c2577b…	drh	622	<th>Control</th>
7c2577b…	drh	623	<th>Wiki</th>
7c2577b…	drh	624	<th>Ticket</th>
7c2577b…	drh	625	<th>Attachment</th>
bd50848…	drh	626	<th>Technote</th>
99fcc43…	drh	627	<th>Forum</th>
d13054c…	drh	628	</tr>
d13054c…	drh	629	<tr>
4e9522a…	mistachkin	630	<td><b>A</b> <i>filename</i> <i>target</i> ?<i>source</i>?</td>
d13054c…	drh	631	<td> </td>
d13054c…	drh	632	<td> </td>
d13054c…	drh	633	<td> </td>
d13054c…	drh	634	<td> </td>
d13054c…	drh	635	<td> </td>
559047a…	stephan	636	<td align=center><b>1</b></td>
4e9522a…	mistachkin	637	<td> </td>
99fcc43…	drh	638	<td> </td>
d96c4a4…	drh	639	</tr>
d96c4a4…	drh	640	<tr>
d13054c…	drh	641	<td><b>B</b> <i>baseline</i></td>
99fcc43…	drh	642	<td align=center><b>0-1</b></td>
99fcc43…	drh	643	<td> </td>
d96c4a4…	drh	644	<td> </td>
d96c4a4…	drh	645	<td> </td>
d96c4a4…	drh	646	<td> </td>
d96c4a4…	drh	647	<td> </td>
d13054c…	drh	648	<td> </td>
d96c4a4…	drh	649	<td> </td>
d96c4a4…	drh	650	</tr>
d96c4a4…	drh	651	<tr>
d96c4a4…	drh	652	<td><b>C</b> <i>comment-text</i></td>
559047a…	stephan	653	<td align=center><b>1</b></td>
d96c4a4…	drh	654	<td> </td>
d96c4a4…	drh	655	<td> </td>
cad57db…	drh	656	<td align=center><b>0-1</b></td>
d96c4a4…	drh	657	<td> </td>
6a03e93…	jan.nijtmans	658	<td align=center><b>0-1</b></td>
559047a…	stephan	659	<td align=center><b>0-1</b></td>
99fcc43…	drh	660	<td> </td>
7c2577b…	drh	661	</tr>
7c2577b…	drh	662	<tr>
7c2577b…	drh	663	<td><b>D</b> <i>date-time-stamp</i></td>
559047a…	stephan	664	<td align=center><b>1</b></td>
53e0042…	jan.nijtmans	665	<td> </td>
99fcc43…	drh	666	<td align=center><b>1</b></td>
4e9522a…	mistachkin	667	<td align=center><b>1</b></td>
4e9522a…	mistachkin	668	<td align=center><b>1</b></td>
4e9522a…	mistachkin	669	<td align=center><b>1</b></td>
4e9522a…	mistachkin	670	<td align=center><b>1</b></td>
bd50848…	drh	671	<td align=center><b>1</b></td>
4e9522a…	mistachkin	672	</tr>
4e9522a…	mistachkin	673	<tr>
bd50848…	drh	674	<td><b>E</b> <i>technote-time technote-id</i></td>
53e0042…	jan.nijtmans	675	<td> </td>
53e0042…	jan.nijtmans	676	<td> </td>
53e0042…	jan.nijtmans	677	<td> </td>
53e0042…	jan.nijtmans	678	<td> </td>
53e0042…	jan.nijtmans	679	<td> </td>
53e0042…	jan.nijtmans	680	<td> </td>
4e9522a…	mistachkin	681	<td align=center><b>1</b></td>
99fcc43…	drh	682	<td> </td>
4e9522a…	mistachkin	683	</tr>
4e9522a…	mistachkin	684	<tr>
4e9522a…	mistachkin	685	<td><b>F</b> <i>filename</i> ?<i>uuid</i>? ?<i>permissions</i>? ?<i>oldname</i>?</td>
559047a…	stephan	686	<td align=center><b>0+</b></td>
53e0042…	jan.nijtmans	687	<td> </td>
53e0042…	jan.nijtmans	688	<td> </td>
53e0042…	jan.nijtmans	689	<td> </td>
53e0042…	jan.nijtmans	690	<td> </td>
53e0042…	jan.nijtmans	691	<td> </td>
53e0042…	jan.nijtmans	692	<td> </td>
99fcc43…	drh	693	<td> </td>
99fcc43…	drh	694	</tr>
99fcc43…	drh	695	<tr>
99fcc43…	drh	696	<td><b>G</b> <i>thread-root</i></td>
99fcc43…	drh	697	<td> </td>
99fcc43…	drh	698	<td> </td>
99fcc43…	drh	699	<td> </td>
99fcc43…	drh	700	<td> </td>
99fcc43…	drh	701	<td> </td>
99fcc43…	drh	702	<td> </td>
99fcc43…	drh	703	<td> </td>
99fcc43…	drh	704	<td align=center><b>0-1</b></td>
99fcc43…	drh	705	</tr>
99fcc43…	drh	706	<tr>
99fcc43…	drh	707	<td><b>H</b> <i>thread-title</i></td>
99fcc43…	drh	708	<td> </td>
99fcc43…	drh	709	<td> </td>
99fcc43…	drh	710	<td> </td>
99fcc43…	drh	711	<td> </td>
99fcc43…	drh	712	<td> </td>
99fcc43…	drh	713	<td> </td>
99fcc43…	drh	714	<td> </td>
a3bfeb8…	stephan	715	<td align=center><b>0-1</b><sup><nowiki>[4]</nowiki></sup></td>
99fcc43…	drh	716	</tr>
99fcc43…	drh	717	<tr>
99fcc43…	drh	718	<td><b>I</b> <i>in-reply-to</i></td>
99fcc43…	drh	719	<td> </td>
99fcc43…	drh	720	<td> </td>
99fcc43…	drh	721	<td> </td>
99fcc43…	drh	722	<td> </td>
99fcc43…	drh	723	<td> </td>
99fcc43…	drh	724	<td> </td>
99fcc43…	drh	725	<td> </td>
a3bfeb8…	stephan	726	<td align=center><b>0-1</b><sup><nowiki>[4]</nowiki></sup></td>
559047a…	stephan	727	</tr>
559047a…	stephan	728	<tr>
4e9522a…	mistachkin	729	<td><b>J</b> <i>name</i> ?<i>value</i>?</td>
53e0042…	jan.nijtmans	730	<td> </td>
53e0042…	jan.nijtmans	731	<td> </td>
53e0042…	jan.nijtmans	732	<td> </td>
53e0042…	jan.nijtmans	733	<td> </td>
559047a…	stephan	734	<td align=center><b>1+</b></td>
99fcc43…	drh	735	<td> </td>
53e0042…	jan.nijtmans	736	<td> </td>
53e0042…	jan.nijtmans	737	<td> </td>
7c2577b…	drh	738	</tr>
7c2577b…	drh	739	<tr>
7c2577b…	drh	740	<td><b>K</b> <i>ticket-uuid</i></td>
53e0042…	jan.nijtmans	741	<td> </td>
53e0042…	jan.nijtmans	742	<td> </td>
53e0042…	jan.nijtmans	743	<td> </td>
53e0042…	jan.nijtmans	744	<td> </td>
559047a…	stephan	745	<td align=center><b>1</b></td>
53e0042…	jan.nijtmans	746	<td> </td>
53e0042…	jan.nijtmans	747	<td> </td>
99fcc43…	drh	748	<td> </td>
7c2577b…	drh	749	</tr>
7c2577b…	drh	750	<tr>
7c2577b…	drh	751	<td><b>L</b> <i>wiki-title</i></td>
53e0042…	jan.nijtmans	752	<td> </td>
53e0042…	jan.nijtmans	753	<td> </td>
53e0042…	jan.nijtmans	754	<td> </td>
559047a…	stephan	755	<td align=center><b>1</b></td>
53e0042…	jan.nijtmans	756	<td> </td>
53e0042…	jan.nijtmans	757	<td> </td>
53e0042…	jan.nijtmans	758	<td> </td>
99fcc43…	drh	759	<td> </td>
7c2577b…	drh	760	</tr>
7c2577b…	drh	761	<tr>
7c2577b…	drh	762	<td><b>M</b> <i>uuid</i></td>
53e0042…	jan.nijtmans	763	<td> </td>
559047a…	stephan	764	<td align=center><b>1+</b></td>
99fcc43…	drh	765	<td> </td>
53e0042…	jan.nijtmans	766	<td> </td>
53e0042…	jan.nijtmans	767	<td> </td>
53e0042…	jan.nijtmans	768	<td> </td>
53e0042…	jan.nijtmans	769	<td> </td>
53e0042…	jan.nijtmans	770	<td> </td>
4dcea80…	drh	771	</tr>
4dcea80…	drh	772	<tr>
4dcea80…	drh	773	<td><b>N</b> <i>mimetype</i></td>
559047a…	stephan	774	<td align=center><b>0-1</b></td>
53e0042…	jan.nijtmans	775	<td> </td>
53e0042…	jan.nijtmans	776	<td> </td>
559047a…	stephan	777	<td align=center><b>0-1</b></td>
53e0042…	jan.nijtmans	778	<td> </td>
53e0042…	jan.nijtmans	779	<td align=center><b>0-1</b></td>
559047a…	stephan	780	<td align=center><b>0-1</b></td>
99fcc43…	drh	781	<td align=center><b>0-1</b></td>
7c2577b…	drh	782	</tr>
7c2577b…	drh	783	<tr>
7c2577b…	drh	784	<td><b>P</b> <i>uuid ...</i></td>
559047a…	stephan	785	<td align=center><b>0-1</b></td>
53e0042…	jan.nijtmans	786	<td> </td>
53e0042…	jan.nijtmans	787	<td> </td>
53e0042…	jan.nijtmans	788	<td align=center><b>0-1</b></td>
53e0042…	jan.nijtmans	789	<td> </td>
53e0042…	jan.nijtmans	790	<td> </td>
53e0042…	jan.nijtmans	791	<td align=center><b>0-1</b></td>
a3bfeb8…	stephan	792	<td align=center><b>0-1</b><sup><nowiki>[5]</nowiki></sup></td>
53e0042…	jan.nijtmans	793	</tr>
53e0042…	jan.nijtmans	794	<tr>
53e0042…	jan.nijtmans	795	<td><b>Q</b> (<b>+</b>\|<b>-</b>)<i>uuid</i> ?<i>uuid</i>?</td>
53e0042…	jan.nijtmans	796	<td align=center><b>0+</b></td>
99fcc43…	drh	797	<td> </td>
53e0042…	jan.nijtmans	798	<td> </td>
53e0042…	jan.nijtmans	799	<td> </td>
53e0042…	jan.nijtmans	800	<td> </td>
53e0042…	jan.nijtmans	801	<td> </td>
53e0042…	jan.nijtmans	802	<td> </td>
53e0042…	jan.nijtmans	803	<td> </td>
53e0042…	jan.nijtmans	804	</tr>
53e0042…	jan.nijtmans	805	<tr>
53e0042…	jan.nijtmans	806	<td><b>R</b> <i>md5sum</i></td>
53e0042…	jan.nijtmans	807	<td align=center><b>0-1</b></td>
53e0042…	jan.nijtmans	808	<td> </td>
53e0042…	jan.nijtmans	809	<td> </td>
53e0042…	jan.nijtmans	810	<td> </td>
53e0042…	jan.nijtmans	811	<td> </td>
53e0042…	jan.nijtmans	812	<td> </td>
53e0042…	jan.nijtmans	813	<td> </td>
99fcc43…	drh	814	<td> </td>
53e0042…	jan.nijtmans	815	<tr>
a3bfeb8…	stephan	816	<td><b>T</b> (<b>+</b>\|<b>*</b>\|<b>-</b>)<i>tagname</i> <i>uuid</i> ?<i>value</i>?<sup><nowiki>[1]</nowiki></sup></td>
53e0042…	jan.nijtmans	817	<td align=center><b>0+</b></td>
53e0042…	jan.nijtmans	818	<td> </td>
a3bfeb8…	stephan	819	<td align=center><b>1+</b><sup><nowiki>[2]</nowiki></sup></td>
53e0042…	jan.nijtmans	820	<td> </td>
53e0042…	jan.nijtmans	821	<td> </td>
53e0042…	jan.nijtmans	822	<td> </td>
a3bfeb8…	stephan	823	<td align=center><b>0+</b><sup><nowiki>[3]</nowiki></sup></td>
99fcc43…	drh	824	<td> </td>
53e0042…	jan.nijtmans	825	</tr>
53e0042…	jan.nijtmans	826	<tr>
53e0042…	jan.nijtmans	827	<td><b>U</b> <i>username</i></td>
53e0042…	jan.nijtmans	828	<td align=center><b>1</b></td>
53e0042…	jan.nijtmans	829	<td> </td>
53e0042…	jan.nijtmans	830	<td align=center><b>1</b></td>
53e0042…	jan.nijtmans	831	<td align=center><b>1</b></td>
53e0042…	jan.nijtmans	832	<td align=center><b>1</b></td>
53e0042…	jan.nijtmans	833	<td align=center><b>0-1</b></td>
53e0042…	jan.nijtmans	834	<td align=center><b>0-1</b></td>
99fcc43…	drh	835	<td align=center><b>1</b></td>
53e0042…	jan.nijtmans	836	</tr>
53e0042…	jan.nijtmans	837	<tr>
5e9e767…	drh	838	<td><b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b></td>
53e0042…	jan.nijtmans	839	<td> </td>
53e0042…	jan.nijtmans	840	<td> </td>
53e0042…	jan.nijtmans	841	<td> </td>
53e0042…	jan.nijtmans	842	<td align=center><b>1</b></td>
53e0042…	jan.nijtmans	843	<td> </td>
53e0042…	jan.nijtmans	844	<td> </td>
99fcc43…	drh	845	<td align=center><b>1</b></td>
559047a…	stephan	846	<td align=center><b>1</b></td>
7c2577b…	drh	847	</tr>
7c2577b…	drh	848	<tr>
7c2577b…	drh	849	<td><b>Z</b> <i>md5sum</i></td>
559047a…	stephan	850	<td align=center><b>1</b></td>
559047a…	stephan	851	<td align=center><b>1</b></td>
559047a…	stephan	852	<td align=center><b>1</b></td>
559047a…	stephan	853	<td align=center><b>1</b></td>
559047a…	stephan	854	<td align=center><b>1</b></td>
559047a…	stephan	855	<td align=center><b>1</b></td>
559047a…	stephan	856	<td align=center><b>1</b></td>
99fcc43…	drh	857	<td align=center><b>1</b></td>
7c2577b…	drh	858	</tr>
7c2577b…	drh	859	</table>
1b5513c…	stephan	860
a3bfeb8…	stephan	861	Footnotes:
a3bfeb8…	stephan	862
a3bfeb8…	stephan	863	1) T-card names may not be made up of only hexadecimal characters, as
a3bfeb8…	stephan	864	they would be indistinguishable from a hash prefix.
a3bfeb8…	stephan	865
a3bfeb8…	stephan	866	2) Tags in [#ctrl \| Control Artifacts] may not be
7ebe73f…	stephan	867	self-referential. i.e. their target hash may not be <tt>*</tt>.
a3bfeb8…	stephan	868
b1600a2…	stephan	869	3) Tags in [#event \| Technotes] must be self-referential. i.e. their
b1600a2…	stephan	870	target hash must be <tt>*</tt>. Similarly, technote tags may only
b1600a2…	stephan	871	be non-propagating "add" tags. i.e. their name prefix must be
b1600a2…	stephan	872	<tt>+</tt>.
a3bfeb8…	stephan	873
a3bfeb8…	stephan	874	4) [#forum \| Forum Posts] must have either one H-card or one
a3bfeb8…	stephan	875	I-card, not both.
a3bfeb8…	stephan	876
7ebe73f…	stephan	877	5) [#forum \| Forum Post] P-cards may have only a single parent
a3bfeb8…	stephan	878	hash. i.e. they may not have merge parents.
1b5513c…	stephan	879
93cee1f…	wyoung	880	<h2 id="addenda">4.0 Addenda</h2>
1b5513c…	stephan	881
1b5513c…	stephan	882	This section contains additional information which may be useful when
1b5513c…	stephan	883	implementing algorithms described above.
1b5513c…	stephan	884
93cee1f…	wyoung	885	<h3 id="outofordercards">4.1 Relaxed Card Ordering Due To An Historical Bug</h3>
023fdde…	drh	886
023fdde…	drh	887	All cards of a structural artifact should be in lexicographical order.
023fdde…	drh	888	The Fossil implementation verifies this and rejects any structural
023fdde…	drh	889	artifact which has out-of-order cards. Futhermore, when Fossil is
023fdde…	drh	890	generating new structural artifacts, it runs the generated artifact
023fdde…	drh	891	through the parser to confirm that all cards really are in the correct
023fdde…	drh	892	order before committing the transaction. In this way, Fossil prevents
023fdde…	drh	893	bugs in the code from accidentally inserting misformatted artifacts.
023fdde…	drh	894	The test parse of newly created artifacts is part of the
023fdde…	drh	895	[./selfcheck.wiki\|self-check strategy] of Fossil. It takes a
023fdde…	drh	896	few more CPU cycles to double check each artifact before inserting it.
023fdde…	drh	897	The developers consider those CPU cycles well-spent.
023fdde…	drh	898
023fdde…	drh	899	However, the card-order safety check was accidentally disabled due to
023fdde…	drh	900	[15d04de574383d61\|a bug].
023fdde…	drh	901	And while that bug was lurking undetected in the code,
023fdde…	drh	902	[5e67a7f4041a36ad\|another bug] caused the N cards of Technical Notes
023fdde…	drh	903	to occur after the P card rather than before.
023fdde…	drh	904	Thus for a span of several years, Technical Note artifacts were being
023fdde…	drh	905	inserted into Fossil repositories that had their N and P cards in the
023fdde…	drh	906	wrong order.
023fdde…	drh	907
023fdde…	drh	908	Both bugs have now been fixed. However, to prevent historical
023fdde…	drh	909	Technical Note artifacts that were inserted by users in good faith
023fdde…	drh	910	from being rejected by newer Fossil builds, the card ordering
023fdde…	drh	911	requirement is relaxed slightly. The actual implementation is this:
023fdde…	drh	912
8a1ba49…	wyoung	913	<p class=blockquote>
023fdde…	drh	914	"All cards must be in strict lexicographic order, except that the
023fdde…	drh	915	N and P cards of a Technical Note artifact are allowed to be
023fdde…	drh	916	interchanged."
8a1ba49…	wyoung	917	</p>
023fdde…	drh	918
023fdde…	drh	919	Future versions of Fossil might strengthen this slightly to only allow
023fdde…	drh	920	the out of order N and P cards for Technical Notes entered before
023fdde…	drh	921	a certain date.
023fdde…	drh	922
023fdde…	drh	923	<h3>4.2 R-Card Hash Calculation</h3>
1b5513c…	stephan	924
df60acb…	stephan	925	Given a manifest file named <tt>MF</tt>, the following Bash shell code
a1437b2…	wyoung	926	demonstrates how to compute the value of the <b>R</b> card in that manifest.
1b5513c…	stephan	927	This example uses manifest [28987096ac]. Lines starting with <tt>#</tt> are
04764ae…	stephan	928	shell input and other lines are output. This demonstration assumes that the
04764ae…	stephan	929	file versions represented by the input manifest are checked out
04764ae…	stephan	930	under the current directory.
1b5513c…	stephan	931
1b5513c…	stephan	932	<nowiki><pre>
1b5513c…	stephan	933	# head MF
1b5513c…	stephan	934	-----BEGIN PGP SIGNED MESSAGE-----
1b5513c…	stephan	935	Hash: SHA1
1b5513c…	stephan	936
1b5513c…	stephan	937	C Make\sthe\s"clearsign"\sPGP\ssigning\sdefault\sto\soff.
1b5513c…	stephan	938	D 2010-02-23T15:33:14
1b5513c…	stephan	939	F BUILD.txt 4f7988767e4e48b29f7eddd0e2cdea4555b9161c
1b5513c…	stephan	940	F COPYRIGHT-GPL2.txt 06877624ea5c77efe3b7e39b0f909eda6e25a4ec
1b5513c…	stephan	941	...
1b5513c…	stephan	942
1b5513c…	stephan	943	# grep '^R ' MF
1b5513c…	stephan	944	R c0788982781981c96a0d81465fec7192
1b5513c…	stephan	945
1b5513c…	stephan	946	# for i in $(awk '/^F /{print $2}' MF); do \
1b5513c…	stephan	947	echo $i $(stat -c '%s' $i); \
1b5513c…	stephan	948	cat $i; \
1b5513c…	stephan	949	done \| md5sum
1b5513c…	stephan	950	c0788982781981c96a0d81465fec7192 -
df60acb…	stephan	951	</pre></nowiki>
76d901d…	stephan	952
9d50b77…	stephan	953	Minor caveats: the above demonstration will work only when none of the
76d901d…	stephan	954	filenames in the manifest are "fossilized" (encoded) because they contain
76d901d…	stephan	955	spaces. In that case the shell-generated hash would differ because the
76d901d…	stephan	956	<tt>stat</tt> calls will fail to find such files (which are output in encoded
9d50b77…	stephan	957	form here). That approach also won't work for delta manifests. Calculating
a1437b2…	wyoung	958	the <b>R</b> card for delta manifests requires traversing both the delta and its baseline in
53e0042…	jan.nijtmans	959	lexical order of the files, preferring the delta's copy if both contain
9d50b77…	stephan	960	a given file.

Fossil SCM

Keyboard Shortcuts