Fossil

Check-in [2e42c9cb]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Abandon the HNAME table idea. Instead, continue to use the BLOB.UUID as the primary artifact name and add the ALIAS table for aliased artifact names after a hash algorithm change. Add the optional alias argument to the M-card.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | fossil-2.0
Files: files | file ages | folders
SHA1:2e42c9cb89ac25e6ee503705070e9022a7e49c7d
User & Date: drh 2017-02-27 22:20:49
Context
2017-02-27
22:33
Back out the change to the cluster artifact M-card that added an alias name. The plan is to transmit alias information by new cards in the sync protocol. check-in: a6ee563c user: drh tags: fossil-2.0
22:20
Abandon the HNAME table idea. Instead, continue to use the BLOB.UUID as the primary artifact name and add the ALIAS table for aliased artifact names after a hash algorithm change. Add the optional alias argument to the M-card. check-in: 2e42c9cb user: drh tags: fossil-2.0
18:26
Manifest parser supports various hash sizes. check-in: 80f9b68e user: drh tags: fossil-2.0
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/content.c.

1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
      for(i=0; i<p->nCherrypick; i++){
        nErr +=  check_exists(p->aCherrypick[i].zCPTarget+1, flags, p,
                              "cherry-pick target of", 0);
        nErr +=  check_exists(p->aCherrypick[i].zCPBase, flags, p,
                              "cherry-pick baseline of", 0);
      }
      for(i=0; i<p->nCChild; i++){
        nErr += check_exists(p->azCChild[i], flags, p, "in", 0);
      }
      for(i=0; i<p->nTag; i++){
        nErr += check_exists(p->aTag[i].zUuid, flags, p, "target of", 0);
      }
      manifest_destroy(p);
    }
  }







|







1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
      for(i=0; i<p->nCherrypick; i++){
        nErr +=  check_exists(p->aCherrypick[i].zCPTarget+1, flags, p,
                              "cherry-pick target of", 0);
        nErr +=  check_exists(p->aCherrypick[i].zCPBase, flags, p,
                              "cherry-pick baseline of", 0);
      }
      for(i=0; i<p->nCChild; i++){
        nErr += check_exists(p->aCChild[i].zUuid, flags, p, "in", 0);
      }
      for(i=0; i<p->nTag; i++){
        nErr += check_exists(p->aTag[i].zUuid, flags, p, "target of", 0);
      }
      manifest_destroy(p);
    }
  }

Changes to src/manifest.c.

93
94
95
96
97
98
99
100

101


102
103
104
105
106
107
108
...
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
...
641
642
643
644
645
646
647

648
649
650
651
652




653
654
655
656
657
658
659


660
661
662
663
664
665
666
667
....
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
  char **azParent;      /* Hashes of parents.  One for each P card argument */
  int nCherrypick;      /* Number of entries in aCherrypick[] */
  struct {
    char *zCPTarget;    /* Hash for cherry-picked version w/ +|- prefix */
    char *zCPBase;      /* Hash for cherry-pick baseline. NULL for singletons */
  } *aCherrypick;
  int nCChild;          /* Number of cluster children */
  int nCChildAlloc;     /* Number of closts allocated in azCChild[] */

  char **azCChild;      /* Hashes of referenced objects in a cluster. M cards */


  int nTag;             /* Number of T Cards */
  int nTagAlloc;        /* Slots allocated in aTag[] */
  struct TagType {
    char *zName;           /* Name of the tag */
    char *zUuid;           /* Hash of artifact that the tag is applied to */
    char *zValue;          /* Value if the tag is really a property */
  } *aTag;              /* One for each T card */
