Artifact 85a1fd60fbebfd33ae1406e9d22130ad36fc4909:
File
www/fileformat.html
part of check-in
[dbda8d6ce9]
- Initial check-in of m1 sources.
by
drh on
2007-07-21 14:10:57.
0000: 3c 68 74 6d 6c 3e 0a 3c 68 65 61 64 3e 0a 3c 74 <html>.<head>.<t
0010: 69 74 6c 65 3e 46 6f 73 73 69 6c 20 46 69 6c 65 itle>Fossil File
0020: 20 46 6f 72 6d 61 74 73 3c 2f 74 69 74 6c 65 3e Formats</title>
0030: 0a 3c 2f 68 65 61 64 3e 0a 3c 62 6f 64 79 20 62 .</head>.<body b
0040: 67 63 6f 6c 6f 72 3d 22 77 68 69 74 65 22 3e 0a gcolor="white">.
0050: 3c 68 31 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 <h1 align="cente
0060: 72 22 3e 0a 46 6f 73 73 69 6c 20 46 69 6c 65 20 r">.Fossil File
0070: 46 6f 72 6d 61 74 73 0a 3c 2f 68 31 3e 0a 0a 3c Formats.</h1>..<
0080: 70 3e 0a 54 68 65 20 67 6c 6f 62 61 6c 20 73 74 p>.The global st
0090: 61 74 65 20 6f 66 20 61 20 66 6f 73 73 69 6c 20 ate of a fossil
00a0: 72 65 70 6f 73 69 74 6f 72 79 20 69 73 20 64 65 repository is de
00b0: 74 65 72 6d 69 6e 65 64 20 62 79 20 61 6e 20 75 termined by an u
00c0: 6e 6f 72 64 65 72 65 64 0a 73 65 74 20 6f 66 20 nordered.set of
00d0: 63 6f 6e 74 65 6e 74 20 66 69 6c 65 73 2e 20 20 content files.
00e0: 45 61 63 68 20 6f 66 20 74 68 65 73 65 20 66 69 Each of these fi
00f0: 6c 65 73 20 68 61 73 20 61 20 66 6f 72 6d 61 74 les has a format
0100: 20 77 68 69 63 68 20 69 73 20 64 65 66 69 6e 65 which is define
0110: 64 0a 62 79 20 74 68 69 73 20 64 6f 63 75 6d 65 d.by this docume
0120: 6e 74 2e 0a 3c 2f 70 3e 0a 0a 3c 68 32 3e 31 2e nt..</p>..<h2>1.
0130: 30 20 47 65 6e 65 72 61 6c 20 46 6f 72 6d 61 74 0 General Format
0140: 74 69 6e 67 20 52 75 6c 65 73 3c 2f 68 32 3e 0a ting Rules</h2>.
0150: 0a 3c 70 3e 0a 46 6f 73 73 69 6c 20 63 6f 6e 74 .<p>.Fossil cont
0160: 65 6e 74 20 66 69 6c 65 73 20 63 6f 6e 73 69 73 ent files consis
0170: 74 20 6f 66 20 61 20 68 65 61 64 65 72 2c 20 61 t of a header, a
0180: 20 62 6c 61 6e 6b 20 6c 69 6e 65 2c 20 61 6e 64 blank line, and
0190: 20 6f 70 74 69 6f 6e 61 6c 0a 63 6f 6e 74 65 6e optional.conten
01a0: 74 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 t..</p>..<p>.The
01b0: 20 68 65 61 64 65 72 20 69 73 20 64 69 76 69 64 header is divid
01c0: 65 64 20 69 6e 74 6f 20 22 70 72 6f 70 65 72 74 ed into "propert
01d0: 69 65 73 22 20 62 79 20 6e 65 77 6c 69 6e 65 20 ies" by newline
01e0: 28 27 5c 6e 27 2c 20 30 78 30 61 29 0a 63 68 61 ('\n', 0x0a).cha
01f0: 72 61 63 74 65 72 73 2e 20 20 45 61 63 68 20 68 racters. Each h
0200: 65 61 64 65 72 20 70 72 6f 70 65 72 74 79 20 69 eader property i
0210: 73 20 64 69 76 69 64 65 64 20 69 6e 74 6f 20 74 s divided into t
0220: 6f 6b 65 6e 73 20 62 79 20 73 70 61 63 65 20 28 okens by space (
0230: 27 20 27 2c 20 30 78 32 30 29 0a 63 68 61 72 61 ' ', 0x20).chara
0240: 63 74 65 72 73 2e 20 20 54 68 65 20 66 69 72 73 cters. The firs
0250: 74 20 74 6f 6b 65 6e 20 6f 66 20 65 61 63 68 20 t token of each
0260: 70 72 6f 70 65 72 74 79 20 69 73 20 74 68 65 20 property is the
0270: 70 72 6f 70 65 72 74 79 20 6e 61 6d 65 2e 0a 53 property name..S
0280: 75 62 73 65 71 75 65 6e 74 20 74 6f 6b 65 6e 73 ubsequent tokens
0290: 20 28 69 66 20 61 6e 79 29 20 61 72 65 20 61 72 (if any) are ar
02a0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 70 guments to the p
02b0: 72 6f 70 65 72 74 79 2e 0a 3c 2f 70 3e 0a 0a 3c roperty..</p>..<
02c0: 70 3e 0a 54 68 65 20 62 6c 61 6e 6b 20 6c 69 6e p>.The blank lin
02d0: 65 20 74 68 61 74 20 73 65 70 61 72 61 74 65 73 e that separates
02e0: 20 74 68 65 20 68 65 61 64 65 72 20 66 72 6f 6d the header from
02f0: 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 63 61 6e the content can
0300: 20 62 65 0a 74 68 6f 75 67 68 74 20 6f 66 20 61 be.thought of a
0310: 73 20 61 20 70 72 6f 70 65 72 74 79 20 6c 69 6e s a property lin
0320: 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 e that contains
0330: 6e 6f 20 74 6f 6b 65 6e 73 2e 20 20 45 76 65 72 no tokens. Ever
0340: 79 74 68 69 6e 67 0a 74 68 61 74 20 66 6f 6c 6c ything.that foll
0350: 6f 77 73 20 74 68 65 20 6e 65 77 6c 69 6e 65 20 ows the newline
0360: 63 68 61 72 61 63 74 65 72 20 74 68 61 74 20 74 character that t
0370: 65 72 6d 69 6e 61 74 65 73 20 74 68 65 20 62 6c erminates the bl
0380: 61 6e 6b 20 6c 69 6e 65 0a 69 73 20 63 6f 6e 74 ank line.is cont
0390: 65 6e 74 2e 20 20 54 68 65 20 62 6c 61 6e 6b 20 ent. The blank
03a0: 6c 69 6e 65 20 69 73 20 61 6c 77 61 79 73 20 70 line is always p
03b0: 72 65 73 65 6e 74 20 62 75 74 20 74 68 65 20 63 resent but the c
03c0: 6f 6e 74 65 6e 74 20 69 73 0a 6f 70 74 69 6f 6e ontent is.option
03d0: 61 6c 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 41 6c al..</p>..<p>.Al
03e0: 6c 20 74 6f 6b 65 6e 73 20 69 6e 20 61 20 70 72 l tokens in a pr
03f0: 6f 70 65 72 74 79 20 6c 69 6e 65 20 61 72 65 20 operty line are
0400: 65 6e 63 6f 64 65 64 20 74 6f 20 65 73 63 61 70 encoded to escap
0410: 65 20 73 70 65 63 69 61 6c 20 63 68 61 72 61 63 e special charac
0420: 74 65 72 73 2e 0a 54 68 65 20 65 6e 63 6f 64 69 ters..The encodi
0430: 6e 67 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 ng is as follows
0440: 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 :.</p>..<blockqu
0450: 6f 74 65 3e 0a 3c 74 61 62 6c 65 20 62 6f 72 64 ote>.<table bord
0460: 65 72 3d 22 31 22 3e 0a 3c 74 72 3e 3c 74 68 3e er="1">.<tr><th>
0470: 49 6e 70 75 74 20 43 68 61 72 61 63 74 65 72 3c Input Character<
0480: 2f 74 68 3e 3c 74 68 3e 45 6e 63 6f 64 65 64 20 /th><th>Encoded
0490: 41 73 3c 2f 74 68 3e 3c 2f 74 72 3e 0a 3c 74 72 As</th></tr>.<tr
04a0: 3e 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 ><td align="cent
04b0: 65 72 22 3e 20 73 70 61 63 65 20 28 30 78 32 30 er"> space (0x20
04c0: 29 20 3c 2f 74 64 3e 3c 74 64 20 61 6c 69 67 6e ) </td><td align
04d0: 3d 22 63 65 6e 74 65 72 22 3e 20 5c 73 20 3c 2f ="center"> \s </
04e0: 74 64 3e 3c 2f 74 72 3e 0a 3c 74 72 3e 3c 74 64 td></tr>.<tr><td
04f0: 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e align="center">
0500: 20 6e 65 77 6c 69 6e 65 20 28 30 78 30 41 29 20 newline (0x0A)
0510: 3c 2f 74 64 3e 3c 74 64 20 61 6c 69 67 6e 3d 22 </td><td align="
0520: 63 65 6e 74 65 72 22 3e 20 5c 6e 20 3c 2f 74 64 center"> \n </td
0530: 3e 3c 2f 74 72 3e 0a 3c 74 72 3e 3c 74 64 20 61 ></tr>.<tr><td a
0540: 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 20 63 lign="center"> c
0550: 61 72 72 69 61 67 65 20 72 65 74 75 72 6e 20 28 arriage return (
0560: 30 78 30 44 29 20 3c 2f 74 64 3e 3c 74 64 20 61 0x0D) </td><td a
0570: 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 20 5c lign="center"> \
0580: 72 20 3c 2f 74 64 3e 3c 2f 74 72 3e 0a 3c 74 72 r </td></tr>.<tr
0590: 3e 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 ><td align="cent
05a0: 65 72 22 3e 20 74 61 62 20 28 30 78 30 39 29 20 er"> tab (0x09)
05b0: 3c 2f 74 64 3e 3c 74 64 20 61 6c 69 67 6e 3d 22 </td><td align="
05c0: 63 65 6e 74 65 72 22 3e 20 5c 74 20 3c 2f 74 64 center"> \t </td
05d0: 3e 3c 2f 74 72 3e 0a 3c 74 72 3e 3c 74 64 20 61 ></tr>.<tr><td a
05e0: 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 20 76 lign="center"> v
05f0: 65 72 74 69 63 61 6c 20 74 61 62 20 28 30 78 30 ertical tab (0x0
0600: 42 29 20 3c 2f 74 64 3e 3c 74 64 20 61 6c 69 67 B) </td><td alig
0610: 6e 3d 22 63 65 6e 74 65 72 22 3e 20 5c 76 20 3c n="center"> \v <
0620: 2f 74 64 3e 3c 2f 74 72 3e 0a 3c 74 72 3e 3c 74 /td></tr>.<tr><t
0630: 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 d align="center"
0640: 3e 20 66 6f 72 6d 66 65 65 64 20 28 30 78 30 43 > formfeed (0x0C
0650: 29 20 3c 2f 74 64 3e 3c 74 64 20 61 6c 69 67 6e ) </td><td align
0660: 3d 22 63 65 6e 74 65 72 22 3e 20 5c 66 20 3c 2f ="center"> \f </
0670: 74 64 3e 3c 2f 74 72 3e 0a 3c 74 72 3e 3c 74 64 td></tr>.<tr><td
0680: 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e align="center">
0690: 20 6e 75 6c 20 28 30 78 30 30 29 20 3c 2f 74 64 nul (0x00) </td
06a0: 3e 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 ><td align="cent
06b0: 65 72 22 3e 20 5c 30 20 3c 2f 74 64 3e 3c 2f 74 er"> \0 </td></t
06c0: 72 3e 0a 3c 74 72 3e 3c 74 64 20 61 6c 69 67 6e r>.<tr><td align
06d0: 3d 22 63 65 6e 74 65 72 22 3e 20 62 61 63 6b 73 ="center"> backs
06e0: 6c 61 73 68 20 28 30 78 35 43 29 20 3c 2f 74 64 lash (0x5C) </td
06f0: 3e 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 ><td align="cent
0700: 65 72 22 3e 20 5c 5c 20 3c 2f 74 64 3e 3c 2f 74 er"> \\ </td></t
0710: 72 3e 0a 3c 2f 74 61 62 6c 65 3e 0a 3c 2f 62 6c r>.</table>.</bl
0720: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 43 ockquote>..<p>.C
0730: 68 61 72 61 63 74 65 72 73 20 6f 74 68 65 72 20 haracters other
0740: 74 68 61 6e 20 74 68 65 20 6f 6e 65 73 20 73 68 than the ones sh
0750: 6f 77 6e 20 69 6e 20 74 68 65 20 74 61 62 6c 65 own in the table
0760: 20 61 62 6f 76 65 20 61 72 65 20 70 61 73 73 65 above are passe
0770: 64 20 74 68 72 6f 75 67 68 0a 74 68 65 20 65 6e d through.the en
0780: 63 6f 64 65 72 20 77 69 74 68 6f 75 74 20 63 68 coder without ch
0790: 61 6e 67 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a ange..</p>..<p>.
07a0: 41 6c 6c 20 70 72 6f 70 65 72 74 69 65 73 20 6e All properties n
07b0: 61 6d 65 73 20 61 72 65 20 75 6e 70 75 6e 63 74 ames are unpunct
07c0: 75 61 74 65 64 20 6c 6f 77 65 72 2d 63 61 73 65 uated lower-case
07d0: 20 41 53 43 49 49 20 73 74 72 69 6e 67 73 2e 0a ASCII strings..
07e0: 54 68 65 20 70 72 6f 70 65 72 74 69 65 73 20 61 The properties a
07f0: 70 70 65 61 72 20 69 6e 20 74 68 65 20 68 65 61 ppear in the hea
0800: 64 65 72 20 69 6e 20 73 6f 72 74 65 64 20 6f 72 der in sorted or
0810: 64 65 72 20 28 75 73 69 6e 67 0a 6d 65 6d 63 70 der (using.memcp
0820: 79 28 29 20 61 73 20 74 68 65 20 63 6f 6d 70 61 y() as the compa
0830: 72 69 73 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 29 rision function)
0840: 20 65 78 63 65 70 74 20 66 6f 72 20 74 68 65 20 except for the
0850: 22 73 69 67 6e 61 74 75 72 65 22 0a 70 72 6f 70 "signature".prop
0860: 65 72 74 79 20 77 68 69 63 68 20 61 6c 77 61 79 erty which alway
0870: 73 20 6f 63 63 75 72 73 20 66 69 72 73 74 2e 0a s occurs first..
0880: 3c 2f 70 3e 0a 0a 3c 68 32 3e 32 2e 30 20 43 6f </p>..<h2>2.0 Co
0890: 6d 6d 6f 6e 20 50 72 6f 70 65 72 74 69 65 73 3c mmon Properties<
08a0: 2f 68 32 3e 0a 0a 3c 70 3e 0a 45 76 65 72 79 20 /h2>..<p>.Every
08b0: 63 6f 6e 74 65 6e 74 20 66 69 6c 65 20 68 61 73 content file has
08c0: 20 61 20 22 74 69 6d 65 22 20 70 72 6f 70 65 72 a "time" proper
08d0: 74 79 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e ty. The argumen
08e0: 74 20 74 6f 20 74 68 65 0a 74 69 6d 65 20 70 72 t to the.time pr
08f0: 6f 70 65 72 74 79 20 69 73 20 61 6e 20 69 6e 74 operty is an int
0900: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68 eger which is th
0910: 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 65 63 6f e number of seco
0920: 6e 64 73 20 73 69 6e 63 65 0a 31 39 37 30 20 55 nds since.1970 U
0930: 54 43 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 74 TC when the cont
0940: 65 6e 74 20 66 69 6c 65 20 77 61 73 20 63 72 65 ent file was cre
0950: 61 74 65 64 2e 20 20 46 6f 72 20 65 78 61 6d 70 ated. For examp
0960: 6c 65 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b le:.</p>..<block
0970: 71 75 6f 74 65 3e 0a 74 69 6d 65 20 31 31 38 31 quote>.time 1181
0980: 34 30 34 37 34 36 0a 3c 2f 62 6c 6f 63 6b 71 75 404746.</blockqu
0990: 6f 74 65 3e 0a 0a 3c 70 3e 0a 45 76 65 72 79 20 ote>..<p>.Every
09a0: 63 6f 6e 74 65 6e 74 20 66 69 6c 65 20 68 61 73 content file has
09b0: 20 61 20 22 74 79 70 65 22 20 70 72 6f 70 65 72 a "type" proper
09c0: 74 79 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e ty. The argumen
09d0: 74 20 74 6f 20 74 68 65 0a 74 79 70 65 20 70 72 t to the.type pr
09e0: 6f 70 65 72 74 79 20 64 65 66 69 6e 65 73 20 74 operty defines t
09f0: 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 he purpose of th
0a00: 65 20 63 6f 6e 74 65 6e 74 20 66 69 6c 65 2e 20 e content file.
0a10: 20 54 68 65 0a 61 72 67 75 6d 65 6e 74 20 63 61 The.argument ca
0a20: 6e 20 62 65 20 73 74 72 69 6e 67 73 20 6c 69 6b n be strings lik
0a30: 65 20 22 76 65 72 73 69 6f 6e 22 2c 20 22 66 6f e "version", "fo
0a40: 6c 64 65 72 22 2c 20 22 66 69 6c 65 22 2c 20 6f lder", "file", o
0a50: 72 20 22 75 73 65 72 22 2e 0a 3c 2f 70 3e 0a 0a r "user"..</p>..
0a60: 3c 70 3e 0a 54 68 65 20 66 69 72 73 74 20 70 72 <p>.The first pr
0a70: 6f 70 65 72 74 79 20 6f 66 20 61 20 63 6f 6e 74 operty of a cont
0a80: 65 6e 74 20 66 69 6c 65 20 69 73 20 74 68 65 20 ent file is the
0a90: 64 69 67 69 74 61 6c 20 73 69 67 6e 61 74 75 72 digital signatur
0aa0: 65 2e 20 20 54 68 65 0a 6e 61 6d 65 20 6f 66 20 e. The.name of
0ab0: 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 70 72 the signature pr
0ac0: 6f 70 65 72 74 79 20 69 73 20 22 73 69 67 6e 61 operty is "signa
0ad0: 74 75 72 65 22 2e 20 20 54 68 65 72 65 20 61 72 ture". There ar
0ae0: 65 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e e two arguments.
0af0: 0a 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d .The first argum
0b00: 65 6e 74 20 69 73 20 74 68 65 20 53 48 41 32 35 ent is the SHA25
0b10: 36 20 68 61 73 68 20 6f 66 20 74 68 65 20 63 6f 6 hash of the co
0b20: 6e 74 65 6e 74 20 66 69 6c 65 20 74 68 61 74 20 ntent file that
0b30: 64 65 66 69 6e 65 73 0a 74 68 65 20 75 73 65 72 defines.the user
0b40: 20 77 68 6f 20 73 69 67 6e 65 64 20 74 68 69 73 who signed this
0b50: 20 66 69 6c 65 2e 20 20 55 73 65 72 20 72 65 63 file. User rec
0b60: 6f 72 64 73 20 74 68 65 6d 73 65 6c 76 65 73 20 ords themselves
0b70: 61 72 65 20 73 65 6c 66 2d 73 69 67 6e 65 64 0a are self-signed.
0b80: 61 6e 64 20 73 6f 20 74 68 65 20 66 69 72 73 74 and so the first
0b90: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 73 69 6d argument is sim
0ba0: 70 6c 79 20 22 2a 22 20 66 6f 72 20 75 73 65 72 ply "*" for user
0bb0: 20 72 65 63 6f 72 64 73 2e 20 20 54 68 65 20 73 records. The s
0bc0: 65 63 6f 6e 64 0a 61 72 67 75 6d 65 6e 74 20 69 econd.argument i
0bd0: 73 20 74 68 65 20 64 69 67 69 74 61 6c 20 73 69 s the digital si
0be0: 67 6e 61 74 75 72 65 20 6f 66 20 61 6e 20 53 48 gnature of an SH
0bf0: 41 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 A256 hash of the
0c00: 20 65 6e 74 69 72 65 0a 66 69 6c 65 20 28 68 65 entire.file (he
0c10: 61 64 65 72 20 61 6e 64 20 63 6f 6e 74 65 6e 74 ader and content
0c20: 29 20 65 78 63 65 70 74 20 66 6f 72 20 74 68 65 ) except for the
0c30: 20 73 69 67 6e 61 74 75 72 65 20 6c 69 6e 65 20 signature line
0c40: 69 74 73 65 6c 66 2e 0a 3c 2f 70 3e 0a itself..</p>.