Fossil SCM
Bolded the card letters in fileformat.wiki and normalized 'X card' vs 'X-card' vs '"X" card' to make it easier to search for a given card type in the document.
Commit
a1437b2447512c2ad6495b463e39ee3223575ab56ad690a6e3d433d550af51cb
Parent
04a2142883e4787…
1 file changed
+131
-131
+131
-131
| --- www/fileformat.wiki | ||
| +++ www/fileformat.wiki | ||
| @@ -125,99 +125,99 @@ | ||
| 125 | 125 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <b>*</b> ?<i>value</i>?<br> |
| 126 | 126 | <b>U</b> <i>user-login</i><br> |
| 127 | 127 | <b>Z</b> <i>manifest-checksum</i> |
| 128 | 128 | </blockquote> |
| 129 | 129 | |
| 130 | -A manifest may optionally have a single B-card. The B-card specifies | |
| 130 | +A manifest may optionally have a single <b>B</b> card. The <b>B</b> card specifies | |
| 131 | 131 | another manifest that serves as the "baseline" for this manifest. A |
| 132 | -manifest that has a B-card is called a delta-manifest and a manifest | |
| 133 | -that omits the B-card is a baseline-manifest. The other manifest | |
| 134 | -identified by the argument of the B-card must be a baseline-manifest. | |
| 132 | +manifest that has a <b>B</b> card is called a delta-manifest and a manifest | |
| 133 | +that omits the <b>B</b> card is a baseline-manifest. The other manifest | |
| 134 | +identified by the argument of the <b>B</b> card must be a baseline-manifest. | |
| 135 | 135 | A baseline-manifest records the complete contents of a check-in. |
| 136 | 136 | A delta-manifest records only changes from its baseline. |
| 137 | 137 | |
| 138 | -A manifest must have exactly one C-card. The sole argument to | |
| 139 | -the C-card is a check-in comment that describes the check-in that | |
| 138 | +A manifest must have exactly one <b>C</b> card. The sole argument to | |
| 139 | +the <b>C</b> card is a check-in comment that describes the check-in that | |
| 140 | 140 | the manifest defines. The check-in comment is text. The following |
| 141 | 141 | escape sequences are applied to the text: |
| 142 | 142 | A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A |
| 143 | 143 | newline (ASCII 0x0a) is "\n" (ASCII 0x5C, x6E). A backslash |
| 144 | 144 | (ASCII 0x5C) is represented as two backslashes "\\". Apart from |
| 145 | 145 | space and newline, no other whitespace characters are allowed in |
| 146 | 146 | the check-in comment. Nor are any unprintable characters allowed |
| 147 | 147 | in the comment. |
| 148 | 148 | |
| 149 | -A manifest must have exactly one D-card. The sole argument to | |
| 150 | -the D-card is a date-time stamp in the ISO8601 format. The | |
| 149 | +A manifest must have exactly one <b>D</b> card. The sole argument to | |
| 150 | +the <b>D</b> card is a date-time stamp in the ISO8601 format. The | |
| 151 | 151 | date and time should be in coordinated universal time (UTC). |
| 152 | 152 | The format one of: |
| 153 | 153 | |
| 154 | 154 | <blockquote> |
| 155 | 155 | <i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i><br> |
| 156 | 156 | <i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i><b>.</b><i>SSS</i> |
| 157 | 157 | </blockquote> |
| 158 | 158 | |
| 159 | -A manifest has zero or more F-cards. Each F-card identifies a file | |
| 159 | +A manifest has zero or more <b>F</b> cards. Each <b>F</b> card identifies a file | |
| 160 | 160 | that is part of the check-in. There are one, two, three, or four |
| 161 | 161 | arguments. The first argument is the pathname of the file in the |
| 162 | 162 | check-in relative to the root of the project file hierarchy. No ".." |
| 163 | 163 | or "." directories are allowed within the filename. Space characters |
| 164 | -are escaped as in C-card comment text. Backslash characters and | |
| 164 | +are escaped as in <b>C</b> card comment text. Backslash characters and | |
| 165 | 165 | newlines are not allowed within filenames. The directory separator |
| 166 | 166 | character is a forward slash (ASCII 0x2F). The second argument to the |
| 167 | -F-card is the lower-case hexadecimal artifact hash of | |
| 167 | +<b>F</b> card is the lower-case hexadecimal artifact hash of | |
| 168 | 168 | the content artifact. The second argument is required for baseline |
| 169 | 169 | manifests but is optional for delta manifests. When the second |
| 170 | -argument to the F-card is omitted, it means that the file has been | |
| 170 | +argument to the <b>F</b> card is omitted, it means that the file has been | |
| 171 | 171 | deleted relative to the baseline (files removed in baseline manifests |
| 172 | -versions are <em>not</em> added as F-cards). The optional 3rd argument | |
| 172 | +versions are <em>not</em> added as <b>F</b> cards). The optional 3rd argument | |
| 173 | 173 | defines any special access permissions associated with the file. This |
| 174 | 174 | can be defined as "x" to mean that the file is executable or "l" |
| 175 | 175 | (small letter ell) to mean a symlink. All files are always readable |
| 176 | 176 | and writable. This can be expressed by "w" permission if desired but |
| 177 | 177 | is optional. The file format might be extended with new permission |
| 178 | 178 | letters in the future. The optional 4th argument is the name of the |
| 179 | 179 | same file as it existed in the parent check-in. If the name of the |
| 180 | 180 | file is unchanged from its parent, then the 4th argument is omitted. |
| 181 | 181 | |
| 182 | -A manifest has zero or one N-cards. The N-card specifies the mimetype for the | |
| 183 | -text in the comment of the C-card. If the N-card is omitted, a default mimetype | |
| 182 | +A manifest has zero or one <b>N</b> cards. The <b>N</b> card specifies the mimetype for the | |
| 183 | +text in the comment of the <b>C</b> card. If the <b>N</b> card is omitted, a default mimetype | |
| 184 | 184 | is used. |
| 185 | 185 | |
| 186 | -A manifest has zero or one P-cards. Most manifests have one P-card. | |
| 187 | -The P-card has a varying number of arguments that | |
| 186 | +A manifest has zero or one <b>P</b> cards. Most manifests have one <b>P</b> card. | |
| 187 | +The <b>P</b> card has a varying number of arguments that | |
| 188 | 188 | define other manifests from which the current manifest |
| 189 | 189 | is derived. Each argument is a lowercase |
| 190 | 190 | hexadecimal artifact hash of a predecessor manifest. All arguments |
| 191 | -to the P-card must be unique within that card. | |
| 191 | +to the <b>P</b> card must be unique within that card. | |
| 192 | 192 | The first argument is the artifact hash of the direct ancestor of the manifest. |
| 193 | 193 | Other arguments define manifests with which the first was |
| 194 | 194 | merged to yield the current manifest. Most manifests have |
| 195 | -a P-card with a single argument. The first manifest in the | |
| 196 | -project has no ancestors and thus has no P-card or (depending | |
| 197 | -on the Fossil version) an empty P-card (no arguments). | |
| 195 | +a <b>P</b> card with a single argument. The first manifest in the | |
| 196 | +project has no ancestors and thus has no <b>P</b> card or (depending | |
| 197 | +on the Fossil version) an empty <b>P</b> card (no arguments). | |
| 198 | 198 | |
| 199 | -A manifest has zero or more Q-cards. A Q-card is similar to a P-card | |
| 199 | +A manifest has zero or more <b>Q</b> cards. A <b>Q</b> card is similar to a <b>P</b> card | |
| 200 | 200 | in that it defines a predecessor to the current check-in. But |
| 201 | -whereas a P-card defines the immediate ancestor or a merge | |
| 202 | -ancestor, the Q-card is used to identify a single check-in or a small | |
| 201 | +whereas a <b>P</b> card defines the immediate ancestor or a merge | |
| 202 | +ancestor, the <b>Q</b> card is used to identify a single check-in or a small | |
| 203 | 203 | range of check-ins which were cherry-picked for inclusion in or |
| 204 | 204 | exclusion from the current manifest. The first argument of |
| 205 | -the Q-card is the artifact ID of another manifest (the "target") | |
| 205 | +the <b>Q</b> card is the artifact ID of another manifest (the "target") | |
| 206 | 206 | which has had its changes included or excluded in the current manifest. |
| 207 | 207 | The target is preceded by "+" or "-" to show inclusion or |
| 208 | 208 | exclusion, respectively. The optional second argument to the |
| 209 | -Q-card is another manifest artifact ID which is the "baseline" | |
| 209 | +<b>Q</b> card is another manifest artifact ID which is the "baseline" | |
| 210 | 210 | for the cherry-pick. If omitted, the baseline is the primary |
| 211 | 211 | parent of the target. The |
| 212 | 212 | changes included or excluded consist of all changes moving from |
| 213 | 213 | the baseline to the target. |
| 214 | 214 | |
| 215 | -The Q-card was added to the interface specification on 2011-02-26. | |
| 216 | -Older versions of Fossil will reject manifests that contain Q-cards. | |
| 215 | +The <b>Q</b> card was added to the interface specification on 2011-02-26. | |
| 216 | +Older versions of Fossil will reject manifests that contain <b>Q</b> cards. | |
| 217 | 217 | |
| 218 | -A manifest may optionally have a single R-card. The R-card has | |
| 218 | +A manifest may optionally have a single <b>R</b> card. The <b>R</b> card has | |
| 219 | 219 | a single argument which is the MD5 checksum of all files in |
| 220 | 220 | the check-in except the manifest itself. The checksum is expressed |
| 221 | 221 | as 32 characters of lowercase hexadecimal. The checksum is |
| 222 | 222 | computed as follows: For each file in the check-in (except for |
| 223 | 223 | the manifest itself) in strict sorted lexicographical order, |
| @@ -225,33 +225,33 @@ | ||
| 225 | 225 | repository, append a single space (ASCII 0x20), the |
| 226 | 226 | size of the file in ASCII decimal, a single newline |
| 227 | 227 | character (ASCII 0x0A), and the complete text of the file. |
| 228 | 228 | Compute the MD5 checksum of the result. |
| 229 | 229 | |
| 230 | -A manifest might contain one or more T-cards used to set | |
| 230 | +A manifest might contain one or more <b>T</b> cards used to set | |
| 231 | 231 | [./branching.wiki#tags | tags or properties] |
| 232 | -on the check-in. The format of the T-card is the same as | |
| 232 | +on the check-in. The format of the <b>T</b> card is the same as | |
| 233 | 233 | described in <i>Control Artifacts</i> section below, except that the |
| 234 | 234 | second argument is the single character "<b>*</b>" instead of an |
| 235 | 235 | artifact ID. The <b>*</b> in place of the artifact ID indicates that |
| 236 | 236 | the tag or property applies to the current artifact. It is not |
| 237 | 237 | possible to encode the current artifact ID as part of an artifact, |
| 238 | 238 | since the act of inserting the artifact ID would change the artifact ID, |
| 239 | -hence a <b>*</b> is used to represent "self". T-cards are typically | |
| 239 | +hence a <b>*</b> is used to represent "self". <b>T</b> cards are typically | |
| 240 | 240 | added to manifests in order to set the <b>branch</b> property and a |
| 241 | 241 | symbolic name when the check-in is intended to start a new branch. |
| 242 | 242 | |
| 243 | -Each manifest has a single U-card. The argument to the U-card is | |
| 243 | +Each manifest has a single <b>U</b> card. The argument to the <b>U</b> card is | |
| 244 | 244 | the login of the user who created the manifest. The login name |
| 245 | 245 | is encoded using the same character escapes as is used for the |
| 246 | -check-in comment argument to the C-card. | |
| 246 | +check-in comment argument to the <b>C</b> card. | |
| 247 | 247 | |
| 248 | -A manifest must have a single Z-card as its last line. The argument | |
| 249 | -to the Z-card is a 32-character lowercase hexadecimal MD5 hash | |
| 248 | +A manifest must have a single <b>Z</b> card as its last line. The argument | |
| 249 | +to the <b>Z</b> card is a 32-character lowercase hexadecimal MD5 hash | |
| 250 | 250 | of all prior lines of the manifest up to and including the newline |
| 251 | 251 | character that immediately precedes the "Z", excluding any PGP |
| 252 | -clear-signing prefix. The Z-card is | |
| 252 | +clear-signing prefix. The <b>Z</b> card is | |
| 253 | 253 | a sanity check to prove that the manifest is well-formed and |
| 254 | 254 | consistent. |
| 255 | 255 | |
| 256 | 256 | A sample manifest from Fossil itself can be seen |
| 257 | 257 | [/artifact/28987096ac | here]. |
| @@ -270,16 +270,16 @@ | ||
| 270 | 270 | <blockquote> |
| 271 | 271 | <b>M</b> <i>artifact-id</i><br /> |
| 272 | 272 | <b>Z</b> <i>checksum</i> |
| 273 | 273 | </blockquote> |
| 274 | 274 | |
| 275 | -A cluster contains one or more "M" cards followed by a single "Z" | |
| 276 | -card. Each M card has a single argument which is the artifact ID of | |
| 277 | -another artifact in the repository. The Z card works exactly like | |
| 278 | -the Z card of a manifest. The argument to the Z card is the | |
| 275 | +A cluster contains one or more <b>M</b> cards followed by a single <b>Z</b> card. | |
| 276 | +Each <b>M</b> card has a single argument which is the artifact ID of | |
| 277 | +another artifact in the repository. The <b>Z</b> card works exactly like | |
| 278 | +the <b>Z</b> card of a manifest. The argument to the <b>Z</b> card is the | |
| 279 | 279 | lower-case hexadecimal representation of the MD5 checksum of all |
| 280 | -prior cards in the cluster. The Z-card is required. | |
| 280 | +prior cards in the cluster. The <b>Z</b> card is required. | |
| 281 | 281 | |
| 282 | 282 | An example cluster from Fossil can be seen |
| 283 | 283 | [/artifact/d03dbdd73a2a8 | here]. |
| 284 | 284 | |
| 285 | 285 | <a name="ctrl"></a> |
| @@ -294,21 +294,21 @@ | ||
| 294 | 294 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br /> |
| 295 | 295 | <b>U</b> <i>user-name</i><br /> |
| 296 | 296 | <b>Z</b> <i>checksum</i><br /> |
| 297 | 297 | </blockquote> |
| 298 | 298 | |
| 299 | -A control artifact must have one D card, one U card, one Z card and | |
| 300 | -one or more T cards. No other cards or other text is | |
| 299 | +A control artifact must have one <b>D</b> card, one <b>U</b> card, one <b>Z</b> card and | |
| 300 | +one or more <b>T</b> cards. No other cards or other text is | |
| 301 | 301 | allowed in a control artifact. Control artifacts might be PGP |
| 302 | 302 | clearsigned. |
| 303 | 303 | |
| 304 | -The D card and the Z card of a control artifact are the same | |
| 304 | +The <b>D</b> card and the <b>Z</b> card of a control artifact are the same | |
| 305 | 305 | as in a manifest. |
| 306 | 306 | |
| 307 | -The T card represents a [./branching.wiki#tags | tag or property] | |
| 307 | +The <b>T</b> card represents a [./branching.wiki#tags | tag or property] | |
| 308 | 308 | that is applied to |
| 309 | -some other artifact. The T card has two or three values. The | |
| 309 | +some other artifact. The <b>T</b> card has two or three values. The | |
| 310 | 310 | second argument is the 40 character lowercase artifact ID of the artifact |
| 311 | 311 | to which the tag is to be applied. The |
| 312 | 312 | first value is the tag name. The first character of the tag |
| 313 | 313 | is either "+", "-", or "*". The "+" means the tag should be added |
| 314 | 314 | to the artifact. The "-" means the tag should be removed. |
| @@ -328,12 +328,12 @@ | ||
| 328 | 328 | for display purposes. The "user" tag overrides the name of the |
| 329 | 329 | check-in user. The "date" tag overrides the check-in date. |
| 330 | 330 | The "branch" tag sets the name of the branch that at check-in |
| 331 | 331 | belongs to. Symbolic tags begin with the "sym-" prefix. |
| 332 | 332 | |
| 333 | -The U card is the name of the user that created the control | |
| 334 | -artifact. The Z card is the usual required artifact checksum. | |
| 333 | +The <b>U</b> card is the name of the user that created the control | |
| 334 | +artifact. The <b>Z</b> card is the usual required artifact checksum. | |
| 335 | 335 | |
| 336 | 336 | An example control artifacts can be seen [/info/9d302ccda8 | here]. |
| 337 | 337 | |
| 338 | 338 | |
| 339 | 339 | <a name="wikichng"></a> |
| @@ -352,23 +352,23 @@ | ||
| 352 | 352 | <b>U</b> <i>user-name</i><br /> |
| 353 | 353 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 354 | 354 | <b>Z</b> <i>checksum</i> |
| 355 | 355 | </blockquote> |
| 356 | 356 | |
| 357 | -The D card is the date and time when the wiki page was edited. | |
| 358 | -The P card specifies the parent wiki pages, if any. The L card | |
| 359 | -gives the name of the wiki page. The optional N card specifies | |
| 360 | -the mimetype of the wiki text. If the N card is omitted, the | |
| 357 | +The <b>D</b> card is the date and time when the wiki page was edited. | |
| 358 | +The <b>P</b> card specifies the parent wiki pages, if any. The <b>L</b> card | |
| 359 | +gives the name of the wiki page. The optional <b>N</b> card specifies | |
| 360 | +the mimetype of the wiki text. If the <b>N</b> card is omitted, the | |
| 361 | 361 | mimetype is assumed to be text/x-fossil-wiki. |
| 362 | -The U card specifies the login | |
| 363 | -of the user who made this edit to the wiki page. The Z card is | |
| 362 | +The <b>U</b> card specifies the login | |
| 363 | +of the user who made this edit to the wiki page. The <b>Z</b> card is | |
| 364 | 364 | the usual checksum over the entire artifact and is required. |
| 365 | 365 | |
| 366 | -The W card is used to specify the text of the wiki page. The | |
| 367 | -argument to the W card is an integer which is the number of bytes | |
| 366 | +The <b>W</b> card is used to specify the text of the wiki page. The | |
| 367 | +argument to the <b>W</b> card is an integer which is the number of bytes | |
| 368 | 368 | of text in the wiki page. That text follows the newline character |
| 369 | -that terminates the W card. The wiki text is always followed by one | |
| 369 | +that terminates the <b>W</b> card. The wiki text is always followed by one | |
| 370 | 370 | extra newline. |
| 371 | 371 | |
| 372 | 372 | An example wiki artifact can be seen |
| 373 | 373 | [/artifact?name=7b2f5fd0e0&txt=1 | here]. |
| 374 | 374 | |
| @@ -384,38 +384,38 @@ | ||
| 384 | 384 | <b>K</b> <i>ticket-id</i><br /> |
| 385 | 385 | <b>U</b> <i>user-name</i><br /> |
| 386 | 386 | <b>Z</b> <i>checksum</i> |
| 387 | 387 | </blockquote> |
| 388 | 388 | |
| 389 | -The D card is the usual date and time stamp and represents the point | |
| 390 | -in time when the change was entered. The U card is the login of the | |
| 391 | -programmer who entered this change. The Z card is the required checksum over | |
| 389 | +The <b>D</b> card is the usual date and time stamp and represents the point | |
| 390 | +in time when the change was entered. The <b>U</b> card is the login of the | |
| 391 | +programmer who entered this change. The <b>Z</b> card is the required checksum over | |
| 392 | 392 | the entire artifact. |
| 393 | 393 | |
| 394 | 394 | Every ticket has a distinct ticket-id: |
| 395 | 395 | 40-character lower-case hexadecimal number. |
| 396 | -The ticket-id is given in the K-card. A ticket exists if it contains one or | |
| 396 | +The ticket-id is given in the <b>K</b> card. A ticket exists if it contains one or | |
| 397 | 397 | more changes. The first "change" to a ticket is what brings the |
| 398 | 398 | ticket into existence. |
| 399 | 399 | |
| 400 | -J cards specify changes to the "value" of "fields" in the ticket. | |
| 401 | -If the <i>value</i> parameter of the J card is omitted, then the | |
| 400 | +<b>J</b> cards specify changes to the "value" of "fields" in the ticket. | |
| 401 | +If the <i>value</i> parameter of the <b>J</b> card is omitted, then the | |
| 402 | 402 | field is set to an empty string. |
| 403 | 403 | Each fossil server has a ticket configuration which specifies the fields its |
| 404 | 404 | understands. The ticket configuration is part of the local state for |
| 405 | 405 | the repository and thus can vary from one repository to another. |
| 406 | -Hence a J card might specify a <i>field</i> that do not exist in the | |
| 407 | -local ticket configuration. If a J card specifies a <i>field</i> that | |
| 408 | -is not in the local configuration, then that J card | |
| 406 | +Hence a <b>J</b> card might specify a <i>field</i> that do not exist in the | |
| 407 | +local ticket configuration. If a <b>J</b> card specifies a <i>field</i> that | |
| 408 | +is not in the local configuration, then that <b>J</b> card | |
| 409 | 409 | is simply ignored. |
| 410 | 410 | |
| 411 | -The first argument of the J card is the field name. The second | |
| 411 | +The first argument of the <b>J</b> card is the field name. The second | |
| 412 | 412 | value is the field value. If the field name begins with "+" then |
| 413 | 413 | the value is appended to the prior value. Otherwise, the value |
| 414 | -on the J card replaces any previous value of the field. | |
| 414 | +on the <b>J</b> card replaces any previous value of the field. | |
| 415 | 415 | The field name and value are both encoded using the character |
| 416 | -escapes defined for the C card of a manifest. | |
| 416 | +escapes defined for the <b>C</b> card of a manifest. | |
| 417 | 417 | |
| 418 | 418 | An example ticket-change artifact can be seen |
| 419 | 419 | [/artifact/91f1ec6af053 | here]. |
| 420 | 420 | |
| 421 | 421 | <a name="attachment"></a> |
| @@ -434,32 +434,32 @@ | ||
| 434 | 434 | <b>N</b> <i>mimetype</i><br /> |
| 435 | 435 | <b>U</b> <i>user-name</i><br /> |
| 436 | 436 | <b>Z</b> <i>checksum</i> |
| 437 | 437 | </blockquote> |
| 438 | 438 | |
| 439 | -The A card specifies a filename for the attachment in its first argument. | |
| 440 | -The second argument to the A card is the name of the wiki page or | |
| 439 | +The <b>A</b> card specifies a filename for the attachment in its first argument. | |
| 440 | +The second argument to the <b>A</b> card is the name of the wiki page or | |
| 441 | 441 | ticket or technical note to which the attachment is connected. The |
| 442 | 442 | third argument is either missing or else it is the 40-character artifact |
| 443 | 443 | ID of the attachment itself. A missing third argument means that the |
| 444 | 444 | attachment should be deleted. |
| 445 | 445 | |
| 446 | -The C card is an optional comment describing what the attachment is about. | |
| 447 | -The C card is optional, but there can only be one. | |
| 446 | +The <b>C</b> card is an optional comment describing what the attachment is about. | |
| 447 | +The <b>C</b> card is optional, but there can only be one. | |
| 448 | 448 | |
| 449 | -A single D card is required to give the date and time when the attachment | |
| 449 | +A single <b>D</b> card is required to give the date and time when the attachment | |
| 450 | 450 | was applied. |
| 451 | 451 | |
| 452 | -There may be zero or one N cards. The N card specifies the mimetype of the | |
| 453 | -comment text provided in the C card. If the N card is omitted, the C card | |
| 452 | +There may be zero or one <b>N</b> cards. The <b>N</b> card specifies the mimetype of the | |
| 453 | +comment text provided in the <b>C</b> card. If the <b>N</b> card is omitted, the <b>C</b> card | |
| 454 | 454 | mimetype is taken to be text/plain. |
| 455 | 455 | |
| 456 | -A single U card gives the name of the user who added the attachment. | |
| 457 | -If an attachment is added anonymously, then the U card may be omitted. | |
| 456 | +A single <b>U</b> card gives the name of the user who added the attachment. | |
| 457 | +If an attachment is added anonymously, then the <b>U</b> card may be omitted. | |
| 458 | 458 | |
| 459 | -The Z card is the usual checksum over the rest of the attachment artifact. | |
| 460 | -The Z card is required. | |
| 459 | +The <b>Z</b> card is the usual checksum over the rest of the attachment artifact. | |
| 460 | +The <b>Z</b> card is required. | |
| 461 | 461 | |
| 462 | 462 | |
| 463 | 463 | <a name="event"></a> |
| 464 | 464 | <h3>2.7 Technical Notes</h3> |
| 465 | 465 | |
| @@ -480,55 +480,55 @@ | ||
| 480 | 480 | <b>U</b> <i>user-name</i><br /> |
| 481 | 481 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 482 | 482 | <b>Z</b> <i>checksum</i> |
| 483 | 483 | </blockquote> |
| 484 | 484 | |
| 485 | -The C card contains text that is displayed on the timeline for the | |
| 486 | -technote. The C card is optional, but there can only be one. | |
| 485 | +The <b>C</b> card contains text that is displayed on the timeline for the | |
| 486 | +technote. The <b>C</b> card is optional, but there can only be one. | |
| 487 | 487 | |
| 488 | -A single D card is required to give the date and time when the | |
| 488 | +A single <b>D</b> card is required to give the date and time when the | |
| 489 | 489 | technote artifact was created. This is different from the time at which |
| 490 | 490 | the technote appears on the timeline. |
| 491 | 491 | |
| 492 | -A single E card gives the time of the technote (the point on the timeline | |
| 492 | +A single <b>E</b> card gives the time of the technote (the point on the timeline | |
| 493 | 493 | where the technote is displayed) and a unique identifier for the technote. |
| 494 | 494 | When there are multiple artifacts with the same technote-id, the one with |
| 495 | -the most recent D card is the only one used. The technote-id must be a | |
| 495 | +the most recent <b>D</b> card is the only one used. The technote-id must be a | |
| 496 | 496 | 40-character lower-case hexadecimal string. |
| 497 | 497 | |
| 498 | -The optional N card specifies the mimetype of the text of the technote | |
| 499 | -that is contained in the W card. If the N card is omitted, then the | |
| 500 | -W card text mimetype is assumed to be text/x-fossil-wiki, which is the | |
| 498 | +The optional <b>N</b> card specifies the mimetype of the text of the technote | |
| 499 | +that is contained in the <b>W</b> card. If the <b>N</b> card is omitted, then the | |
| 500 | +<b>W</b> card text mimetype is assumed to be text/x-fossil-wiki, which is the | |
| 501 | 501 | Fossil wiki format. |
| 502 | 502 | |
| 503 | -The optional P card specifies a prior technote with the same technote-id | |
| 504 | -from which the current technote is an edit. The P card is a hint to the | |
| 503 | +The optional <b>P</b> card specifies a prior technote with the same technote-id | |
| 504 | +from which the current technote is an edit. The <b>P</b> card is a hint to the | |
| 505 | 505 | system that it might be space efficient to store one technote as a delta of |
| 506 | 506 | the other. |
| 507 | 507 | |
| 508 | -A technote might contain one or more T-cards used to set | |
| 508 | +A technote might contain one or more <b>T</b> cards used to set | |
| 509 | 509 | [./branching.wiki#tags | tags or properties] |
| 510 | -on the technote. The format of the T-card is the same as | |
| 510 | +on the technote. The format of the <b>T</b> card is the same as | |
| 511 | 511 | described in [#ctrl | Control Artifacts] section above, except that the |
| 512 | 512 | second argument is the single character "<b>*</b>" instead of an |
| 513 | 513 | artifact ID and the name is always prefaced by "<b>+</b>". |
| 514 | 514 | The <b>*</b> in place of the artifact ID indicates that |
| 515 | 515 | the tag or property applies to the current artifact. It is not |
| 516 | 516 | possible to encode the current artifact ID as part of an artifact, |
| 517 | 517 | since the act of inserting the artifact ID would change the artifact ID, |
| 518 | 518 | hence a <b>*</b> is used to represent "self". The "<b>+</b>" on the |
| 519 | 519 | name means that tags can only be add and they can only be non-propagating |
| 520 | -tags. In a technote, T cards are normally used to set the background | |
| 520 | +tags. In a technote, <b>T</b> cards are normally used to set the background | |
| 521 | 521 | display color for timelines. |
| 522 | 522 | |
| 523 | -The optional U card gives name of the user who entered the technote. | |
| 523 | +The optional <b>U</b> card gives name of the user who entered the technote. | |
| 524 | 524 | |
| 525 | -A single W card provides wiki text for the document associated with the | |
| 526 | -technote. The format of the W card is exactly the same as for a | |
| 525 | +A single <b>W</b> card provides wiki text for the document associated with the | |
| 526 | +technote. The format of the <b>W</b> card is exactly the same as for a | |
| 527 | 527 | [#wikichng | wiki artifact]. |
| 528 | 528 | |
| 529 | -The Z card is the required checksum over the rest of the artifact. | |
| 529 | +The <b>Z</b> card is the required checksum over the rest of the artifact. | |
| 530 | 530 | |
| 531 | 531 | <a name="forum"></a> |
| 532 | 532 | <h3>2.8 Forum Posts</h3> |
| 533 | 533 | |
| 534 | 534 | Forum posts are intended as a mechanism for users and developers to |
| @@ -546,63 +546,63 @@ | ||
| 546 | 546 | <b>U</b> <i>user-name</i><br /> |
| 547 | 547 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 548 | 548 | <b>Z</b> <i>checksum</i> |
| 549 | 549 | </blockquote> |
| 550 | 550 | |
| 551 | -Every forum post must have either one I card and one G card | |
| 552 | -or one H card. | |
| 551 | +Every forum post must have either one <b>I</b> card and one <b>G</b> card | |
| 552 | +or one <b>H</b> card. | |
| 553 | 553 | Forum posts are organized into topic threads. The initial |
| 554 | -post for a thread (the root post) has an H card giving the title or | |
| 555 | -subject for that thread. The argument to the H card is a string | |
| 556 | -in the same format as a comment string in a C card. | |
| 557 | -All follow-up posts have an I card that | |
| 554 | +post for a thread (the root post) has an <b>H</b> card giving the title or | |
| 555 | +subject for that thread. The argument to the <b>H</b> card is a string | |
| 556 | +in the same format as a comment string in a <b>C</b> card. | |
| 557 | +All follow-up posts have an <b>I</b> card that | |
| 558 | 558 | indicates which prior post in the same thread the current forum |
| 559 | -post is replying to, and a G card specifying the root post for | |
| 560 | -the entire thread. The argument to G and I cards is the | |
| 559 | +post is replying to, and a <b>G</b> card specifying the root post for | |
| 560 | +the entire thread. The argument to G and <b>I</b> cards is the | |
| 561 | 561 | artifact hash for the prior forum post to which the card refers. |
| 562 | 562 | |
| 563 | 563 | In theory, it is sufficient for follow-up posts to have only an |
| 564 | -I card, since the G card value could be computed by following a | |
| 565 | -chain of I cards. However, the G card is required in order to | |
| 564 | +<b>I</b> card, since the <b>G</b> card value could be computed by following a | |
| 565 | +chain of <b>I</b> cards. However, the <b>G</b> card is required in order to | |
| 566 | 566 | associate the artifact with a forum thread in the case where an |
| 567 | -intermediate artifact in the I card chain is shunned or otherwise | |
| 567 | +intermediate artifact in the <b>I</b> card chain is shunned or otherwise | |
| 568 | 568 | becomes unreadable. |
| 569 | 569 | |
| 570 | -A single D card is required to give the date and time when the | |
| 570 | +A single <b>D</b> card is required to give the date and time when the | |
| 571 | 571 | forum post was created. |
| 572 | 572 | |
| 573 | -The optional N card specifies the mimetype of the text of the technote | |
| 574 | -that is contained in the W card. If the N card is omitted, then the | |
| 575 | -W card text mimetype is assumed to be text/x-fossil-wiki, which is the | |
| 573 | +The optional <b>N</b> card specifies the mimetype of the text of the technote | |
| 574 | +that is contained in the <b>W</b> card. If the <b>N</b> card is omitted, then the | |
| 575 | +<b>W</b> card text mimetype is assumed to be text/x-fossil-wiki, which is the | |
| 576 | 576 | Fossil wiki format. |
| 577 | 577 | |
| 578 | -The optional P card specifies a prior forum post for which this | |
| 578 | +The optional <b>P</b> card specifies a prior forum post for which this | |
| 579 | 579 | forum post is an edit. For display purposes, only the child post |
| 580 | 580 | is shown, though the historical post is retained as a record. |
| 581 | -If P cards are used and there exist multiple versions of the same | |
| 582 | -forum post, then I cards for other artifacts refer to whichever | |
| 581 | +If <b>P</b> cards are used and there exist multiple versions of the same | |
| 582 | +forum post, then <b>I</b> cards for other artifacts refer to whichever | |
| 583 | 583 | version of the post was current at the time the reply was made, |
| 584 | -but G cards refer to the initial, unedited root post for the thread. | |
| 585 | -Thus, following the chain of I cards back to the root of the thread | |
| 586 | -may land on a different post than the one given in the G card. | |
| 587 | -However, following the chain of I cards back to the thread root, | |
| 588 | -then following P cards back to the initial version of the thread | |
| 589 | -root must give the same artifact as is provided by the G card, | |
| 590 | -otherwise the artifact containing the G card is considered invalid | |
| 584 | +but <b>G</b> cards refer to the initial, unedited root post for the thread. | |
| 585 | +Thus, following the chain of <b>I</b> cards back to the root of the thread | |
| 586 | +may land on a different post than the one given in the <b>G</b> card. | |
| 587 | +However, following the chain of <b>I</b> cards back to the thread root, | |
| 588 | +then following <b>P</b> cards back to the initial version of the thread | |
| 589 | +root must give the same artifact as is provided by the <b>G</b> card, | |
| 590 | +otherwise the artifact containing the <b>G</b> card is considered invalid | |
| 591 | 591 | and should be ignored. |
| 592 | 592 | |
| 593 | -In general, P cards may contain multiple arguments, indicating a | |
| 593 | +In general, <b>P</b> cards may contain multiple arguments, indicating a | |
| 594 | 594 | merge. But since forum posts cannot be merged, the |
| 595 | -P card of a forum post may only contain a single argument. | |
| 595 | +<b>P</b> card of a forum post may only contain a single argument. | |
| 596 | 596 | |
| 597 | -The U card gives name of the user who entered the forum post. | |
| 597 | +The <b>U</b> card gives name of the user who entered the forum post. | |
| 598 | 598 | |
| 599 | -A single W card provides wiki text for the forum post. | |
| 600 | -The format of the W card is exactly the same as for a | |
| 599 | +A single <b>W</b> card provides wiki text for the forum post. | |
| 600 | +The format of the <b>W</b> card is exactly the same as for a | |
| 601 | 601 | [#wikichng | wiki artifact]. |
| 602 | 602 | |
| 603 | -The Z card is the required checksum over the rest of the artifact. | |
| 603 | +The <b>Z</b> card is the required checksum over the rest of the artifact. | |
| 604 | 604 | |
| 605 | 605 | |
| 606 | 606 | <a name="summary"></a> |
| 607 | 607 | <h2>3.0 Card Summary</h2> |
| 608 | 608 | |
| @@ -868,11 +868,11 @@ | ||
| 868 | 868 | implementing algorithms described above. |
| 869 | 869 | |
| 870 | 870 | <h3>4.1 R-Card Hash Calculation</h3> |
| 871 | 871 | |
| 872 | 872 | Given a manifest file named <tt>MF</tt>, the following Bash shell code |
| 873 | -demonstrates how to compute the value of the R card in that manifest. | |
| 873 | +demonstrates how to compute the value of the <b>R</b> card in that manifest. | |
| 874 | 874 | This example uses manifest [28987096ac]. Lines starting with <tt>#</tt> are |
| 875 | 875 | shell input and other lines are output. This demonstration assumes that the |
| 876 | 876 | file versions represented by the input manifest are checked out |
| 877 | 877 | under the current directory. |
| 878 | 878 | |
| @@ -900,8 +900,8 @@ | ||
| 900 | 900 | Minor caveats: the above demonstration will work only when none of the |
| 901 | 901 | filenames in the manifest are "fossilized" (encoded) because they contain |
| 902 | 902 | spaces. In that case the shell-generated hash would differ because the |
| 903 | 903 | <tt>stat</tt> calls will fail to find such files (which are output in encoded |
| 904 | 904 | form here). That approach also won't work for delta manifests. Calculating |
| 905 | -the R-card for delta manifests requires traversing both the delta and its baseline in | |
| 905 | +the <b>R</b> card for delta manifests requires traversing both the delta and its baseline in | |
| 906 | 906 | lexical order of the files, preferring the delta's copy if both contain |
| 907 | 907 | a given file. |
| 908 | 908 |
| --- www/fileformat.wiki | |
| +++ www/fileformat.wiki | |
| @@ -125,99 +125,99 @@ | |
| 125 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <b>*</b> ?<i>value</i>?<br> |
| 126 | <b>U</b> <i>user-login</i><br> |
| 127 | <b>Z</b> <i>manifest-checksum</i> |
| 128 | </blockquote> |
| 129 | |
| 130 | A manifest may optionally have a single B-card. The B-card specifies |
| 131 | another manifest that serves as the "baseline" for this manifest. A |
| 132 | manifest that has a B-card is called a delta-manifest and a manifest |
| 133 | that omits the B-card is a baseline-manifest. The other manifest |
| 134 | identified by the argument of the B-card must be a baseline-manifest. |
| 135 | A baseline-manifest records the complete contents of a check-in. |
| 136 | A delta-manifest records only changes from its baseline. |
| 137 | |
| 138 | A manifest must have exactly one C-card. The sole argument to |
| 139 | the C-card is a check-in comment that describes the check-in that |
| 140 | the manifest defines. The check-in comment is text. The following |
| 141 | escape sequences are applied to the text: |
| 142 | A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A |
| 143 | newline (ASCII 0x0a) is "\n" (ASCII 0x5C, x6E). A backslash |
| 144 | (ASCII 0x5C) is represented as two backslashes "\\". Apart from |
| 145 | space and newline, no other whitespace characters are allowed in |
| 146 | the check-in comment. Nor are any unprintable characters allowed |
| 147 | in the comment. |
| 148 | |
| 149 | A manifest must have exactly one D-card. The sole argument to |
| 150 | the D-card is a date-time stamp in the ISO8601 format. The |
| 151 | date and time should be in coordinated universal time (UTC). |
| 152 | The format one of: |
| 153 | |
| 154 | <blockquote> |
| 155 | <i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i><br> |
| 156 | <i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i><b>.</b><i>SSS</i> |
| 157 | </blockquote> |
| 158 | |
| 159 | A manifest has zero or more F-cards. Each F-card identifies a file |
| 160 | that is part of the check-in. There are one, two, three, or four |
| 161 | arguments. The first argument is the pathname of the file in the |
| 162 | check-in relative to the root of the project file hierarchy. No ".." |
| 163 | or "." directories are allowed within the filename. Space characters |
| 164 | are escaped as in C-card comment text. Backslash characters and |
| 165 | newlines are not allowed within filenames. The directory separator |
| 166 | character is a forward slash (ASCII 0x2F). The second argument to the |
| 167 | F-card is the lower-case hexadecimal artifact hash of |
| 168 | the content artifact. The second argument is required for baseline |
| 169 | manifests but is optional for delta manifests. When the second |
| 170 | argument to the F-card is omitted, it means that the file has been |
| 171 | deleted relative to the baseline (files removed in baseline manifests |
| 172 | versions are <em>not</em> added as F-cards). The optional 3rd argument |
| 173 | defines any special access permissions associated with the file. This |
| 174 | can be defined as "x" to mean that the file is executable or "l" |
| 175 | (small letter ell) to mean a symlink. All files are always readable |
| 176 | and writable. This can be expressed by "w" permission if desired but |
| 177 | is optional. The file format might be extended with new permission |
| 178 | letters in the future. The optional 4th argument is the name of the |
| 179 | same file as it existed in the parent check-in. If the name of the |
| 180 | file is unchanged from its parent, then the 4th argument is omitted. |
| 181 | |
| 182 | A manifest has zero or one N-cards. The N-card specifies the mimetype for the |
| 183 | text in the comment of the C-card. If the N-card is omitted, a default mimetype |
| 184 | is used. |
| 185 | |
| 186 | A manifest has zero or one P-cards. Most manifests have one P-card. |
| 187 | The P-card has a varying number of arguments that |
| 188 | define other manifests from which the current manifest |
| 189 | is derived. Each argument is a lowercase |
| 190 | hexadecimal artifact hash of a predecessor manifest. All arguments |
| 191 | to the P-card must be unique within that card. |
| 192 | The first argument is the artifact hash of the direct ancestor of the manifest. |
| 193 | Other arguments define manifests with which the first was |
| 194 | merged to yield the current manifest. Most manifests have |
| 195 | a P-card with a single argument. The first manifest in the |
| 196 | project has no ancestors and thus has no P-card or (depending |
| 197 | on the Fossil version) an empty P-card (no arguments). |
| 198 | |
| 199 | A manifest has zero or more Q-cards. A Q-card is similar to a P-card |
| 200 | in that it defines a predecessor to the current check-in. But |
| 201 | whereas a P-card defines the immediate ancestor or a merge |
| 202 | ancestor, the Q-card is used to identify a single check-in or a small |
| 203 | range of check-ins which were cherry-picked for inclusion in or |
| 204 | exclusion from the current manifest. The first argument of |
| 205 | the Q-card is the artifact ID of another manifest (the "target") |
| 206 | which has had its changes included or excluded in the current manifest. |
| 207 | The target is preceded by "+" or "-" to show inclusion or |
| 208 | exclusion, respectively. The optional second argument to the |
| 209 | Q-card is another manifest artifact ID which is the "baseline" |
| 210 | for the cherry-pick. If omitted, the baseline is the primary |
| 211 | parent of the target. The |
| 212 | changes included or excluded consist of all changes moving from |
| 213 | the baseline to the target. |
| 214 | |
| 215 | The Q-card was added to the interface specification on 2011-02-26. |
| 216 | Older versions of Fossil will reject manifests that contain Q-cards. |
| 217 | |
| 218 | A manifest may optionally have a single R-card. The R-card has |
| 219 | a single argument which is the MD5 checksum of all files in |
| 220 | the check-in except the manifest itself. The checksum is expressed |
| 221 | as 32 characters of lowercase hexadecimal. The checksum is |
| 222 | computed as follows: For each file in the check-in (except for |
| 223 | the manifest itself) in strict sorted lexicographical order, |
| @@ -225,33 +225,33 @@ | |
| 225 | repository, append a single space (ASCII 0x20), the |
| 226 | size of the file in ASCII decimal, a single newline |
| 227 | character (ASCII 0x0A), and the complete text of the file. |
| 228 | Compute the MD5 checksum of the result. |
| 229 | |
| 230 | A manifest might contain one or more T-cards used to set |
| 231 | [./branching.wiki#tags | tags or properties] |
| 232 | on the check-in. The format of the T-card is the same as |
| 233 | described in <i>Control Artifacts</i> section below, except that the |
| 234 | second argument is the single character "<b>*</b>" instead of an |
| 235 | artifact ID. The <b>*</b> in place of the artifact ID indicates that |
| 236 | the tag or property applies to the current artifact. It is not |
| 237 | possible to encode the current artifact ID as part of an artifact, |
| 238 | since the act of inserting the artifact ID would change the artifact ID, |
| 239 | hence a <b>*</b> is used to represent "self". T-cards are typically |
| 240 | added to manifests in order to set the <b>branch</b> property and a |
| 241 | symbolic name when the check-in is intended to start a new branch. |
| 242 | |
| 243 | Each manifest has a single U-card. The argument to the U-card is |
| 244 | the login of the user who created the manifest. The login name |
| 245 | is encoded using the same character escapes as is used for the |
| 246 | check-in comment argument to the C-card. |
| 247 | |
| 248 | A manifest must have a single Z-card as its last line. The argument |
| 249 | to the Z-card is a 32-character lowercase hexadecimal MD5 hash |
| 250 | of all prior lines of the manifest up to and including the newline |
| 251 | character that immediately precedes the "Z", excluding any PGP |
| 252 | clear-signing prefix. The Z-card is |
| 253 | a sanity check to prove that the manifest is well-formed and |
| 254 | consistent. |
| 255 | |
| 256 | A sample manifest from Fossil itself can be seen |
| 257 | [/artifact/28987096ac | here]. |
| @@ -270,16 +270,16 @@ | |
| 270 | <blockquote> |
| 271 | <b>M</b> <i>artifact-id</i><br /> |
| 272 | <b>Z</b> <i>checksum</i> |
| 273 | </blockquote> |
| 274 | |
| 275 | A cluster contains one or more "M" cards followed by a single "Z" |
| 276 | card. Each M card has a single argument which is the artifact ID of |
| 277 | another artifact in the repository. The Z card works exactly like |
| 278 | the Z card of a manifest. The argument to the Z card is the |
| 279 | lower-case hexadecimal representation of the MD5 checksum of all |
| 280 | prior cards in the cluster. The Z-card is required. |
| 281 | |
| 282 | An example cluster from Fossil can be seen |
| 283 | [/artifact/d03dbdd73a2a8 | here]. |
| 284 | |
| 285 | <a name="ctrl"></a> |
| @@ -294,21 +294,21 @@ | |
| 294 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br /> |
| 295 | <b>U</b> <i>user-name</i><br /> |
| 296 | <b>Z</b> <i>checksum</i><br /> |
| 297 | </blockquote> |
| 298 | |
| 299 | A control artifact must have one D card, one U card, one Z card and |
| 300 | one or more T cards. No other cards or other text is |
| 301 | allowed in a control artifact. Control artifacts might be PGP |
| 302 | clearsigned. |
| 303 | |
| 304 | The D card and the Z card of a control artifact are the same |
| 305 | as in a manifest. |
| 306 | |
| 307 | The T card represents a [./branching.wiki#tags | tag or property] |
| 308 | that is applied to |
| 309 | some other artifact. The T card has two or three values. The |
| 310 | second argument is the 40 character lowercase artifact ID of the artifact |
| 311 | to which the tag is to be applied. The |
| 312 | first value is the tag name. The first character of the tag |
| 313 | is either "+", "-", or "*". The "+" means the tag should be added |
| 314 | to the artifact. The "-" means the tag should be removed. |
| @@ -328,12 +328,12 @@ | |
| 328 | for display purposes. The "user" tag overrides the name of the |
| 329 | check-in user. The "date" tag overrides the check-in date. |
| 330 | The "branch" tag sets the name of the branch that at check-in |
| 331 | belongs to. Symbolic tags begin with the "sym-" prefix. |
| 332 | |
| 333 | The U card is the name of the user that created the control |
| 334 | artifact. The Z card is the usual required artifact checksum. |
| 335 | |
| 336 | An example control artifacts can be seen [/info/9d302ccda8 | here]. |
| 337 | |
| 338 | |
| 339 | <a name="wikichng"></a> |
| @@ -352,23 +352,23 @@ | |
| 352 | <b>U</b> <i>user-name</i><br /> |
| 353 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 354 | <b>Z</b> <i>checksum</i> |
| 355 | </blockquote> |
| 356 | |
| 357 | The D card is the date and time when the wiki page was edited. |
| 358 | The P card specifies the parent wiki pages, if any. The L card |
| 359 | gives the name of the wiki page. The optional N card specifies |
| 360 | the mimetype of the wiki text. If the N card is omitted, the |
| 361 | mimetype is assumed to be text/x-fossil-wiki. |
| 362 | The U card specifies the login |
| 363 | of the user who made this edit to the wiki page. The Z card is |
| 364 | the usual checksum over the entire artifact and is required. |
| 365 | |
| 366 | The W card is used to specify the text of the wiki page. The |
| 367 | argument to the W card is an integer which is the number of bytes |
| 368 | of text in the wiki page. That text follows the newline character |
| 369 | that terminates the W card. The wiki text is always followed by one |
| 370 | extra newline. |
| 371 | |
| 372 | An example wiki artifact can be seen |
| 373 | [/artifact?name=7b2f5fd0e0&txt=1 | here]. |
| 374 | |
| @@ -384,38 +384,38 @@ | |
| 384 | <b>K</b> <i>ticket-id</i><br /> |
| 385 | <b>U</b> <i>user-name</i><br /> |
| 386 | <b>Z</b> <i>checksum</i> |
| 387 | </blockquote> |
| 388 | |
| 389 | The D card is the usual date and time stamp and represents the point |
| 390 | in time when the change was entered. The U card is the login of the |
| 391 | programmer who entered this change. The Z card is the required checksum over |
| 392 | the entire artifact. |
| 393 | |
| 394 | Every ticket has a distinct ticket-id: |
| 395 | 40-character lower-case hexadecimal number. |
| 396 | The ticket-id is given in the K-card. A ticket exists if it contains one or |
| 397 | more changes. The first "change" to a ticket is what brings the |
| 398 | ticket into existence. |
| 399 | |
| 400 | J cards specify changes to the "value" of "fields" in the ticket. |
| 401 | If the <i>value</i> parameter of the J card is omitted, then the |
| 402 | field is set to an empty string. |
| 403 | Each fossil server has a ticket configuration which specifies the fields its |
| 404 | understands. The ticket configuration is part of the local state for |
| 405 | the repository and thus can vary from one repository to another. |
| 406 | Hence a J card might specify a <i>field</i> that do not exist in the |
| 407 | local ticket configuration. If a J card specifies a <i>field</i> that |
| 408 | is not in the local configuration, then that J card |
| 409 | is simply ignored. |
| 410 | |
| 411 | The first argument of the J card is the field name. The second |
| 412 | value is the field value. If the field name begins with "+" then |
| 413 | the value is appended to the prior value. Otherwise, the value |
| 414 | on the J card replaces any previous value of the field. |
| 415 | The field name and value are both encoded using the character |
| 416 | escapes defined for the C card of a manifest. |
| 417 | |
| 418 | An example ticket-change artifact can be seen |
| 419 | [/artifact/91f1ec6af053 | here]. |
| 420 | |
| 421 | <a name="attachment"></a> |
| @@ -434,32 +434,32 @@ | |
| 434 | <b>N</b> <i>mimetype</i><br /> |
| 435 | <b>U</b> <i>user-name</i><br /> |
| 436 | <b>Z</b> <i>checksum</i> |
| 437 | </blockquote> |
| 438 | |
| 439 | The A card specifies a filename for the attachment in its first argument. |
| 440 | The second argument to the A card is the name of the wiki page or |
| 441 | ticket or technical note to which the attachment is connected. The |
| 442 | third argument is either missing or else it is the 40-character artifact |
| 443 | ID of the attachment itself. A missing third argument means that the |
| 444 | attachment should be deleted. |
| 445 | |
| 446 | The C card is an optional comment describing what the attachment is about. |
| 447 | The C card is optional, but there can only be one. |
| 448 | |
| 449 | A single D card is required to give the date and time when the attachment |
| 450 | was applied. |
| 451 | |
| 452 | There may be zero or one N cards. The N card specifies the mimetype of the |
| 453 | comment text provided in the C card. If the N card is omitted, the C card |
| 454 | mimetype is taken to be text/plain. |
| 455 | |
| 456 | A single U card gives the name of the user who added the attachment. |
| 457 | If an attachment is added anonymously, then the U card may be omitted. |
| 458 | |
| 459 | The Z card is the usual checksum over the rest of the attachment artifact. |
| 460 | The Z card is required. |
| 461 | |
| 462 | |
| 463 | <a name="event"></a> |
| 464 | <h3>2.7 Technical Notes</h3> |
| 465 | |
| @@ -480,55 +480,55 @@ | |
| 480 | <b>U</b> <i>user-name</i><br /> |
| 481 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 482 | <b>Z</b> <i>checksum</i> |
| 483 | </blockquote> |
| 484 | |
| 485 | The C card contains text that is displayed on the timeline for the |
| 486 | technote. The C card is optional, but there can only be one. |
| 487 | |
| 488 | A single D card is required to give the date and time when the |
| 489 | technote artifact was created. This is different from the time at which |
| 490 | the technote appears on the timeline. |
| 491 | |
| 492 | A single E card gives the time of the technote (the point on the timeline |
| 493 | where the technote is displayed) and a unique identifier for the technote. |
| 494 | When there are multiple artifacts with the same technote-id, the one with |
| 495 | the most recent D card is the only one used. The technote-id must be a |
| 496 | 40-character lower-case hexadecimal string. |
| 497 | |
| 498 | The optional N card specifies the mimetype of the text of the technote |
| 499 | that is contained in the W card. If the N card is omitted, then the |
| 500 | W card text mimetype is assumed to be text/x-fossil-wiki, which is the |
| 501 | Fossil wiki format. |
| 502 | |
| 503 | The optional P card specifies a prior technote with the same technote-id |
| 504 | from which the current technote is an edit. The P card is a hint to the |
| 505 | system that it might be space efficient to store one technote as a delta of |
| 506 | the other. |
| 507 | |
| 508 | A technote might contain one or more T-cards used to set |
| 509 | [./branching.wiki#tags | tags or properties] |
| 510 | on the technote. The format of the T-card is the same as |
| 511 | described in [#ctrl | Control Artifacts] section above, except that the |
| 512 | second argument is the single character "<b>*</b>" instead of an |
| 513 | artifact ID and the name is always prefaced by "<b>+</b>". |
| 514 | The <b>*</b> in place of the artifact ID indicates that |
| 515 | the tag or property applies to the current artifact. It is not |
| 516 | possible to encode the current artifact ID as part of an artifact, |
| 517 | since the act of inserting the artifact ID would change the artifact ID, |
| 518 | hence a <b>*</b> is used to represent "self". The "<b>+</b>" on the |
| 519 | name means that tags can only be add and they can only be non-propagating |
| 520 | tags. In a technote, T cards are normally used to set the background |
| 521 | display color for timelines. |
| 522 | |
| 523 | The optional U card gives name of the user who entered the technote. |
| 524 | |
| 525 | A single W card provides wiki text for the document associated with the |
| 526 | technote. The format of the W card is exactly the same as for a |
| 527 | [#wikichng | wiki artifact]. |
| 528 | |
| 529 | The Z card is the required checksum over the rest of the artifact. |
| 530 | |
| 531 | <a name="forum"></a> |
| 532 | <h3>2.8 Forum Posts</h3> |
| 533 | |
| 534 | Forum posts are intended as a mechanism for users and developers to |
| @@ -546,63 +546,63 @@ | |
| 546 | <b>U</b> <i>user-name</i><br /> |
| 547 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 548 | <b>Z</b> <i>checksum</i> |
| 549 | </blockquote> |
| 550 | |
| 551 | Every forum post must have either one I card and one G card |
| 552 | or one H card. |
| 553 | Forum posts are organized into topic threads. The initial |
| 554 | post for a thread (the root post) has an H card giving the title or |
| 555 | subject for that thread. The argument to the H card is a string |
| 556 | in the same format as a comment string in a C card. |
| 557 | All follow-up posts have an I card that |
| 558 | indicates which prior post in the same thread the current forum |
| 559 | post is replying to, and a G card specifying the root post for |
| 560 | the entire thread. The argument to G and I cards is the |
| 561 | artifact hash for the prior forum post to which the card refers. |
| 562 | |
| 563 | In theory, it is sufficient for follow-up posts to have only an |
| 564 | I card, since the G card value could be computed by following a |
| 565 | chain of I cards. However, the G card is required in order to |
| 566 | associate the artifact with a forum thread in the case where an |
| 567 | intermediate artifact in the I card chain is shunned or otherwise |
| 568 | becomes unreadable. |
| 569 | |
| 570 | A single D card is required to give the date and time when the |
| 571 | forum post was created. |
| 572 | |
| 573 | The optional N card specifies the mimetype of the text of the technote |
| 574 | that is contained in the W card. If the N card is omitted, then the |
| 575 | W card text mimetype is assumed to be text/x-fossil-wiki, which is the |
| 576 | Fossil wiki format. |
| 577 | |
| 578 | The optional P card specifies a prior forum post for which this |
| 579 | forum post is an edit. For display purposes, only the child post |
| 580 | is shown, though the historical post is retained as a record. |
| 581 | If P cards are used and there exist multiple versions of the same |
| 582 | forum post, then I cards for other artifacts refer to whichever |
| 583 | version of the post was current at the time the reply was made, |
| 584 | but G cards refer to the initial, unedited root post for the thread. |
| 585 | Thus, following the chain of I cards back to the root of the thread |
| 586 | may land on a different post than the one given in the G card. |
| 587 | However, following the chain of I cards back to the thread root, |
| 588 | then following P cards back to the initial version of the thread |
| 589 | root must give the same artifact as is provided by the G card, |
| 590 | otherwise the artifact containing the G card is considered invalid |
| 591 | and should be ignored. |
| 592 | |
| 593 | In general, P cards may contain multiple arguments, indicating a |
| 594 | merge. But since forum posts cannot be merged, the |
| 595 | P card of a forum post may only contain a single argument. |
| 596 | |
| 597 | The U card gives name of the user who entered the forum post. |
| 598 | |
| 599 | A single W card provides wiki text for the forum post. |
| 600 | The format of the W card is exactly the same as for a |
| 601 | [#wikichng | wiki artifact]. |
| 602 | |
| 603 | The Z card is the required checksum over the rest of the artifact. |
| 604 | |
| 605 | |
| 606 | <a name="summary"></a> |
| 607 | <h2>3.0 Card Summary</h2> |
| 608 | |
| @@ -868,11 +868,11 @@ | |
| 868 | implementing algorithms described above. |
| 869 | |
| 870 | <h3>4.1 R-Card Hash Calculation</h3> |
| 871 | |
| 872 | Given a manifest file named <tt>MF</tt>, the following Bash shell code |
| 873 | demonstrates how to compute the value of the R card in that manifest. |
| 874 | This example uses manifest [28987096ac]. Lines starting with <tt>#</tt> are |
| 875 | shell input and other lines are output. This demonstration assumes that the |
| 876 | file versions represented by the input manifest are checked out |
| 877 | under the current directory. |
| 878 | |
| @@ -900,8 +900,8 @@ | |
| 900 | Minor caveats: the above demonstration will work only when none of the |
| 901 | filenames in the manifest are "fossilized" (encoded) because they contain |
| 902 | spaces. In that case the shell-generated hash would differ because the |
| 903 | <tt>stat</tt> calls will fail to find such files (which are output in encoded |
| 904 | form here). That approach also won't work for delta manifests. Calculating |
| 905 | the R-card for delta manifests requires traversing both the delta and its baseline in |
| 906 | lexical order of the files, preferring the delta's copy if both contain |
| 907 | a given file. |
| 908 |
| --- www/fileformat.wiki | |
| +++ www/fileformat.wiki | |
| @@ -125,99 +125,99 @@ | |
| 125 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <b>*</b> ?<i>value</i>?<br> |
| 126 | <b>U</b> <i>user-login</i><br> |
| 127 | <b>Z</b> <i>manifest-checksum</i> |
| 128 | </blockquote> |
| 129 | |
| 130 | A manifest may optionally have a single <b>B</b> card. The <b>B</b> card specifies |
| 131 | another manifest that serves as the "baseline" for this manifest. A |
| 132 | manifest that has a <b>B</b> card is called a delta-manifest and a manifest |
| 133 | that omits the <b>B</b> card is a baseline-manifest. The other manifest |
| 134 | identified by the argument of the <b>B</b> card must be a baseline-manifest. |
| 135 | A baseline-manifest records the complete contents of a check-in. |
| 136 | A delta-manifest records only changes from its baseline. |
| 137 | |
| 138 | A manifest must have exactly one <b>C</b> card. The sole argument to |
| 139 | the <b>C</b> card is a check-in comment that describes the check-in that |
| 140 | the manifest defines. The check-in comment is text. The following |
| 141 | escape sequences are applied to the text: |
| 142 | A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A |
| 143 | newline (ASCII 0x0a) is "\n" (ASCII 0x5C, x6E). A backslash |
| 144 | (ASCII 0x5C) is represented as two backslashes "\\". Apart from |
| 145 | space and newline, no other whitespace characters are allowed in |
| 146 | the check-in comment. Nor are any unprintable characters allowed |
| 147 | in the comment. |
| 148 | |
| 149 | A manifest must have exactly one <b>D</b> card. The sole argument to |
| 150 | the <b>D</b> card is a date-time stamp in the ISO8601 format. The |
| 151 | date and time should be in coordinated universal time (UTC). |
| 152 | The format one of: |
| 153 | |
| 154 | <blockquote> |
| 155 | <i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i><br> |
| 156 | <i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i><b>.</b><i>SSS</i> |
| 157 | </blockquote> |
| 158 | |
| 159 | A manifest has zero or more <b>F</b> cards. Each <b>F</b> card identifies a file |
| 160 | that is part of the check-in. There are one, two, three, or four |
| 161 | arguments. The first argument is the pathname of the file in the |
| 162 | check-in relative to the root of the project file hierarchy. No ".." |
| 163 | or "." directories are allowed within the filename. Space characters |
| 164 | are escaped as in <b>C</b> card comment text. Backslash characters and |
| 165 | newlines are not allowed within filenames. The directory separator |
| 166 | character is a forward slash (ASCII 0x2F). The second argument to the |
| 167 | <b>F</b> card is the lower-case hexadecimal artifact hash of |
| 168 | the content artifact. The second argument is required for baseline |
| 169 | manifests but is optional for delta manifests. When the second |
| 170 | argument to the <b>F</b> card is omitted, it means that the file has been |
| 171 | deleted relative to the baseline (files removed in baseline manifests |
| 172 | versions are <em>not</em> added as <b>F</b> cards). The optional 3rd argument |
| 173 | defines any special access permissions associated with the file. This |
| 174 | can be defined as "x" to mean that the file is executable or "l" |
| 175 | (small letter ell) to mean a symlink. All files are always readable |
| 176 | and writable. This can be expressed by "w" permission if desired but |
| 177 | is optional. The file format might be extended with new permission |
| 178 | letters in the future. The optional 4th argument is the name of the |
| 179 | same file as it existed in the parent check-in. If the name of the |
| 180 | file is unchanged from its parent, then the 4th argument is omitted. |
| 181 | |
| 182 | A manifest has zero or one <b>N</b> cards. The <b>N</b> card specifies the mimetype for the |
| 183 | text in the comment of the <b>C</b> card. If the <b>N</b> card is omitted, a default mimetype |
| 184 | is used. |
| 185 | |
| 186 | A manifest has zero or one <b>P</b> cards. Most manifests have one <b>P</b> card. |
| 187 | The <b>P</b> card has a varying number of arguments that |
| 188 | define other manifests from which the current manifest |
| 189 | is derived. Each argument is a lowercase |
| 190 | hexadecimal artifact hash of a predecessor manifest. All arguments |
| 191 | to the <b>P</b> card must be unique within that card. |
| 192 | The first argument is the artifact hash of the direct ancestor of the manifest. |
| 193 | Other arguments define manifests with which the first was |
| 194 | merged to yield the current manifest. Most manifests have |
| 195 | a <b>P</b> card with a single argument. The first manifest in the |
| 196 | project has no ancestors and thus has no <b>P</b> card or (depending |
| 197 | on the Fossil version) an empty <b>P</b> card (no arguments). |
| 198 | |
| 199 | A manifest has zero or more <b>Q</b> cards. A <b>Q</b> card is similar to a <b>P</b> card |
| 200 | in that it defines a predecessor to the current check-in. But |
| 201 | whereas a <b>P</b> card defines the immediate ancestor or a merge |
| 202 | ancestor, the <b>Q</b> card is used to identify a single check-in or a small |
| 203 | range of check-ins which were cherry-picked for inclusion in or |
| 204 | exclusion from the current manifest. The first argument of |
| 205 | the <b>Q</b> card is the artifact ID of another manifest (the "target") |
| 206 | which has had its changes included or excluded in the current manifest. |
| 207 | The target is preceded by "+" or "-" to show inclusion or |
| 208 | exclusion, respectively. The optional second argument to the |
| 209 | <b>Q</b> card is another manifest artifact ID which is the "baseline" |
| 210 | for the cherry-pick. If omitted, the baseline is the primary |
| 211 | parent of the target. The |
| 212 | changes included or excluded consist of all changes moving from |
| 213 | the baseline to the target. |
| 214 | |
| 215 | The <b>Q</b> card was added to the interface specification on 2011-02-26. |
| 216 | Older versions of Fossil will reject manifests that contain <b>Q</b> cards. |
| 217 | |
| 218 | A manifest may optionally have a single <b>R</b> card. The <b>R</b> card has |
| 219 | a single argument which is the MD5 checksum of all files in |
| 220 | the check-in except the manifest itself. The checksum is expressed |
| 221 | as 32 characters of lowercase hexadecimal. The checksum is |
| 222 | computed as follows: For each file in the check-in (except for |
| 223 | the manifest itself) in strict sorted lexicographical order, |
| @@ -225,33 +225,33 @@ | |
| 225 | repository, append a single space (ASCII 0x20), the |
| 226 | size of the file in ASCII decimal, a single newline |
| 227 | character (ASCII 0x0A), and the complete text of the file. |
| 228 | Compute the MD5 checksum of the result. |
| 229 | |
| 230 | A manifest might contain one or more <b>T</b> cards used to set |
| 231 | [./branching.wiki#tags | tags or properties] |
| 232 | on the check-in. The format of the <b>T</b> card is the same as |
| 233 | described in <i>Control Artifacts</i> section below, except that the |
| 234 | second argument is the single character "<b>*</b>" instead of an |
| 235 | artifact ID. The <b>*</b> in place of the artifact ID indicates that |
| 236 | the tag or property applies to the current artifact. It is not |
| 237 | possible to encode the current artifact ID as part of an artifact, |
| 238 | since the act of inserting the artifact ID would change the artifact ID, |
| 239 | hence a <b>*</b> is used to represent "self". <b>T</b> cards are typically |
| 240 | added to manifests in order to set the <b>branch</b> property and a |
| 241 | symbolic name when the check-in is intended to start a new branch. |
| 242 | |
| 243 | Each manifest has a single <b>U</b> card. The argument to the <b>U</b> card is |
| 244 | the login of the user who created the manifest. The login name |
| 245 | is encoded using the same character escapes as is used for the |
| 246 | check-in comment argument to the <b>C</b> card. |
| 247 | |
| 248 | A manifest must have a single <b>Z</b> card as its last line. The argument |
| 249 | to the <b>Z</b> card is a 32-character lowercase hexadecimal MD5 hash |
| 250 | of all prior lines of the manifest up to and including the newline |
| 251 | character that immediately precedes the "Z", excluding any PGP |
| 252 | clear-signing prefix. The <b>Z</b> card is |
| 253 | a sanity check to prove that the manifest is well-formed and |
| 254 | consistent. |
| 255 | |
| 256 | A sample manifest from Fossil itself can be seen |
| 257 | [/artifact/28987096ac | here]. |
| @@ -270,16 +270,16 @@ | |
| 270 | <blockquote> |
| 271 | <b>M</b> <i>artifact-id</i><br /> |
| 272 | <b>Z</b> <i>checksum</i> |
| 273 | </blockquote> |
| 274 | |
| 275 | A cluster contains one or more <b>M</b> cards followed by a single <b>Z</b> card. |
| 276 | Each <b>M</b> card has a single argument which is the artifact ID of |
| 277 | another artifact in the repository. The <b>Z</b> card works exactly like |
| 278 | the <b>Z</b> card of a manifest. The argument to the <b>Z</b> card is the |
| 279 | lower-case hexadecimal representation of the MD5 checksum of all |
| 280 | prior cards in the cluster. The <b>Z</b> card is required. |
| 281 | |
| 282 | An example cluster from Fossil can be seen |
| 283 | [/artifact/d03dbdd73a2a8 | here]. |
| 284 | |
| 285 | <a name="ctrl"></a> |
| @@ -294,21 +294,21 @@ | |
| 294 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br /> |
| 295 | <b>U</b> <i>user-name</i><br /> |
| 296 | <b>Z</b> <i>checksum</i><br /> |
| 297 | </blockquote> |
| 298 | |
| 299 | A control artifact must have one <b>D</b> card, one <b>U</b> card, one <b>Z</b> card and |
| 300 | one or more <b>T</b> cards. No other cards or other text is |
| 301 | allowed in a control artifact. Control artifacts might be PGP |
| 302 | clearsigned. |
| 303 | |
| 304 | The <b>D</b> card and the <b>Z</b> card of a control artifact are the same |
| 305 | as in a manifest. |
| 306 | |
| 307 | The <b>T</b> card represents a [./branching.wiki#tags | tag or property] |
| 308 | that is applied to |
| 309 | some other artifact. The <b>T</b> card has two or three values. The |
| 310 | second argument is the 40 character lowercase artifact ID of the artifact |
| 311 | to which the tag is to be applied. The |
| 312 | first value is the tag name. The first character of the tag |
| 313 | is either "+", "-", or "*". The "+" means the tag should be added |
| 314 | to the artifact. The "-" means the tag should be removed. |
| @@ -328,12 +328,12 @@ | |
| 328 | for display purposes. The "user" tag overrides the name of the |
| 329 | check-in user. The "date" tag overrides the check-in date. |
| 330 | The "branch" tag sets the name of the branch that at check-in |
| 331 | belongs to. Symbolic tags begin with the "sym-" prefix. |
| 332 | |
| 333 | The <b>U</b> card is the name of the user that created the control |
| 334 | artifact. The <b>Z</b> card is the usual required artifact checksum. |
| 335 | |
| 336 | An example control artifacts can be seen [/info/9d302ccda8 | here]. |
| 337 | |
| 338 | |
| 339 | <a name="wikichng"></a> |
| @@ -352,23 +352,23 @@ | |
| 352 | <b>U</b> <i>user-name</i><br /> |
| 353 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 354 | <b>Z</b> <i>checksum</i> |
| 355 | </blockquote> |
| 356 | |
| 357 | The <b>D</b> card is the date and time when the wiki page was edited. |
| 358 | The <b>P</b> card specifies the parent wiki pages, if any. The <b>L</b> card |
| 359 | gives the name of the wiki page. The optional <b>N</b> card specifies |
| 360 | the mimetype of the wiki text. If the <b>N</b> card is omitted, the |
| 361 | mimetype is assumed to be text/x-fossil-wiki. |
| 362 | The <b>U</b> card specifies the login |
| 363 | of the user who made this edit to the wiki page. The <b>Z</b> card is |
| 364 | the usual checksum over the entire artifact and is required. |
| 365 | |
| 366 | The <b>W</b> card is used to specify the text of the wiki page. The |
| 367 | argument to the <b>W</b> card is an integer which is the number of bytes |
| 368 | of text in the wiki page. That text follows the newline character |
| 369 | that terminates the <b>W</b> card. The wiki text is always followed by one |
| 370 | extra newline. |
| 371 | |
| 372 | An example wiki artifact can be seen |
| 373 | [/artifact?name=7b2f5fd0e0&txt=1 | here]. |
| 374 | |
| @@ -384,38 +384,38 @@ | |
| 384 | <b>K</b> <i>ticket-id</i><br /> |
| 385 | <b>U</b> <i>user-name</i><br /> |
| 386 | <b>Z</b> <i>checksum</i> |
| 387 | </blockquote> |
| 388 | |
| 389 | The <b>D</b> card is the usual date and time stamp and represents the point |
| 390 | in time when the change was entered. The <b>U</b> card is the login of the |
| 391 | programmer who entered this change. The <b>Z</b> card is the required checksum over |
| 392 | the entire artifact. |
| 393 | |
| 394 | Every ticket has a distinct ticket-id: |
| 395 | 40-character lower-case hexadecimal number. |
| 396 | The ticket-id is given in the <b>K</b> card. A ticket exists if it contains one or |
| 397 | more changes. The first "change" to a ticket is what brings the |
| 398 | ticket into existence. |
| 399 | |
| 400 | <b>J</b> cards specify changes to the "value" of "fields" in the ticket. |
| 401 | If the <i>value</i> parameter of the <b>J</b> card is omitted, then the |
| 402 | field is set to an empty string. |
| 403 | Each fossil server has a ticket configuration which specifies the fields its |
| 404 | understands. The ticket configuration is part of the local state for |
| 405 | the repository and thus can vary from one repository to another. |
| 406 | Hence a <b>J</b> card might specify a <i>field</i> that do not exist in the |
| 407 | local ticket configuration. If a <b>J</b> card specifies a <i>field</i> that |
| 408 | is not in the local configuration, then that <b>J</b> card |
| 409 | is simply ignored. |
| 410 | |
| 411 | The first argument of the <b>J</b> card is the field name. The second |
| 412 | value is the field value. If the field name begins with "+" then |
| 413 | the value is appended to the prior value. Otherwise, the value |
| 414 | on the <b>J</b> card replaces any previous value of the field. |
| 415 | The field name and value are both encoded using the character |
| 416 | escapes defined for the <b>C</b> card of a manifest. |
| 417 | |
| 418 | An example ticket-change artifact can be seen |
| 419 | [/artifact/91f1ec6af053 | here]. |
| 420 | |
| 421 | <a name="attachment"></a> |
| @@ -434,32 +434,32 @@ | |
| 434 | <b>N</b> <i>mimetype</i><br /> |
| 435 | <b>U</b> <i>user-name</i><br /> |
| 436 | <b>Z</b> <i>checksum</i> |
| 437 | </blockquote> |
| 438 | |
| 439 | The <b>A</b> card specifies a filename for the attachment in its first argument. |
| 440 | The second argument to the <b>A</b> card is the name of the wiki page or |
| 441 | ticket or technical note to which the attachment is connected. The |
| 442 | third argument is either missing or else it is the 40-character artifact |
| 443 | ID of the attachment itself. A missing third argument means that the |
| 444 | attachment should be deleted. |
| 445 | |
| 446 | The <b>C</b> card is an optional comment describing what the attachment is about. |
| 447 | The <b>C</b> card is optional, but there can only be one. |
| 448 | |
| 449 | A single <b>D</b> card is required to give the date and time when the attachment |
| 450 | was applied. |
| 451 | |
| 452 | There may be zero or one <b>N</b> cards. The <b>N</b> card specifies the mimetype of the |
| 453 | comment text provided in the <b>C</b> card. If the <b>N</b> card is omitted, the <b>C</b> card |
| 454 | mimetype is taken to be text/plain. |
| 455 | |
| 456 | A single <b>U</b> card gives the name of the user who added the attachment. |
| 457 | If an attachment is added anonymously, then the <b>U</b> card may be omitted. |
| 458 | |
| 459 | The <b>Z</b> card is the usual checksum over the rest of the attachment artifact. |
| 460 | The <b>Z</b> card is required. |
| 461 | |
| 462 | |
| 463 | <a name="event"></a> |
| 464 | <h3>2.7 Technical Notes</h3> |
| 465 | |
| @@ -480,55 +480,55 @@ | |
| 480 | <b>U</b> <i>user-name</i><br /> |
| 481 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 482 | <b>Z</b> <i>checksum</i> |
| 483 | </blockquote> |
| 484 | |
| 485 | The <b>C</b> card contains text that is displayed on the timeline for the |
| 486 | technote. The <b>C</b> card is optional, but there can only be one. |
| 487 | |
| 488 | A single <b>D</b> card is required to give the date and time when the |
| 489 | technote artifact was created. This is different from the time at which |
| 490 | the technote appears on the timeline. |
| 491 | |
| 492 | A single <b>E</b> card gives the time of the technote (the point on the timeline |
| 493 | where the technote is displayed) and a unique identifier for the technote. |
| 494 | When there are multiple artifacts with the same technote-id, the one with |
| 495 | the most recent <b>D</b> card is the only one used. The technote-id must be a |
| 496 | 40-character lower-case hexadecimal string. |
| 497 | |
| 498 | The optional <b>N</b> card specifies the mimetype of the text of the technote |
| 499 | that is contained in the <b>W</b> card. If the <b>N</b> card is omitted, then the |
| 500 | <b>W</b> card text mimetype is assumed to be text/x-fossil-wiki, which is the |
| 501 | Fossil wiki format. |
| 502 | |
| 503 | The optional <b>P</b> card specifies a prior technote with the same technote-id |
| 504 | from which the current technote is an edit. The <b>P</b> card is a hint to the |
| 505 | system that it might be space efficient to store one technote as a delta of |
| 506 | the other. |
| 507 | |
| 508 | A technote might contain one or more <b>T</b> cards used to set |
| 509 | [./branching.wiki#tags | tags or properties] |
| 510 | on the technote. The format of the <b>T</b> card is the same as |
| 511 | described in [#ctrl | Control Artifacts] section above, except that the |
| 512 | second argument is the single character "<b>*</b>" instead of an |
| 513 | artifact ID and the name is always prefaced by "<b>+</b>". |
| 514 | The <b>*</b> in place of the artifact ID indicates that |
| 515 | the tag or property applies to the current artifact. It is not |
| 516 | possible to encode the current artifact ID as part of an artifact, |
| 517 | since the act of inserting the artifact ID would change the artifact ID, |
| 518 | hence a <b>*</b> is used to represent "self". The "<b>+</b>" on the |
| 519 | name means that tags can only be add and they can only be non-propagating |
| 520 | tags. In a technote, <b>T</b> cards are normally used to set the background |
| 521 | display color for timelines. |
| 522 | |
| 523 | The optional <b>U</b> card gives name of the user who entered the technote. |
| 524 | |
| 525 | A single <b>W</b> card provides wiki text for the document associated with the |
| 526 | technote. The format of the <b>W</b> card is exactly the same as for a |
| 527 | [#wikichng | wiki artifact]. |
| 528 | |
| 529 | The <b>Z</b> card is the required checksum over the rest of the artifact. |
| 530 | |
| 531 | <a name="forum"></a> |
| 532 | <h3>2.8 Forum Posts</h3> |
| 533 | |
| 534 | Forum posts are intended as a mechanism for users and developers to |
| @@ -546,63 +546,63 @@ | |
| 546 | <b>U</b> <i>user-name</i><br /> |
| 547 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 548 | <b>Z</b> <i>checksum</i> |
| 549 | </blockquote> |
| 550 | |
| 551 | Every forum post must have either one <b>I</b> card and one <b>G</b> card |
| 552 | or one <b>H</b> card. |
| 553 | Forum posts are organized into topic threads. The initial |
| 554 | post for a thread (the root post) has an <b>H</b> card giving the title or |
| 555 | subject for that thread. The argument to the <b>H</b> card is a string |
| 556 | in the same format as a comment string in a <b>C</b> card. |
| 557 | All follow-up posts have an <b>I</b> card that |
| 558 | indicates which prior post in the same thread the current forum |
| 559 | post is replying to, and a <b>G</b> card specifying the root post for |
| 560 | the entire thread. The argument to G and <b>I</b> cards is the |
| 561 | artifact hash for the prior forum post to which the card refers. |
| 562 | |
| 563 | In theory, it is sufficient for follow-up posts to have only an |
| 564 | <b>I</b> card, since the <b>G</b> card value could be computed by following a |
| 565 | chain of <b>I</b> cards. However, the <b>G</b> card is required in order to |
| 566 | associate the artifact with a forum thread in the case where an |
| 567 | intermediate artifact in the <b>I</b> card chain is shunned or otherwise |
| 568 | becomes unreadable. |
| 569 | |
| 570 | A single <b>D</b> card is required to give the date and time when the |
| 571 | forum post was created. |
| 572 | |
| 573 | The optional <b>N</b> card specifies the mimetype of the text of the technote |
| 574 | that is contained in the <b>W</b> card. If the <b>N</b> card is omitted, then the |
| 575 | <b>W</b> card text mimetype is assumed to be text/x-fossil-wiki, which is the |
| 576 | Fossil wiki format. |
| 577 | |
| 578 | The optional <b>P</b> card specifies a prior forum post for which this |
| 579 | forum post is an edit. For display purposes, only the child post |
| 580 | is shown, though the historical post is retained as a record. |
| 581 | If <b>P</b> cards are used and there exist multiple versions of the same |
| 582 | forum post, then <b>I</b> cards for other artifacts refer to whichever |
| 583 | version of the post was current at the time the reply was made, |
| 584 | but <b>G</b> cards refer to the initial, unedited root post for the thread. |
| 585 | Thus, following the chain of <b>I</b> cards back to the root of the thread |
| 586 | may land on a different post than the one given in the <b>G</b> card. |
| 587 | However, following the chain of <b>I</b> cards back to the thread root, |
| 588 | then following <b>P</b> cards back to the initial version of the thread |
| 589 | root must give the same artifact as is provided by the <b>G</b> card, |
| 590 | otherwise the artifact containing the <b>G</b> card is considered invalid |
| 591 | and should be ignored. |
| 592 | |
| 593 | In general, <b>P</b> cards may contain multiple arguments, indicating a |
| 594 | merge. But since forum posts cannot be merged, the |
| 595 | <b>P</b> card of a forum post may only contain a single argument. |
| 596 | |
| 597 | The <b>U</b> card gives name of the user who entered the forum post. |
| 598 | |
| 599 | A single <b>W</b> card provides wiki text for the forum post. |
| 600 | The format of the <b>W</b> card is exactly the same as for a |
| 601 | [#wikichng | wiki artifact]. |
| 602 | |
| 603 | The <b>Z</b> card is the required checksum over the rest of the artifact. |
| 604 | |
| 605 | |
| 606 | <a name="summary"></a> |
| 607 | <h2>3.0 Card Summary</h2> |
| 608 | |
| @@ -868,11 +868,11 @@ | |
| 868 | implementing algorithms described above. |
| 869 | |
| 870 | <h3>4.1 R-Card Hash Calculation</h3> |
| 871 | |
| 872 | Given a manifest file named <tt>MF</tt>, the following Bash shell code |
| 873 | demonstrates how to compute the value of the <b>R</b> card in that manifest. |
| 874 | This example uses manifest [28987096ac]. Lines starting with <tt>#</tt> are |
| 875 | shell input and other lines are output. This demonstration assumes that the |
| 876 | file versions represented by the input manifest are checked out |
| 877 | under the current directory. |
| 878 | |
| @@ -900,8 +900,8 @@ | |
| 900 | Minor caveats: the above demonstration will work only when none of the |
| 901 | filenames in the manifest are "fossilized" (encoded) because they contain |
| 902 | spaces. In that case the shell-generated hash would differ because the |
| 903 | <tt>stat</tt> calls will fail to find such files (which are output in encoded |
| 904 | form here). That approach also won't work for delta manifests. Calculating |
| 905 | the <b>R</b> card for delta manifests requires traversing both the delta and its baseline in |
| 906 | lexical order of the files, preferring the delta's copy if both contain |
| 907 | a given file. |
| 908 |