................................................................................
** Clear the memory allocated in a manifest object
*/
void manifest_destroy(Manifest *p){
  if( p ){
    blob_reset(&p->content);
    fossil_free(p->aFile);
    fossil_free(p->azParent);
    fossil_free(p->azCChild);
    fossil_free(p->aTag);
    fossil_free(p->aField);
    fossil_free(p->aCherrypick);
    if( p->pBaseline ) manifest_destroy(p->pBaseline);
    memset(p, 0, sizeof(*p));
    fossil_free(p);
  }
................................................................................
      /*
      **    M <hash>
      **
      ** An M-line identifies another artifact by its hash.  M-lines
      ** occur in clusters only.
      */
      case 'M': {

        zUuid = next_token(&x, &sz);
        if( zUuid==0 ) SYNTAX("missing hash on M-card");
        if( hname_validate(zUuid,sz)==HNAME_NONE ){
          SYNTAX("Invalid hash on M-card");
        }




        if( p->nCChild>=p->nCChildAlloc ){
          p->nCChildAlloc = p->nCChildAlloc*2 + 10;
          p->azCChild = fossil_realloc(p->azCChild
                                 , p->nCChildAlloc*sizeof(p->azCChild[0]) );
        }
        i = p->nCChild++;
        p->azCChild[i] = zUuid;


        if( i>0 && fossil_strcmp(p->azCChild[i-1], zUuid)>=0 ){
          SYNTAX("M-card in the wrong order");
        }
        break;
      }

      /*
      **    N <uuid>
................................................................................
  }
  if( p->type==CFTYPE_CLUSTER ){
    static Stmt del1;
    tag_insert("cluster", 1, 0, rid, p->rDate, rid);
    db_static_prepare(&del1, "DELETE FROM unclustered WHERE rid=:rid");
    for(i=0; i<p->nCChild; i++){
      int mid;
      mid = uuid_to_rid(p->azCChild[i], 1);
      if( mid>0 ){
        db_bind_int(&del1, ":rid", mid);
        db_step(&del1);
        db_reset(&del1);
      }
    }
  }







|
>
|
>
>







 







|







 







>





>
>
>
>


|
|


<
>
>
|







 







|







93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
...
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
...
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666

667
668
669
670
671
672
673
674
675
676
....
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
  char **azParent;      /* Hashes of parents.  One for each P card argument */
  int nCherrypick;      /* Number of entries in aCherrypick[] */
  struct {
    char *zCPTarget;    /* Hash for cherry-picked version w/ +|- prefix */
    char *zCPBase;      /* Hash for cherry-pick baseline. NULL for singletons */
  } *aCherrypick;
  int nCChild;          /* Number of cluster children */
  int nCChildAlloc;     /* Number of cluster allocated in aCChild[] */
  struct {
    char *zUuid;        /* Hashes of referenced objects in cluster. M cards */
    char *zAlias;       /* Alias arguments on a cluster */
  } *aCChild;  
  int nTag;             /* Number of T Cards */
  int nTagAlloc;        /* Slots allocated in aTag[] */
  struct TagType {
    char *zName;           /* Name of the tag */
    char *zUuid;           /* Hash of artifact that the tag is applied to */
    char *zValue;          /* Value if the tag is really a property */
  } *aTag;              /* One for each T card */
................................................................................
** Clear the memory allocated in a manifest object
*/
void manifest_destroy(Manifest *p){
  if( p ){
    blob_reset(&p->content);
    fossil_free(p->aFile);
    fossil_free(p->azParent);
    fossil_free(p->aCChild);
    fossil_free(p->aTag);
    fossil_free(p->aField);
    fossil_free(p->aCherrypick);
    if( p->pBaseline ) manifest_destroy(p->pBaseline);
    memset(p, 0, sizeof(*p));
    fossil_free(p);
  }
................................................................................
      /*
      **    M <hash>
      **
      ** An M-line identifies another artifact by its hash.  M-lines
      ** occur in clusters only.
      */
      case 'M': {
        char *zAlias;
        zUuid = next_token(&x, &sz);
        if( zUuid==0 ) SYNTAX("missing hash on M-card");
        if( hname_validate(zUuid,sz)==HNAME_NONE ){
          SYNTAX("Invalid hash on M-card");
        }
        zAlias = next_token(&x, &sz);
        if( zAlias && hname_validate(zAlias,sz)==HNAME_NONE ){
          SYNTAX("Invalid alias hash on M-card");
        }
        if( p->nCChild>=p->nCChildAlloc ){
          p->nCChildAlloc = p->nCChildAlloc*2 + 10;
          p->aCChild = fossil_realloc(p->aCChild
                                 , p->nCChildAlloc*sizeof(p->aCChild[0]) );
        }
        i = p->nCChild++;

        p->aCChild[i].zUuid = zUuid;
        p->aCChild[i].zAlias = zAlias;
        if( i>0 && fossil_strcmp(p->aCChild[i-1].zUuid, zUuid)>=0 ){
          SYNTAX("M-card in the wrong order");
        }
        break;
      }

      /*
      **    N <uuid>
................................................................................
  }
  if( p->type==CFTYPE_CLUSTER ){
    static Stmt del1;
    tag_insert("cluster", 1, 0, rid, p->rDate, rid);
    db_static_prepare(&del1, "DELETE FROM unclustered WHERE rid=:rid");
    for(i=0; i<p->nCChild; i++){
      int mid;
      mid = uuid_to_rid(p->aCChild[i].zUuid, 1);
      if( mid>0 ){
        db_bind_int(&del1, ":rid", mid);
        db_step(&del1);
        db_reset(&del1);
      }
    }
  }

Changes to src/rebuild.c.

76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
...
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
...
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
@    owner TEXT,              -- Owner of this report format (not used)
@    title TEXT UNIQUE,       -- Title of this report
@    mtime INTEGER,           -- Time last modified.  Seconds since 1970
@    cols TEXT,               -- A color-key specification
@    sqlcode TEXT             -- An SQL SELECT statement for this report
@ );
;
static const char zCreateHnameTable[] =
@ -- The hname table provides mappings from artifact hashes (hval) to the
@ -- artifact id (rid).  This table was added in Fossil-2.0.  Prior to
@ -- Fossil-2.0, there was only a single SHA1 hash value for each artifact
@ -- which was stored in the BLOB.UUID field.  With the introduction of
@ -- multiple hash algorithms, the hval to rid mapping went from one-to-one to
@ -- many-to-one and a new table became necessary.
@ --
@ CREATE TABLE hname(
@   hval TEXT,                      -- Hex-encoded hash value
@   htype ANY,                      -- Type of hash.  Preferred hash: 0
@   rid INTEGER REFERENCES blob,    -- Blob that this hash names
@   PRIMARY KEY(hval,htype)
@ ) WITHOUT ROWID;
@ INSERT INTO hname(hval,htype,rid) SELECT uuid,0,rid FROM blob;
@ CREATE INDEX hname_rid ON hname(rid,htype);
;

/*
** Update the schema as necessary
*/
static void rebuild_update_schema(void){
  int rc;
................................................................................
  if( !db_table_has_column("repository", "concealed", "mtime") ){
    db_multi_exec(
      "ALTER TABLE concealed ADD COLUMN mtime INTEGER;"
      "UPDATE concealed SET mtime=now();"
    );
  }

  /* If the hname table is missing, that means we are dealing with an
  ** older Fossil 1.x database.  Create the hname table an populate it
  ** with the SHA1 hash values in the blob.uuid field.
  **
  ** TODO:  After all the rest of the code is updated to use the hname
  ** table instead of the blob.uuid column, also delete the blob.uuid
  ** column.
  */
  if( !db_table_exists("repository", "hname") ){
    db_multi_exec("%s", zCreateHnameTable/*safe-for-%s*/);
  }
}

/*
** Variables used to store state information about an on-going "rebuild"
** or "deconstruct".
*/
................................................................................

    bag_remove(&pending, rid);
    p = manifest_get(rid, CFTYPE_CLUSTER, 0);
    if( p==0 ){
      fossil_fatal("bad cluster: rid=%d", rid);
    }
    for(i=0; i<p->nCChild; i++){
      const char *zUuid = p->azCChild[i];
      int crid = name_to_rid(zUuid);
      if( crid==0 ){
         fossil_warning("cluster (rid=%d) references unknown artifact %s",
                        rid, zUuid);
         continue;
      }
      db_multi_exec("INSERT OR IGNORE INTO xdone VALUES(%d)", crid);







|
|
<
<
<
<
<

|

|



|
<







 







|
<
<
<
<
<
<
<
|
|







 







|







76
77
78
79
80
81
82
83
84





85
86
87
88
89
90
91
92

93
94
95
96
97
98
99
...
166
167
168
169
170
171
172
173







174
175
176
177
178
179
180
181
182
...
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
@    owner TEXT,              -- Owner of this report format (not used)
@    title TEXT UNIQUE,       -- Title of this report
@    mtime INTEGER,           -- Time last modified.  Seconds since 1970
@    cols TEXT,               -- A color-key specification
@    sqlcode TEXT             -- An SQL SELECT statement for this report
@ );
;
static const char zSchemaUpdate3[] =
@ -- Make sure the alias table exists.





@ --
@ CREATE TABLE alias(
@   hval TEXT,                      -- Hex-encoded hash value
@   htype ANY,                      -- Type of hash.
@   rid INTEGER REFERENCES blob,    -- Blob that this hash names
@   PRIMARY KEY(hval,htype)
@ ) WITHOUT ROWID;
@ CREATE INDEX alias_rid ON alias(rid,htype)

;

/*
** Update the schema as necessary
*/
static void rebuild_update_schema(void){
  int rc;
................................................................................
  if( !db_table_has_column("repository", "concealed", "mtime") ){
    db_multi_exec(
      "ALTER TABLE concealed ADD COLUMN mtime INTEGER;"
      "UPDATE concealed SET mtime=now();"
    );
  }

  /* If the alias table is missing, create it. */







  if( !db_table_exists("repository", "alias") ){
    db_multi_exec("%s", zSchemaUpdate3/*safe-for-%s*/);
  }
}

/*
** Variables used to store state information about an on-going "rebuild"
** or "deconstruct".
*/
................................................................................

    bag_remove(&pending, rid);
    p = manifest_get(rid, CFTYPE_CLUSTER, 0);
    if( p==0 ){
      fossil_fatal("bad cluster: rid=%d", rid);
    }
    for(i=0; i<p->nCChild; i++){
      const char *zUuid = p->aCChild[i].zUuid;
      int crid = name_to_rid(zUuid);
      if( crid==0 ){
         fossil_warning("cluster (rid=%d) references unknown artifact %s",
                        rid, zUuid);
         continue;
      }
      db_multi_exec("INSERT OR IGNORE INTO xdone VALUES(%d)", crid);

Changes to src/schema.c.

77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
...
105
106
107
108
109
110
111
112
113
114
115
116


117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
@ -- The blob and delta tables collectively hold the "global state" of
@ -- a Fossil repository.
@ --
@ CREATE TABLE blob(
@   rid INTEGER PRIMARY KEY,        -- Record ID
@   rcvid INTEGER,                  -- Origin of this record
@   size INTEGER,                   -- Size of content. -1 for a phantom.
@   uuid TEXT UNIQUE NOT NULL,      -- SHA1 hash of the content
@   content BLOB,                   -- Compressed content of this record
@   CHECK( length(uuid)==40 AND rid>0 )
@ );
@ CREATE TABLE delta(
@   rid INTEGER PRIMARY KEY,                 -- BLOB that is delta-compressed
@   srcid INTEGER NOT NULL REFERENCES blob   -- Baseline for delta-compression
@ );
................................................................................
@   rcvid INTEGER PRIMARY KEY,      -- Received-From ID
@   uid INTEGER REFERENCES user,    -- User login
@   mtime DATETIME,                 -- Time of receipt.  Julian day.
@   nonce TEXT UNIQUE,              -- Nonce used for login
@   ipaddr TEXT                     -- Remote IP address.  NULL for direct.
@ );
@
@ -- The hname table maps hash values (hval) into artifact IDs (rid).
@ -- Prior to Fossil 2.0 (early 2017) there was only a single SHA1 hash
@ -- value, and so the one-to-one mapping was accomplished using the
@ -- BLOB.UUID column.  Beginning with 2.0, the mapping is many-to-one
@ -- and so a separate table became necessary.


@ --
@ CREATE TABLE hname(
@   hval TEXT,                      -- Hex-encoded hash value
@   htype ANY,                      -- Type of hash.  Preferred hash: 0
@   rid INTEGER REFERENCES blob,    -- Blob that this hash names
@   PRIMARY KEY(hval,htype)
@ ) WITHOUT ROWID;
@ CREATE INDEX hname_rid ON hname(rid,htype)
@
@ -- Information about users
@ --
@ -- The user.pw field can be either cleartext of the password, or
@ -- a SHA1 hash of the password.  If the user.pw field is exactly 40
@ -- characters long we assume it is a SHA1 hash.  Otherwise, it is
@ -- cleartext.  The sha1_shared_secret() routine computes the password







|







 







|
|
|
|
|
>
>

|

|



|







77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
...
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
@ -- The blob and delta tables collectively hold the "global state" of
@ -- a Fossil repository.
@ --
@ CREATE TABLE blob(
@   rid INTEGER PRIMARY KEY,        -- Record ID
@   rcvid INTEGER,                  -- Origin of this record
@   size INTEGER,                   -- Size of content. -1 for a phantom.
@   uuid TEXT UNIQUE NOT NULL,      -- hash of the content
@   content BLOB,                   -- Compressed content of this record
@   CHECK( length(uuid)==40 AND rid>0 )
@ );
@ CREATE TABLE delta(
@   rid INTEGER PRIMARY KEY,                 -- BLOB that is delta-compressed
@   srcid INTEGER NOT NULL REFERENCES blob   -- Baseline for delta-compression
@ );
................................................................................
@   rcvid INTEGER PRIMARY KEY,      -- Received-From ID
@   uid INTEGER REFERENCES user,    -- User login
@   mtime DATETIME,                 -- Time of receipt.  Julian day.
@   nonce TEXT UNIQUE,              -- Nonce used for login
@   ipaddr TEXT                     -- Remote IP address.  NULL for direct.
@ );
@
@ -- The canonical name of each artifact is given by the BLOB.UUID field.
@ -- But artifacts can also have aliases.  Aliases arise, for example, when
@ -- the naming hash algorithm changes, or as a result of trying to provide
@ -- compatibility with a different VCS.
@ --
@ -- Each entry in the ALIAS table provides an alternative name by which an
@ -- artifact can be called.
@ --
@ CREATE TABLE alias(
@   hval TEXT,                      -- Hex-encoded hash value
@   htype ANY,                      -- Type of hash.
@   rid INTEGER REFERENCES blob,    -- Blob that this hash names
@   PRIMARY KEY(hval,htype)
@ ) WITHOUT ROWID;
@ CREATE INDEX alias_rid ON alias(rid,htype)
@
@ -- Information about users
@ --
@ -- The user.pw field can be either cleartext of the password, or
@ -- a SHA1 hash of the password.  If the user.pw field is exactly 40
@ -- characters long we assume it is a SHA1 hash.  Otherwise, it is
@ -- cleartext.  The sha1_shared_secret() routine computes the password

Changes to www/fileformat.wiki.

25
26
27
28
29
30
31
32

33
34
35
36
37









38

39

40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
..
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
...
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
...
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
...
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
...
261
262
263
264
265
266
267
268
269
270
271
272
273


274
275
276
277
278
279
280
281
...
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
different in separate repositories.
The local state is not versioned and is not synchronized
with the global state.
The local state is not composed of artifacts and is not intended to be enduring.
This document is concerned with global state only.  Local state is only
mentioned here in order to distinguish it from global state.

Each artifact in the repository is named by its SHA1 hash.

No prefixes or meta information is added to an artifact before
its hash is computed.  The name of an artifact in the repository
is exactly the same SHA1 hash that is computed by sha1sum
on the file as it exists in your source tree.</p>










Some artifacts have a particular format which gives them special

meaning to fossil.  Fossil recognizes:


<ul>
<li> [#manifest | Manifests] </li>
<li> [#cluster | Clusters] </li>
<li> [#ctrl | Control Artifacts] </li>
<li> [#wikichng | Wiki Pages] </li>
<li> [#tktchng | Ticket Changes] </li>
<li> [#attachment | Attachments] </li>
<li> [#event | TechNotes] </li>
</ul>

These seven artifact types are described in the following sections.

In the current implementation (as of 2009-01-25) the artifacts that
make up a fossil repository are stored as delta- and zlib-compressed
blobs in an <a href="http://www.sqlite.org/">SQLite</a> database.  This
is an implementation detail and might change in a future release.  For
the purpose of this article "file format" means the format of the artifacts,
not how the artifacts are stored on disk.  It is the artifact format that
is intended to be enduring.  The specifics of how artifacts are stored on
disk, though stable, is not intended to live as long as the
................................................................................

Allowed cards in the manifest are as follows:

<blockquote>
<b>B</b> <i>baseline-manifest</i><br>
<b>C</b> <i>checkin-comment</i><br>
<b>D</b> <i>time-and-date-stamp</i><br>
<b>F</b> <i>filename</i> ?<i>SHA1-hash</i>? ?<i>permissions</i>? ?<i>old-name</i>?<br>
<b>N</b> <i>mimetype</i><br>
<b>P</b> <i>SHA1-hash</i>+<br>
<b>Q</b> (<b>+</b>|<b>-</b>)<i>SHA1-hash</i> ?<i>SHA1-hash</i>?<br>
<b>R</b> <i>repository-checksum</i><br>
<b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <b>*</b> ?<i>value</i>?<br>
<b>U</b> <i>user-login</i><br>
<b>Z</b> <i>manifest-checksum</i>
</blockquote>

A manifest may optionally have a single B-card.  The B-card specifies
................................................................................
that is part of the check-in.  There are one, two, three, or four
arguments.  The first argument is the pathname of the file in the
check-in relative to the root of the project file hierarchy.  No ".."
or "." directories are allowed within the filename.  Space characters
are escaped as in C-card comment text.  Backslash characters and
newlines are not allowed within filenames.  The directory separator
character is a forward slash (ASCII 0x2F).  The second argument to the
F-card is the full 40-character lower-case hexadecimal SHA1 hash of
the content artifact.  The second argument is required for baseline
manifests but is optional for delta manifests.  When the second
argument to the F-card is omitted, it means that the file has been
deleted relative to the baseline (files removed in baseline manifests
versions are <em>not</em> added as F-cards). The optional 3rd argument
defines any special access permissions associated with the file.  This
can be defined as "x" to mean that the file is executable or "l"
................................................................................
A manifest has zero or one N-cards.  The N-card specifies the mimetype for the
text in the comment of the C-card.  If the N-card is omitted, a default mimetype
is used.

A manifest has zero or one P-cards.  Most manifests have one P-card.
The P-card has a varying number of arguments that
define other manifests from which the current manifest
is derived.  Each argument is a 40-character lowercase
hexadecimal SHA1 of a predecessor manifest.  All arguments
to the P-card must be unique within that card.
The first argument is the SHA1 of the direct ancestor of the manifest.
Other arguments define manifests with which the first was
merged to yield the current manifest.  Most manifests have
a P-card with a single argument.  The first manifest in the
project has no ancestors and thus has no P-card or (depending
on the Fossil version) an empty P-card (no arguments).

A manifest has zero or more Q-cards.  A Q-card is similar to a P-card
................................................................................
[/artifact/28987096ac | here].

<a name="cluster"></a>
<h2>2.0 Clusters</h2>

A cluster is an artifact that declares the existence of other artifacts.
Clusters are used during repository synchronization to help
reduce network traffic.  As such, clusters are an optimization and
may be removed from a repository without loss or damage to the
underlying project code.

Clusters follow a syntax that is very similar to manifests.
A cluster is a line-oriented text file.  Newline characters
(ASCII 0x0a) separate the artifact into cards.  Each card begins with a single
character "card type".  Zero or more arguments may follow
the card type.  All arguments are separated from each other
and from the card-type character by a single space
................................................................................
The cluster may not contain additional text or data beyond
what is described here.
Unlike manifests, clusters are never PGP signed.

Allowed cards in the cluster are as follows:

<blockquote>
<b>M</b> <i>artifact-id</i><br />
<b>Z</b> <i>checksum</i>
</blockquote>

A cluster contains one or more "M" cards followed by a single "Z"
card.  Each M card has a single argument which is the artifact ID of


another artifact in the repository.  The Z card works exactly like
the Z card of a manifest.  The argument to the Z card is the
lower-case hexadecimal representation of the MD5 checksum of all
prior cards in the cluster.  The Z-card is required.

An example cluster from Fossil can be seen
[/artifact/d03dbdd73a2a8 | here].

................................................................................
<td>&nbsp;</td>
<td align=center><b>1</b></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><b>M</b> <i>uuid</i></td>
<td>&nbsp;</td>
<td align=center><b>1+</b></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>







|
>

|
<
<

>
>
>
>
>
>
>
>
>

>
|
>











|

|







 







|

|
|







 







|







 







|
|

|







 







|
|
|







 







|




|
>
>
|







 







|







25
26
27
28
29
30
31
32
33
34
35


36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
...
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
...
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
...
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
...
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
...
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
...
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
different in separate repositories.
The local state is not versioned and is not synchronized
with the global state.
The local state is not composed of artifacts and is not intended to be enduring.
This document is concerned with global state only.  Local state is only
mentioned here in order to distinguish it from global state.

Each artifact in the repository is named by a hash of the artifact
content.
No prefixes or meta information is added to an artifact before
its hash is computed.



Each repository uses a single hash algorithm to compute artifact names.
The default algorithm is currently SHA3-256, though this might change
in future releases of Fossil.  Historical versions of Fossil used
SHA1.  The hash algorithm for a repository can be changed.  When a hash
algorithm change occurs, a set of aliases are set up (using the
two-argument version of the M-card on cluster artifacts) so that the
older hash values can be mapped into the new hash values for artifacts
that were added to the repository before the hash algorithm change.

Some artifacts have a particular format which gives them special
meaning to Fossil.  The special artifacts are calls "structural
artifacts".  Fossil recognizes the following kinds of structural
artifacts:

<ul>
<li> [#manifest | Manifests] </li>
<li> [#cluster | Clusters] </li>
<li> [#ctrl | Control Artifacts] </li>
<li> [#wikichng | Wiki Pages] </li>
<li> [#tktchng | Ticket Changes] </li>
<li> [#attachment | Attachments] </li>
<li> [#event | TechNotes] </li>
</ul>

These seven structural artifact types are described in the following sections.

In the current implementation (as of 2017-02-27) the artifacts that
make up a fossil repository are stored as delta- and zlib-compressed
blobs in an <a href="http://www.sqlite.org/">SQLite</a> database.  This
is an implementation detail and might change in a future release.  For
the purpose of this article "file format" means the format of the artifacts,
not how the artifacts are stored on disk.  It is the artifact format that
is intended to be enduring.  The specifics of how artifacts are stored on
disk, though stable, is not intended to live as long as the
................................................................................

Allowed cards in the manifest are as follows:

<blockquote>
<b>B</b> <i>baseline-manifest</i><br>
<b>C</b> <i>checkin-comment</i><br>
<b>D</b> <i>time-and-date-stamp</i><br>
<b>F</b> <i>filename</i> ?<i>hash</i>? ?<i>permissions</i>? ?<i>old-name</i>?<br>
<b>N</b> <i>mimetype</i><br>
<b>P</b> <i>artifact-hash</i>+<br>
<b>Q</b> (<b>+</b>|<b>-</b>)<i>artifact-hash</i> ?<i>artifact-hash</i>?<br>
<b>R</b> <i>repository-checksum</i><br>
<b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <b>*</b> ?<i>value</i>?<br>
<b>U</b> <i>user-login</i><br>
<b>Z</b> <i>manifest-checksum</i>
</blockquote>

A manifest may optionally have a single B-card.  The B-card specifies
................................................................................
that is part of the check-in.  There are one, two, three, or four
arguments.  The first argument is the pathname of the file in the
check-in relative to the root of the project file hierarchy.  No ".."
or "." directories are allowed within the filename.  Space characters
are escaped as in C-card comment text.  Backslash characters and
newlines are not allowed within filenames.  The directory separator
character is a forward slash (ASCII 0x2F).  The second argument to the
F-card is the lower-case hexadecimal artifact hash of
the content artifact.  The second argument is required for baseline
manifests but is optional for delta manifests.  When the second
argument to the F-card is omitted, it means that the file has been
deleted relative to the baseline (files removed in baseline manifests
versions are <em>not</em> added as F-cards). The optional 3rd argument
defines any special access permissions associated with the file.  This
can be defined as "x" to mean that the file is executable or "l"
................................................................................
A manifest has zero or one N-cards.  The N-card specifies the mimetype for the
text in the comment of the C-card.  If the N-card is omitted, a default mimetype
is used.

A manifest has zero or one P-cards.  Most manifests have one P-card.
The P-card has a varying number of arguments that
define other manifests from which the current manifest
is derived.  Each argument is a lowercase
hexadecimal artifact hash of a predecessor manifest.  All arguments
to the P-card must be unique within that card.
The first argument is the artifact hash of the direct ancestor of the manifest.
Other arguments define manifests with which the first was
merged to yield the current manifest.  Most manifests have
a P-card with a single argument.  The first manifest in the
project has no ancestors and thus has no P-card or (depending
on the Fossil version) an empty P-card (no arguments).

A manifest has zero or more Q-cards.  A Q-card is similar to a P-card
................................................................................
[/artifact/28987096ac | here].

<a name="cluster"></a>
<h2>2.0 Clusters</h2>

A cluster is an artifact that declares the existence of other artifacts.
Clusters are used during repository synchronization to help
reduce network traffic.  Clusters are also used to record aliases
for artifact names, so that if the artifact hash algorithm changes,
artifacts can still be looked up using the older hash algorithm.

Clusters follow a syntax that is very similar to manifests.
A cluster is a line-oriented text file.  Newline characters
(ASCII 0x0a) separate the artifact into cards.  Each card begins with a single
character "card type".  Zero or more arguments may follow
the card type.  All arguments are separated from each other
and from the card-type character by a single space
................................................................................
The cluster may not contain additional text or data beyond
what is described here.
Unlike manifests, clusters are never PGP signed.

Allowed cards in the cluster are as follows:

<blockquote>
<b>M</b> <i>artifact-id</i> ?<i>alias</i><br />
<b>Z</b> <i>checksum</i>
</blockquote>

A cluster contains one or more "M" cards followed by a single "Z"
card.  Each M card has at least on argument which is the artifact ID of
another artifact in the repository.  If the M card has a second argument,
the second argument is an alias for the artifact name.  
The Z card works exactly like
the Z card of a manifest.  The argument to the Z card is the
lower-case hexadecimal representation of the MD5 checksum of all
prior cards in the cluster.  The Z-card is required.

An example cluster from Fossil can be seen
[/artifact/d03dbdd73a2a8 | here].

................................................................................
<td>&nbsp;</td>
<td align=center><b>1</b></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><b>M</b> <i>uuid</i> ?<i>alias</i>?</td>
<td>&nbsp;</td>
<td align=center><b>1+</b></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>