Fossil

Check-in [904ee40b]
Login

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

Overview
Comment:Change "baseline" to "check-in" in the on-line documentation.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 904ee40b938df48e574959815b2f331bb99acbbb
User & Date: drh 2009-01-23 00:16:26
Context
2009-01-23
01:01
Nomenclature chanage: "bug report" becomes "ticket" check-in: cf9ee7d6 user: drh tags: trunk
00:16
Change "baseline" to "check-in" in the on-line documentation. check-in: 904ee40b user: drh tags: trunk
2009-01-22
14:04
Changes some "Baseline" labels to "Check-in". check-in: e8d3e327 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/db.c.

973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
  db_begin_transaction();
  db_initial_setup(1, 1);
  db_end_transaction(0);
  printf("project-id: %s\n", db_get("project-code", 0));
  printf("server-id:  %s\n", db_get("server-code", 0));
  zPassword = db_text(0, "SELECT pw FROM user WHERE login=%Q", g.zLogin);
  printf("admin-user: %s (initial password is \"%s\")\n", g.zLogin, zPassword);
  printf("baseline:   %s\n", db_text(0, "SELECT uuid FROM blob"));
}

/*
** SQL functions for debugging.
**
** The print() function writes its arguments on stdout, but only
** if the -sqlprint command-line option is turned on.







<







973
974
975
976
977
978
979

980
981
982
983
984
985
986
  db_begin_transaction();
  db_initial_setup(1, 1);
  db_end_transaction(0);
  printf("project-id: %s\n", db_get("project-code", 0));
  printf("server-id:  %s\n", db_get("server-code", 0));
  zPassword = db_text(0, "SELECT pw FROM user WHERE login=%Q", g.zLogin);
  printf("admin-user: %s (initial password is \"%s\")\n", g.zLogin, zPassword);

}

/*
** SQL functions for debugging.
**
** The print() function writes its arguments on stdout, but only
** if the -sqlprint command-line option is turned on.

Changes to www/bugtheory.wiki.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<h1>Bug-Tracking In <a href="index.wiki">Fossil</a></h1>

A bug-report in fossil is called a "ticket".  Tickets are tracked
separately from code check-ins (baselines).

Some other distributed bug-tracking systems store tickets as files within
the source tree and thereby leverage the syncing and merging capabilities
of the versioning system to sync and merge tickets.  This approach is
rejected in fossil for three reasons:

  1.  Check-ins (a.k.a. "baselines") in fossil are immutable.  So if
      tickets were part of the check-in, then there would be no way to add
      new tickets to a check-in as new bugs are discovered.

  2.  Any project of reasonable size and complexity will generate thousands
      and thousands of tickets, and we do not want all those ticket files
      cluttering the source tree.




|






|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<h1>Bug-Tracking In <a href="index.wiki">Fossil</a></h1>

A bug-report in fossil is called a "ticket".  Tickets are tracked
separately from code check-ins.

Some other distributed bug-tracking systems store tickets as files within
the source tree and thereby leverage the syncing and merging capabilities
of the versioning system to sync and merge tickets.  This approach is
rejected in fossil for three reasons:

  1.  Check-ins in fossil are immutable.  So if
      tickets were part of the check-in, then there would be no way to add
      new tickets to a check-in as new bugs are discovered.

  2.  Any project of reasonable size and complexity will generate thousands
      and thousands of tickets, and we do not want all those ticket files
      cluttering the source tree.

Changes to www/cmd_checkout.wiki.

30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
<code>update</code>, on the other hand, <em>merges</em> edits into the
version you choose (if you choose one; you can default the version.)

Since a version is required, and <b>fossil</b>'s artifact IDs are
fairly long, there are two good ways to refer to the version.  You can
use a unique proper prefix of the version (six or eight characters is
more than enough in most cases) <em>or</em> you can [./cmd_tag.wiki |
tag] your baselines and use the tags for checkouts, reverting,
branching (tags are the best way to branch) and so forth.  Both
methods work throughout fossil.

See also [./cmd_tag.wiki | fossil tag],
[./cmd_revert.wiki | fossil revert],
[./cmd_update.wiki | fossil update],
[./cmd_push.wiki | fossil push],
[./cmd_pull.wiki | fossil pull],
[./cmd_clone.wiki | fossil clone],
[./cmd_open.wiki | fossil open],
[./cmd_close.wiki | fossil close],
[./cmd_new.wiki | fossil new],
[./reference.wiki | Reference]







|













30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
<code>update</code>, on the other hand, <em>merges</em> edits into the
version you choose (if you choose one; you can default the version.)

Since a version is required, and <b>fossil</b>'s artifact IDs are
fairly long, there are two good ways to refer to the version.  You can
use a unique proper prefix of the version (six or eight characters is
more than enough in most cases) <em>or</em> you can [./cmd_tag.wiki |
tag] your check-ins and use the tags for checkouts, reverting,
branching (tags are the best way to branch) and so forth.  Both
methods work throughout fossil.

See also [./cmd_tag.wiki | fossil tag],
[./cmd_revert.wiki | fossil revert],
[./cmd_update.wiki | fossil update],
[./cmd_push.wiki | fossil push],
[./cmd_pull.wiki | fossil pull],
[./cmd_clone.wiki | fossil clone],
[./cmd_open.wiki | fossil open],
[./cmd_close.wiki | fossil close],
[./cmd_new.wiki | fossil new],
[./reference.wiki | Reference]

Changes to www/concepts.wiki.

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
...
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
...
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
...
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
...
429
430
431
432
433
434
435
436
437
438
439
440
441

<p>A software project normally consists of a "source tree".
A source tree is a hierarchy of files that are used to generate
the end product.  The source tree changes over time as the
software grows and expands and as features are added and bugs
are fixed.  A snapshot of the source tree at any point in time
is called a "version" or "revision" or a "baseline" of the product.
In fossil, we use the name "baseline".</p>

<p>A "repository" is a database that contains copies of all historical
versions or baselines for a project.  Baselines are normally stored in the
repository in a highly space-efficient compressed format (delta encoding).
But that is an implementation detail that you the user need not worry over.
Think of the repository as a safe place where all your old baselines are
securely stored away and available for retrieval whenever you need
them.</p>

<p>A repository in fossil is a single file on your disk.  This file
might be rather large (dozens or hundreds of megabytes for a large
or long running project) but it is nevertheless just a file.  You
can move it around, rename it, write it out to a memory stick, or
................................................................................
<h3>2.2 Manifests</h3>

<p>At the root of a source tree is a special file called the
"manifest".  The manifest is a listing of all other files in
that source tree.  The manifest contains the (complete) artifact ID 
of the file and the name of the file as it appears on disk,
and thus serves as a mapping from artifact ID to disk name.  The artifact ID
of the manifest is the identifier for the entire baseline.  When
you look at a "timeline" of changes in fossil, the ID associated
with each check-in or commit is really just the artifact ID of the
manifest for that baseline.</p>

<p>Fossil automatically generates a manifest whenever you "commit" 
a new baseline.  So this is not something that you, the developer,
need to worry with.  The format of a manifest is intentionally
designed to be simple to parse, so that if
you want to read and interpret a manifest, either by hand or
with a script, that is easy to do.  But you will probably never
need to do so.</p>

<p>In addition to identifying all files in the baseline, a
manifest also contains a check-in comment, the date and time
when the baseline was established, who created the baseline,
and links to other baselines from which the current baseline
is derived.  There is also a couple of checksums used to verify
the integrity of the baseline.  And the whole manifest might
be PGP clearsigned.</p>

<h3>2.3 Key concepts</h3>

<ul>
<li>A <b>baseline</b> is a set of files arranged
    in a hierarchy.</li>
<li>A <b>repository</b> keeps a record of historical baselines.</li>
<li>Repositories share their changes using <b>push</b>, <b>pull</b>,
    <b>sync</b>, and <b>clone</b>.</li>
<li>A particular version of a particular file is an <b>artifact</b>
    that is identified by an <b>artifact ID</b>.</li>
<li>Artifacts tracked by fossil are inherently immutable.</li>
<li>Fossil automatically generates a <b>manifest</b> file that identifies
    every artifact in a baseline.</li>
<li>The artifact ID of the manifest is the identifier of the baseline.</li>
</ul>

<h2>3.0 Fossil - The Program</h2>

<p>Fossil is software.  The implementation of fossil is in the form
of a single executable named "fossil".  To install fossil on your system,
all you have to do is obtain a copy of this one executable file (either
................................................................................
to where you want the root of the source tree to be, then issuing
the <b>open</b> command with the name of the repository file as its
argument.
</p></li>

<li><p>
The <b>open</b> command in the previous step populates your local source
tree with a copy of the latest baseline.  Usually this is what you want.
In the rare cases where it is not, use the <b>update</b> command to
switch to a new baseline.  Use the <b>timeline</b> or <b>leaves</b> commands
to identify alternative baselines to switch to.
</p></li>

<li><p>
Edit the code.  Add new files to the source tree using the <b>add</b>
command.  Omit files from future baselines using the <b>rm</b> command.
(Even when you remove files from future baselines, those files continue
to exist in historical baselines.)  Test your changes.
</p></li>

<li><p>
Create a new baseline using the <b>commit</b> command.  You will be prompted
for a check-in comment and also for your GPG key if you have GPG installed.
The commit copies the edits you have made in your local source
tree into your local repository.  After your commit completes, fossil will
automatically <b>push</b> your changes back to the server
you cloned from or whatever server you most recently synced with.
</p></li>

................................................................................
to where you want the root of the source tree to be, then issuing
the <b>open</b> command with the name of the repository file as its
argument.
</p></li>

<li><p>
The <b>open</b> command in the previous step populates your local source
tree with a copy of the latest baseline.  Usually this is what you want.
In the rare cases where it is not, use the <b>update</b> command to
switch to a new baseline.  Use the <b>timeline</b> or <b>leaves</b> commands
to identify alternative baselines to switch to.
</p></li>

<li><p>
Edit the code.  Add new files to the source tree using the <b>add</b>
command.  Omit files from future baselines using the <b>rm</b> command.
(Even when you remove files from future baselines, those files continue
to exist in historical baselines.)  Test your changes.
</p></li>

<li><p>
Create a new baseline using the <b>commit</b> command.  You will be prompted
for a check-in comment and also for your GPG key if you have GPG installed.
The commit copies the edits you have made in your local source
tree into your local repository.
</p></li>

<li><p>Use the <b>push</b> command to push your changes out to a server
where your co-workers can access them.
................................................................................
<ul>
<li>The <b>fossil</b> program is a self-contained stand-alone executable.
    Just put it somewhere on your PATH to install it.</li>
<li>Use the <b>clone</b> or <b>new</b> commands to create a new repository.</li>
<li>Use the <b>open</b> command to create a new source tree.</li>
<li>Use the <b>add</b> and <b>rm</b> or <b>delete</b> commands to add and
    remove files from the local source tree.</li>
<li>Use the <b>commit</b> command to create a new baseline.</li>
<li>Use the <b>update</b> command to merge in changes from others.</li>
<li>The <b>push</b> and <b>pull</b> commands can be used to share changes
    manually, but these things happen automatically in the default
    autosync mode.</li>
</ul>







|


|


|







 







|


|


|






|

|
|

|





|

|






|
|







 







|

|
|




|
|
|



|







 







|

|
|




|
|
|



|







 







|





23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
...
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
...
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
...
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
...
429
430
431
432
433
434
435
436
437
438
439
440
441

<p>A software project normally consists of a "source tree".
A source tree is a hierarchy of files that are used to generate
the end product.  The source tree changes over time as the
software grows and expands and as features are added and bugs
are fixed.  A snapshot of the source tree at any point in time
is called a "version" or "revision" or a "baseline" of the product.
In fossil, we use the name "check-in".</p>

<p>A "repository" is a database that contains copies of all historical
check-ins for a project.  Check-ins are normally stored in the
repository in a highly space-efficient compressed format (delta encoding).
But that is an implementation detail that you the user need not worry over.
Think of the repository as a safe place where all your old check-ins are
securely stored away and available for retrieval whenever you need
them.</p>

<p>A repository in fossil is a single file on your disk.  This file
might be rather large (dozens or hundreds of megabytes for a large
or long running project) but it is nevertheless just a file.  You
can move it around, rename it, write it out to a memory stick, or
................................................................................
<h3>2.2 Manifests</h3>

<p>At the root of a source tree is a special file called the
"manifest".  The manifest is a listing of all other files in
that source tree.  The manifest contains the (complete) artifact ID 
of the file and the name of the file as it appears on disk,
and thus serves as a mapping from artifact ID to disk name.  The artifact ID
of the manifest is the identifier for the entire check-in.  When
you look at a "timeline" of changes in fossil, the ID associated
with each check-in or commit is really just the artifact ID of the
manifest for that check-in.</p>

<p>Fossil automatically generates a manifest whenever you "commit" 
a new check-in.  So this is not something that you, the developer,
need to worry with.  The format of a manifest is intentionally
designed to be simple to parse, so that if
you want to read and interpret a manifest, either by hand or
with a script, that is easy to do.  But you will probably never
need to do so.</p>

<p>In addition to identifying all files in the check-in, a
manifest also contains a check-in comment, the date and time
when the check-in was established, who created the check-in,
and links to other check-ins from which the current check-in
is derived.  There is also a couple of checksums used to verify
the integrity of the check-in.  And the whole manifest might
be PGP clearsigned.</p>

<h3>2.3 Key concepts</h3>

<ul>
<li>A <b>check-in</b> is a set of files arranged
    in a hierarchy.</li>
<li>A <b>repository</b> keeps a record of historical check-ins.</li>
<li>Repositories share their changes using <b>push</b>, <b>pull</b>,
    <b>sync</b>, and <b>clone</b>.</li>
<li>A particular version of a particular file is an <b>artifact</b>
    that is identified by an <b>artifact ID</b>.</li>
<li>Artifacts tracked by fossil are inherently immutable.</li>
<li>Fossil automatically generates a <b>manifest</b> file that identifies
    every artifact in a check-in.</li>
<li>The artifact ID of the manifest is the identifier of the check-in.</li>
</ul>

<h2>3.0 Fossil - The Program</h2>

<p>Fossil is software.  The implementation of fossil is in the form
of a single executable named "fossil".  To install fossil on your system,
all you have to do is obtain a copy of this one executable file (either
................................................................................
to where you want the root of the source tree to be, then issuing
the <b>open</b> command with the name of the repository file as its
argument.
</p></li>

<li><p>
The <b>open</b> command in the previous step populates your local source
tree with a copy of the latest check-in.  Usually this is what you want.
In the rare cases where it is not, use the <b>update</b> command to
switch to a new check-in.  Use the <b>timeline</b> or <b>leaves</b> commands
to identify alternative check-ins to switch to.
</p></li>

<li><p>
Edit the code.  Add new files to the source tree using the <b>add</b>
command.  Omit files from future check-ins using the <b>rm</b> command.
(Even when you remove files from future check-ins, those files continue
to exist in historical check-ins.)  Test your changes.
</p></li>

<li><p>
Create a new check-in using the <b>commit</b> command.  You will be prompted
for a check-in comment and also for your GPG key if you have GPG installed.
The commit copies the edits you have made in your local source
tree into your local repository.  After your commit completes, fossil will
automatically <b>push</b> your changes back to the server
you cloned from or whatever server you most recently synced with.
</p></li>

................................................................................
to where you want the root of the source tree to be, then issuing
the <b>open</b> command with the name of the repository file as its
argument.
</p></li>

<li><p>
The <b>open</b> command in the previous step populates your local source
tree with a copy of the latest check-in.  Usually this is what you want.
In the rare cases where it is not, use the <b>update</b> command to
switch to a new check-in.  Use the <b>timeline</b> or <b>leaves</b> commands
to identify alternative check-ins to switch to.
</p></li>

<li><p>
Edit the code.  Add new files to the source tree using the <b>add</b>
command.  Omit files from future check-ins using the <b>rm</b> command.
(Even when you remove files from future check-ins, those files continue
to exist in historical check-ins.)  Test your changes.
</p></li>

<li><p>
Create a new check-in using the <b>commit</b> command.  You will be prompted
for a check-in comment and also for your GPG key if you have GPG installed.
The commit copies the edits you have made in your local source
tree into your local repository.
</p></li>

<li><p>Use the <b>push</b> command to push your changes out to a server
where your co-workers can access them.
................................................................................
<ul>
<li>The <b>fossil</b> program is a self-contained stand-alone executable.
    Just put it somewhere on your PATH to install it.</li>
<li>Use the <b>clone</b> or <b>new</b> commands to create a new repository.</li>
<li>Use the <b>open</b> command to create a new source tree.</li>
<li>Use the <b>add</b> and <b>rm</b> or <b>delete</b> commands to add and
    remove files from the local source tree.</li>
<li>Use the <b>commit</b> command to create a new check-in.</li>
<li>Use the <b>update</b> command to merge in changes from others.</li>
<li>The <b>push</b> and <b>pull</b> commands can be used to share changes
    manually, but these things happen automatically in the default
    autosync mode.</li>
</ul>

Changes to www/embeddeddoc.wiki.

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
114
115
For example, the <i>&lt;baseurl&gt;</i> for the fossil project itself is
either <b>http://www.fossil-scm.org/fossil</b> or
<b>http://www.hwaci.com/cgi-bin/fossil</b>.
If you launch the web server using the "<b>fossil server</b>" command line,
then the <i>&lt;baseurl&gt;</i> is usually
<b>http://localhost:8080/</b>.

The <i>&lt;version&gt;</i> is any unique prefix of the baseline ID for 
the baseline containing the documentation you want to access.
Or <i>&lt;version&gt;</i> can be one of the keywords "<b>tip</b>" or
"<b>ckout</b>".  The "<b>tip</b>" keyword means to use the most recently
checked-in baseline.  This is useful if you want to see the very latest
version of the documentation.  The "<b>ckout</b>" keywords means to
pull the documentation file from the local source tree on disk, not
from the any versioned baseline.  The "<b>ckout</b>" keyword normally
only works when you start your server using the "<b>fossil server</b>"
or "<b>fossil ui</b>"
command line and is indented to show what the documentation you are currently
editing looks like before you check it in.

Finally, the <i>&lt;filename&gt;</i> element of the URL is the full
pathname of the documentation file starting from the root of the source
................................................................................
repository: /fossil/fossil.fossil
</pre></blockquote>

This is one of three ways to set up a 
<a href="quickstart.wiki#serversetup">fossil web server</a>.

The "<b>/tip/</b>" part of the URL tells fossil to use
the documentation files from the baseline that was checked in most
recently.  This file is stored in the fossil source tree under
the name "<b>www/embeddeddoc.wiki</b>" and so that name forms the
last part of the URL.

As I sit writing this documentation file, I am testing my work by
running the "<b>fossil server</b>" command line and viewing
<b>http://localhost:8080/doc/ckout/www/embeddeddoc.wiki</b> in
Firefox.  I am doing this even though I have not yet checked in
the "<b>www/embeddeddoc.wiki</b>" file for the first time.  Using
the special "<b>ckout</b>" version identifier on the "<b>/doc</b>" page
it is easy to make multiple changes to multiple files and see how they all
look together before committing anything to the repository.







|
|


|


|







 







|












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
114
115
For example, the <i>&lt;baseurl&gt;</i> for the fossil project itself is
either <b>http://www.fossil-scm.org/fossil</b> or
<b>http://www.hwaci.com/cgi-bin/fossil</b>.
If you launch the web server using the "<b>fossil server</b>" command line,
then the <i>&lt;baseurl&gt;</i> is usually
<b>http://localhost:8080/</b>.

The <i>&lt;version&gt;</i> is any unique prefix of the check-in ID for 
the check-in containing the documentation you want to access.
Or <i>&lt;version&gt;</i> can be one of the keywords "<b>tip</b>" or
"<b>ckout</b>".  The "<b>tip</b>" keyword means to use the most recently
checked-in.  This is useful if you want to see the very latest
version of the documentation.  The "<b>ckout</b>" keywords means to
pull the documentation file from the local source tree on disk, not
from the any check-in.  The "<b>ckout</b>" keyword normally
only works when you start your server using the "<b>fossil server</b>"
or "<b>fossil ui</b>"
command line and is indented to show what the documentation you are currently
editing looks like before you check it in.

Finally, the <i>&lt;filename&gt;</i> element of the URL is the full
pathname of the documentation file starting from the root of the source
................................................................................
repository: /fossil/fossil.fossil
</pre></blockquote>

This is one of three ways to set up a 
<a href="quickstart.wiki#serversetup">fossil web server</a>.

The "<b>/tip/</b>" part of the URL tells fossil to use
the documentation files from the check-in that was checked in most
recently.  This file is stored in the fossil source tree under
the name "<b>www/embeddeddoc.wiki</b>" and so that name forms the
last part of the URL.

As I sit writing this documentation file, I am testing my work by
running the "<b>fossil server</b>" command line and viewing
<b>http://localhost:8080/doc/ckout/www/embeddeddoc.wiki</b> in
Firefox.  I am doing this even though I have not yet checked in
the "<b>www/embeddeddoc.wiki</b>" file for the first time.  Using
the special "<b>ckout</b>" version identifier on the "<b>/doc</b>" page
it is easy to make multiple changes to multiple files and see how they all
look together before committing anything to the repository.

Changes to www/fileformat.wiki.

61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
...
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
...
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
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 have as long a lifespan as the
artifact format.</p>

<h2>1.0 The Manifest</h2>

<p>A manifest defines a baseline or version of the project
source tree.  The manifest contains a list of artifacts for
each file in the project and the corresponding filenames, as
well as information such as parent baselines, the name of the
programmer who created the baseline, the date and time when
the baseline was created, and any check-in comments associated
with the baseline.</p>

<p>
Any artifact in the repository that follows the syntactic rules
of a manifest is a manifest.  Note that a manifest can
be both a real manifest and also a content file, though this
is rare.
</p>
................................................................................

<blockquote>
<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>
</blockquote>

<p>
A manifest has zero or more F-cards.  Each F-card defines a file
(other than the manifest itself) which is part of the baseline that
the manifest defines.  There are two, three, or three arguments.
The first argument
is the pathname of the file in the baseline 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 optional 3rd argument defines any special access 
permissions associated with the file.  The only special code currently
defined is "x" which means that the file is executable.  All files are
always readable and writable.  This can be expressed by "w" permission
if desired but is optional.
The optional 4th argument is the name of the same file as it existed in
the parent baseline.  If the name of the file is unchanged from its
parent, then the 4th argument is omitted.
</p>

<p>
A manifest has zero or more N-cards.  Each N card records a name changes
to one of the files in the manifest.  The first argument to the N code is
the name of the file in the parent baseline.  The second argument is the
name of the file in the baseline defined by the manifest.
</p>

<p>
A manifest has zero or one P-cards.  Most manifests have one P-card.
The P-card has a varying number of arguments that
defines other manifests from which the current manifest
is derived.  Each argument is an 40-character lowercase 
................................................................................
a P-card with a single argument.  The first manifest in the
project has no ancestors and thus has no P-card.
</p>

<p>
A manifest may optionally have a single R-card.  The R-card has
a single argument which is the MD5 checksum of all files in 
the baseline except the manifest itself.  The checksum is expressed
as 32-characters of lowercase hexadecimal.   The checksum is
computed as follows:  For each file in the baseline (except for
the manifest itself) in strict sorted lexicographical order, 
take the pathname of the file relative to the root of the
repository, append a single space (ASCII 0x20), the
size of the file in ASCII decimal, a single newline
character (ASCII 0x0A), and the complete text of the file.
Compute the MD5 checksum of the the result.
</p>
................................................................................
without a value is a boolean.</p>

<p>When two or more tags with the same name are applied to the
same artifact, the tag with the latest (most recent) date is
used.</p>

<p>Some tags have special meaning.  The "comment" tag when applied
to a baseline will override the check-in comment of that baseline
for display purposes.</p>

<a name="wikichng"></a>
<h2>4.0 Wiki Pages</h2>

<p>A wiki page is an artifact with a format similar to manifests,
clusters, and control artifacts.  The artifact is divided into







|


|
|
|
|







 







|


|












|






|
|







 







|

|







 







|







61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
...
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
...
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
...
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
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 have as long a lifespan as the
artifact format.</p>

<h2>1.0 The Manifest</h2>

<p>A manifest defines a check-in or version of the project
source tree.  The manifest contains a list of artifacts for
each file in the project and the corresponding filenames, as
well as information such as parent check-ins, the name of the
programmer who created the check-in, the date and time when
the check-in was created, and any check-in comments associated
with the check-in.</p>

<p>
Any artifact in the repository that follows the syntactic rules
of a manifest is a manifest.  Note that a manifest can
be both a real manifest and also a content file, though this
is rare.
</p>
................................................................................

<blockquote>
<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>
</blockquote>

<p>
A manifest has zero or more F-cards.  Each F-card defines a file
(other than the manifest itself) which is part of the check-in that
the manifest defines.  There are two, three, or three 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 optional 3rd argument defines any special access 
permissions associated with the file.  The only special code currently
defined is "x" which means that the file is executable.  All files are
always readable and writable.  This can be expressed by "w" permission
if desired but is optional.
The optional 4th argument is the name of the same file as it existed in
the parent check-in.  If the name of the file is unchanged from its
parent, then the 4th argument is omitted.
</p>

<p>
A manifest has zero or more N-cards.  Each N card records a name changes
to one of the files in the manifest.  The first argument to the N code is
the name of the file in the parent check-in.  The second argument is the
name of the file in the check-in defined by the manifest.
</p>

<p>
A manifest has zero or one P-cards.  Most manifests have one P-card.
The P-card has a varying number of arguments that
defines other manifests from which the current manifest
is derived.  Each argument is an 40-character lowercase 
................................................................................
a P-card with a single argument.  The first manifest in the
project has no ancestors and thus has no P-card.
</p>

<p>
A manifest may optionally have a single R-card.  The R-card has
a single argument which is the MD5 checksum of all files in 
the check-in except the manifest itself.  The checksum is expressed
as 32-characters of lowercase hexadecimal.   The checksum is
computed as follows:  For each file in the check-in (except for
the manifest itself) in strict sorted lexicographical order, 
take the pathname of the file relative to the root of the
repository, append a single space (ASCII 0x20), the
size of the file in ASCII decimal, a single newline
character (ASCII 0x0A), and the complete text of the file.
Compute the MD5 checksum of the the result.
</p>
................................................................................
without a value is a boolean.</p>

<p>When two or more tags with the same name are applied to the
same artifact, the tag with the latest (most recent) date is
used.</p>

<p>Some tags have special meaning.  The "comment" tag when applied
to a check-in will override the check-in comment of that check-in
for display purposes.</p>

<a name="wikichng"></a>
<h2>4.0 Wiki Pages</h2>

<p>A wiki page is an artifact with a format similar to manifests,
clusters, and control artifacts.  The artifact is divided into

Changes to www/newrepo.wiki.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

The first thing we need to do is create a fossil repository file:

<verbatim>
stephan@ludo:~/fossil$ fossil new demo.fossil
project-id: 9d8ccff5671796ee04e60af6932aa7788f0a990a
server-id:  145fe7d71e3b513ac37ac283979d73e12ca04bfe
admin-user: stephan (no password set yet!)
baseline:   84e81a150535f031722f815d59c0c5e96ab7f122
</verbatim>

The numbers it spits out are unimportant (they are version
numbers).

Now we have an empty repository file named <tt>demo.fossil</tt>.
There is nothing magical about the extension <tt>.fossil</tt> - it's







|
<







8
9
10
11
12
13
14
15

16
17
18
19
20
21
22

The first thing we need to do is create a fossil repository file:

<verbatim>
stephan@ludo:~/fossil$ fossil new demo.fossil
project-id: 9d8ccff5671796ee04e60af6932aa7788f0a990a
server-id:  145fe7d71e3b513ac37ac283979d73e12ca04bfe
admin-user: stephan (initial password is ******)

</verbatim>

The numbers it spits out are unimportant (they are version
numbers).

Now we have an empty repository file named <tt>demo.fossil</tt>.
There is nothing magical about the extension <tt>.fossil</tt> - it's

Changes to www/pop.wiki.

58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
artifacts.</p></li>

<li><p>Two repositories for the same project can synchronize
their global states simply by sharing artifacts.  The local
state of repositories is not normally synchronized or
shared.</p></li>

<li><p>Every baseline has a special file at the top-level
named "manifest" which is an index of all other files in
that baseline.  The manifest is automatically created and
maintained by the system.</p></li>

<li><p>The <a href="fileformat.wiki">file formats</a>
used by Fossil are all very simple so that with access
to the original content files, one can easily reconstruct
the content of a baseline without the need for any
special tools or software.</p></li>







|

|





|

58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
artifacts.</p></li>

<li><p>Two repositories for the same project can synchronize
their global states simply by sharing artifacts.  The local
state of repositories is not normally synchronized or
shared.</p></li>

<li><p>Every check-in has a special file at the top-level
named "manifest" which is an index of all other files in
that check-in.  The manifest is automatically created and
maintained by the system.</p></li>

<li><p>The <a href="fileformat.wiki">file formats</a>
used by Fossil are all very simple so that with access
to the original content files, one can easily reconstruct
the content of a check-in without the need for any
special tools or software.</p></li>

Changes to www/quickstart.wiki.

161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
    local tree, use <b>update</b>:</p>

    <blockquote>
    <b>fossil update</b> <i>AID</i>
    </blockquote>

    <p>The <i>AID</i> is some unique abbreviation to the 40-character
    artifact identifier (AID) for a particular baseline.  If you omit
    the <i>AID</i> fossil moves you to the
    leaf version of the branch your are currently on.  If your branch
    has multiple leaves, you get an error - you'll have to specify the
    leaf you want using a <i>AID</i> argument.</p>

</blockquote><h2>Branching And Merging</h2><blockquote>








|







161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
    local tree, use <b>update</b>:</p>

    <blockquote>
    <b>fossil update</b> <i>AID</i>
    </blockquote>

    <p>The <i>AID</i> is some unique abbreviation to the 40-character
    artifact identifier (AID) for a particular check-in.  If you omit
    the <i>AID</i> fossil moves you to the
    leaf version of the branch your are currently on.  If your branch
    has multiple leaves, you get an error - you'll have to specify the
    leaf you want using a <i>AID</i> argument.</p>

</blockquote><h2>Branching And Merging</h2><blockquote>

Changes to www/reference.wiki.

251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
...
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
...
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
    remaining 38 characters.

<hr><a href="#tof">&#710;</a>
    <a name="rm">Usage: </a><a href="cmd_rm.wiki">fossil rm</a> FILE...    or: fossil del FILE...
    Remove one or more files from the tree.

<hr><a href="#tof">&#710;</a>
    <a name="descendants">Usage: </a><a href="cmd_descendants.wiki">fossil descendants</a> ?BASELINE-ID?
    Find all leaf descendants of the baseline specified or if the argument
    is omitted, of the baseline currently checked out.

<hr><a href="#tof">&#710;</a>
    <a name="diff">Usage: </a><a href="cmd_diff.wiki">fossil diff</a>|gdiff ?-i? ?-r REVISION? FILE...
    Show the difference between the current version of a file (as it
    exists on disk) and that same file as it was checked out.

    diff will show a textual diff while gdiff will attempt to run a
................................................................................
    associated with the named file(s) but otherwise leave the update
    or merge undone.

    A single level of undo/redo is supported.  The undo/redo stack
    is cleared by the commit and checkout commands.

<hr><a href="#tof">&#710;</a>
    <a name="revert">Usage: </a><a href="cmd_revert.wiki">fossil revert</a> ?--yes? ?-r REVISION? FILE
    Revert to the current repository version of FILE, or to
    the version associated with baseline REVISION if the -r flag
    appears.  This command will confirm your operation unless the
    file is missing or the --yes option is used.

<hr><a href="#tof">&#710;</a>
    <a name="server">Usage: </a><a href="cmd_server.wiki">fossil server</a> ?-P|--port TCPPORT? ?REPOSITORY?    Or: fossil ui ?-P|--port TCPPORT? ?REPOSITORY?

    Open a socket and begin listening and responding to HTTP requests on
................................................................................
    the equivalent of running both "push" and "pull" at the same time.
    See the "pull" command for additional information.

<hr><a href="#tof">&#710;</a>
    <a name="tag">Usage: </a><a href="cmd_tag.wiki">fossil tag</a> SUBCOMMAND ...
    Run various subcommands to control tags and properties

    fossil tag add ?--raw? TAGNAME BASELINE ?VALUE?

    Add a new tag or property to BASELINE. The tag will
    be usable instead of a BASELINE in commands such as
    update and merge.

    fossil tag branch ?--raw? ?--nofork? TAGNAME BASELINE ?VALUE?

    A fork will be created so that the new checkin
    is a sibling of BASELINE and identical to it except
    for a generated comment. Then the new tag will
    be added to the new checkin and propagated to
    all direct children.  Additionally all symbolic
    tags of that checkin inherited from BASELINE will
    be cancelled.

    However, if the option --nofork is given, no
    fork will be created and the tag/property will be
    added to BASELINE directly. No tags will be canceled.

    fossil tag cancel ?--raw? TAGNAME BASELINE

    Remove the tag TAGNAME from BASELINE, and also remove
    the propagation of the tag to any descendants.

    fossil tag find ?--raw? TAGNAME

    List all baselines that use TAGNAME

    fossil tag list ?--raw? ?BASELINE?

    List all tags, or if BASELINE is supplied, list
    all tags and their values for BASELINE.

    The option --raw allows the manipulation of all types of
    tags used for various internal purposes in fossil. You
    should not use this option to make changes unless you are
    sure what you are doing.

    If you need to use a tagname that might be confused with
    a hexadecimal baseline or artifact ID, you can explicitly
    disambiguate it by prefixing it with "tag:". For instance:

    fossil update decaf

    will be taken as an artifact or baseline ID and fossil will
    probably complain that no such revision was found. However

    fossil update tag:decaf

    will assume that "decaf" is a tag/branch name.

<hr><a href="#tof">&#710;</a>
    <a name="timeline">Usage: </a><a href="cmd_timeline.wiki">fossil timeline</a> ?WHEN? ?BASELINE|DATETIME? ?-n|--count N?
    Print a summary of activity going backwards in date and time
    specified or from the current date and time if no arguments
    are given.  Show as many as N (default 20) check-ins.  The
    WHEN argument can be any unique abbreviation of one of these
    keywords:

    before
    after
    descendants | children
    ancestors | parents

    The BASELINE can be any unique prefix of 4 characters or more.
    The DATETIME should be in the ISO8601 format.  For
    examples: "2007-08-18 07:21:21".  You can also say "current"
    for the current version or "now" for the current time.

<hr><a href="#tof">&#710;</a>
    <a name="undo">Usage: </a><a href="cmd_undo.wiki">fossil undo</a> ?FILENAME...?
    Undo the most recent update or merge operation.  If FILENAME is







|
|
|







 







|

|







 







|

|
|


|


|



|




|

|

|




|

|

|
|







|




|







|











|







251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
...
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
...
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
    remaining 38 characters.

<hr><a href="#tof">&#710;</a>
    <a name="rm">Usage: </a><a href="cmd_rm.wiki">fossil rm</a> FILE...    or: fossil del FILE...
    Remove one or more files from the tree.

<hr><a href="#tof">&#710;</a>
    <a name="descendants">Usage: </a><a href="cmd_descendants.wiki">fossil descendants</a> ?CHECKIN-ID?
    Find all leaf descendants of the check-in specified or if the argument
    is omitted, of the check-in currently checked out.

<hr><a href="#tof">&#710;</a>
    <a name="diff">Usage: </a><a href="cmd_diff.wiki">fossil diff</a>|gdiff ?-i? ?-r REVISION? FILE...
    Show the difference between the current version of a file (as it
    exists on disk) and that same file as it was checked out.

    diff will show a textual diff while gdiff will attempt to run a
................................................................................
    associated with the named file(s) but otherwise leave the update
    or merge undone.

    A single level of undo/redo is supported.  The undo/redo stack
    is cleared by the commit and checkout commands.

<hr><a href="#tof">&#710;</a>
    <a name="revert">Usage: </a><a href="cmd_revert.wiki">fossil revert</a> ?--yes? ?-r CHECKIN? FILE
    Revert to the current repository version of FILE, or to
    the version associated with check-in CHECKIN if the -r flag
    appears.  This command will confirm your operation unless the
    file is missing or the --yes option is used.

<hr><a href="#tof">&#710;</a>
    <a name="server">Usage: </a><a href="cmd_server.wiki">fossil server</a> ?-P|--port TCPPORT? ?REPOSITORY?    Or: fossil ui ?-P|--port TCPPORT? ?REPOSITORY?

    Open a socket and begin listening and responding to HTTP requests on
................................................................................
    the equivalent of running both "push" and "pull" at the same time.
    See the "pull" command for additional information.

<hr><a href="#tof">&#710;</a>
    <a name="tag">Usage: </a><a href="cmd_tag.wiki">fossil tag</a> SUBCOMMAND ...
    Run various subcommands to control tags and properties

    fossil tag add ?--raw? TAGNAME CHECK-IN ?VALUE?

    Add a new tag or property to CHECK-IN. The tag will
    be usable instead of a CHECK-IN in commands such as
    update and merge.

    fossil tag branch ?--raw? ?--nofork? TAGNAME CHECK-IN ?VALUE?

    A fork will be created so that the new checkin
    is a sibling of CHECK-IN and identical to it except
    for a generated comment. Then the new tag will
    be added to the new checkin and propagated to
    all direct children.  Additionally all symbolic
    tags of that checkin inherited from CHECK-IN will
    be cancelled.

    However, if the option --nofork is given, no
    fork will be created and the tag/property will be
    added to CHECK-IN directly. No tags will be canceled.

    fossil tag cancel ?--raw? TAGNAME CHECK-IN

    Remove the tag TAGNAME from CHECK-IN, and also remove
    the propagation of the tag to any descendants.

    fossil tag find ?--raw? TAGNAME

    List all check-ins that use TAGNAME

    fossil tag list ?--raw? ?CHECK-IN?

    List all tags, or if CHECK-IN is supplied, list
    all tags and their values for CHECK-IN.

    The option --raw allows the manipulation of all types of
    tags used for various internal purposes in fossil. You
    should not use this option to make changes unless you are
    sure what you are doing.

    If you need to use a tagname that might be confused with
    a hexadecimal check-in or artifact ID, you can explicitly
    disambiguate it by prefixing it with "tag:". For instance:

    fossil update decaf

    will be taken as an artifact or check-in ID and fossil will
    probably complain that no such revision was found. However

    fossil update tag:decaf

    will assume that "decaf" is a tag/branch name.

<hr><a href="#tof">&#710;</a>
    <a name="timeline">Usage: </a><a href="cmd_timeline.wiki">fossil timeline</a> ?WHEN? ?CHECK-IN|DATETIME? ?-n|--count N?
    Print a summary of activity going backwards in date and time
    specified or from the current date and time if no arguments
    are given.  Show as many as N (default 20) check-ins.  The
    WHEN argument can be any unique abbreviation of one of these
    keywords:

    before
    after
    descendants | children
    ancestors | parents

    The CHECK-IN can be any unique prefix of 4 characters or more.
    The DATETIME should be in the ISO8601 format.  For
    examples: "2007-08-18 07:21:21".  You can also say "current"
    for the current version or "now" for the current time.

<hr><a href="#tof">&#710;</a>
    <a name="undo">Usage: </a><a href="cmd_undo.wiki">fossil undo</a> ?FILENAME...?
    Undo the most recent update or merge operation.  If FILENAME is

Changes to www/selfcheck.wiki.

74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
So, in other words, fossil always checks to make sure it can
re-extract a file before it commits a change to that file.
Hence bugs in fossil are unlikely to corrupt the repository in
a way that prevents us from extracting historical versions of 
files.
</p>

<h2>Checksum Over All Files In A Baseline</h2>

<p>
Manifest artifacts that define a baseline have two fields (the
R-card and Z-card) that record MD5 hashs of the manifest itself
and of all other files in the manifest.  Prior to any check-in
commit, these checksums are verified to ensure that the baseline
checked in agrees exactly with what is on disk.  Similarly,
the repository checksum is verified after a checkout to make
sure that the entire repository was checked out correctly.
Note that these added checks use a different hash (MD5 instead
of SHA1) in order to avoid common-mode failures in the hash
algorithm implementation.
</p>







|


|


|







74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
So, in other words, fossil always checks to make sure it can
re-extract a file before it commits a change to that file.
Hence bugs in fossil are unlikely to corrupt the repository in
a way that prevents us from extracting historical versions of 
files.
</p>

<h2>Checksum Over All Files In A Check-in</h2>

<p>
Manifest artifacts that define a check-in have two fields (the
R-card and Z-card) that record MD5 hashs of the manifest itself
and of all other files in the manifest.  Prior to any check-in
commit, these checksums are verified to ensure that the check-in
checked in agrees exactly with what is on disk.  Similarly,
the repository checksum is verified after a checkout to make
sure that the entire repository was checked out correctly.
Note that these added checks use a different hash (MD5 instead
of SHA1) in order to avoid common-mode failures in the hash
algorithm implementation.
</p>

Changes to www/wikitheory.wiki.

31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
      there is nothing new to learn.  And, though cumbersome, the HTML
      does not need to be used very often so need not be a burden.


<h2>Stand-alone Wiki Pages</h2>

Each wiki page has its own revision history which is independent of
the sequence of baselines (check-ins).  Wiki pages can branch and merge
just like baselines, though as of this writing (2008-07-29) there is
no mechanism in the user interface to support branching and merging.
The current implementation of the wiki shows the version of the wiki
page that has the most recent timestamp.

In other words, if two users make unrelated changes to the same wiki
page on separate repositories, then those repositories are synced,
the wiki page will fork.  The web interface will display whichever edit







|
|







31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
      there is nothing new to learn.  And, though cumbersome, the HTML
      does not need to be used very often so need not be a burden.


<h2>Stand-alone Wiki Pages</h2>

Each wiki page has its own revision history which is independent of
the sequence of check-ins (check-ins).  Wiki pages can branch and merge
just like check-ins, though as of this writing (2008-07-29) there is
no mechanism in the user interface to support branching and merging.
The current implementation of the wiki shows the version of the wiki
page that has the most recent timestamp.

In other words, if two users make unrelated changes to the same wiki
page on separate repositories, then those repositories are synced,
the wiki page will fork.  The web interface will display whichever edit