Fossil

Check-in [0e1447a6]
Login

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

Overview
Comment:Update the quick-start guide documentation to provide hyperlinks to the command-line help in the web interface. Add the beginning of a technical overview article, but as that article is still incomplete, do not hyperlink to it.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:0e1447a6ea799421066336cd1ed7dda53b34b1f6
User & Date: drh 2010-12-26 00:43:43
Context
2010-12-26
13:22
Change the "setting" command so that it works for global settings even if it is run outside of a check-out and with no repository specified using -R. check-in: 3d592297 user: drh tags: trunk
00:43
Update the quick-start guide documentation to provide hyperlinks to the command-line help in the web interface. Add the beginning of a technical overview article, but as that article is still incomplete, do not hyperlink to it. check-in: 0e1447a6 user: drh tags: trunk
00:40
Fix the mkindex program so that it ignores lines beginning with COMMAND: when assembling help text. check-in: de4c07ca user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/quickstart.wiki.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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
..
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
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
...
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

174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221

222
223

224
225
226
227
228
229

230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
...
301
302
303
304
305
306
307

308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
...
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
<title>Fossil Quick Start Guide</title>
<nowiki>
<h1 align="center">Fossil Quick Start</h1>

<p>This is a guide to get you started using fossil quickly
and painlessly.</p>

<h2>Installing</h2><blockquote>

    <p>Fossil is a single self-contained C program.  You need to
    either download a 
    <a href="http://www.fossil-scm.org/download.html">precompiled binary</a>
    or <a href="build.wiki">build it yourself</a> from sources.
    Install fossil by putting the fossil binary
    someplace on your PATH environment variable.</p>
    
</blockquote>
<a name="fslclone"></a>

<h2>General Work Flow</h2><blockquote>

    <p>Fossil works with repository files, a database with the project's
    complete history, and with checked-out local trees, the working directory
    you use to do your work.  In most operations that require you to work on a
    specific repository you must have a checked out tree in place to work  from.
    The resulting workflow looks like this:</p>

    <ul>
        <li>Create or clone a repository file.  (<b>fossil new</b> or
            <b>fossil clone</b>)
        <li>Check out a local tree.  (<b>fossil open</b>)
        <li>Perform operations on the repository (including repository
            configuration).
        <li><em>Optionally</em> close the local tree.  (<b>fossil
            close</b>, but this is rarely used.)
    </ul>

    <p>The following sections will give you a brief overview of these
    operations.</p>

</blockquote>

<h2>Starting A New Project</h2><blockquote>

    <p>To start a new project with fossil, create a new empty repository
    this way:</p>

    
    <blockquote>
    <b>fossil new </b><i> repository-filename</i>
    </blockquote>

</blockquote>
    
<h2>Cloning An Existing Repository</h2><blockquote>

    <p>Most fossil operations interact with a repository that is on the
    local disk drive, not on a remote system.  Hence, before accessing
    a remote repository it is necessary to make a local copy of that
    repository.  Making a local copy of a remote repository is called
    "cloning".</p>
    
    <p>Clone a remote repository as follows:</p>
    
    <blockquote>
    <b>fossil clone</b> <i>URL  repository-filename</i>
    </blockquote>
    
    <p>The <i>URL</i> above is the http URL for the fossil repository
    you want to clone, and it may include a "user:password" part, e.g.
................................................................................
    which in the example above is named "myclone.fossil".
    You can name your repositories anything you want.  The ".fossil" suffix
    is not required.</p>

    <p>Note: If you are behind a restrictive firewall, you might need
    to <a href="#proxy">specify an HTTP proxy</a> to use.</p>
    
</blockquote><h2>Importing From Another Version Control System</h2><blockquote>

    <p>Rather than start a new project, or clone an existing Fossil project,
    you might prefer to 
    <a href="./inout.wiki">import an existing Git project</a>
    into Fossil.

</blockquote><h2>Checking Out A Local Tree</h2><blockquote>

    <p>To work on a project in fossil, you need to check out a local
    copy of the source tree.  Create the directory you want to be
    the root of your tree and cd into that directory.  Then
    do this:</p>
    
    <blockquote>
    <b>fossil open </b><i> repository-filename</i>
    </blockquote>
    
    <p>This leaves you with the newest version of the tree
    checked out.    
    From anywhere underneath the root of your local tree, you
    can type commands like the following to find out the status of
    your local tree:</p>

    <blockquote>
    <b>fossil info</b><br>
    <b>fossil status</b><br>
    <b>fossil changes</b><br>
    <b>fossil diff</b><br>
    <b>fossil timeline</b><br>
    <b>fossil ls</b><br>
    <b>fossil branch list</b><br>
    </blockquote>

</blockquote><h2>Configuring Your Local Repository</h2><blockquote>
    
    <p>When you create a new repository, either by cloning an existing
    project or create a new project of your own, you usually want to do some
    local configuration.  This is easily accomplished using the webserver
    that is built into fossil.  Start the fossil webserver like this:</p>

    
    <blockquote>
    <b>fossil ui </b><i> repository-filename</i>
    </blockquote>

    <p>You can omit the <i>repository-filename</i> from the command above
    if you are inside a checked-out local tree.</p>
................................................................................
    <p>By default, fossil does not require a login for HTTP connections
    coming in from the IP loopback address 127.0.0.1.  You can, and perhaps
    should, change this after you create a few users.</p>
    
    <p>When you are finished configuring, just press Control-C or use
    the <b>kill</b> command to shut down the mini-server.</p>

</blockquote><h2>Making Changes</h2><blockquote>

    <p>To add new files to your project, or remove old files, use these
    commands:</p>

    <blockquote>
    <b>fossil add</b> <i>file...</i><br>
    <b>fossil rm</b> <i>file...</i>
    </blockquote>

    <p>You can also edit files freely.  Once you are ready to commit
    your changes, type:</p>

    <blockquote>
    <b>fossil commit</b>
    </blockquote>

    <p>You will be prompted for check-in comments using whatever editor
    is specified by your VISUAL or EDITOR environment variable.</p>

</blockquote><h2>Sharing Changes</h2><blockquote>


    <p>The changes you <b>commit</b> are only on your local repository.
    To share those changes with other repositories, do:</p>

    <blockquote>
    <b>fossil push</b> <i>URL</i>
    </blockquote>

    <p>Where <i>URL</i> is the http: URL of the server repository you
    want to share your changes with.  If you omit the <i>URL</i> argument,
    fossil will use whatever server you most recently synced with.</p>

    <p>The <b>push</b> command only sends your changes to others.  To
    Receive changes from others, use <b>pull</b>.  Or go both ways at
    once using <b>sync</b>:</p>

    <blockquote>
    <b>fossil pull</b> <i>URL</i><br>
    <b>fossil sync</b> <i>URL</i>
    </blockquote>

    <p>When you pull in changes from others, they go into your repository,
    not into your checked-out local tree.  To get the changes into your
    local tree, use <b>update</b>:</p>

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

    <p>The <i>VERSION</i> can be the name of a branch or tag or any
    abbreviation to the 40-character
    artifact identifier for a particular check-in, or it can be a
    date/time stamp.  (<a href="./checkin_names.wiki">More information</a>.)
    If you omit
    the <i>VERSION</i>, then fossil moves you to the
    latest version of the branch your are currently on.</p>

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

    <p>You can create branches by doing multiple commits off of the
    same base version.  To merge to branches back together, first
    <b>update</b> to the leaf of one branch.  Then do a <b>merge</b>
    of the leaf of the other branch:</p>

    <blockquote>
    <b>fossil merge</b> <i>VERSION</i>
    </blockquote>

    <p>The <i>VERSION</i> can be any of the forms allowed for <b>update</b>.

    After performing the merge, you will normally want to test it to
    make sure it does not break anything, then

    <b>commit</b> your chagnes.  In the default configuration, the <b>commit</b>
    command will also automatically <b>push</b> your changes, but that
    feature can be disabled.  (More information about 
    <a href="concepts.wiki#workflow">autosync</a> and how to disable it.)
    Remember that your coworkers can not see your changes until you 
    <b>commit</b> and <b>push</b> them.</p>


    <p>The merge command has options to cherrypick individual
    changes, or to back out individual changes.</p>

    <p>If a merge or update doesn't work out (perhaps something breaks or
    there are many merge conflicts) then you back up using:</p>

    <blockquote>
    <b>fossil undo</b>
    </blockquote>

    <p>This will back out the changes that the merge or update made to the
    working checkout.  There is also a <b>redo</b> command if you undo by
    mistake.  Undo and redo only work for changes that have
    not yet been checked in using <b>commit</b> and there is only a single
    level of undo/redo.</p>


<a name="serversetup"></a>
</blockquote><h2>Setting Up A Server</h2><blockquote>

    <p>The easiest way to set up a server is:</p>

    <blockquote>
    <b>fossil server</b> <i>repository-filename</i>
    </blockquote>

    <p>Or</b>

    <blockquote>
    <b>fossil ui</b> <i>repository-filename</i>
    </blockquote>

    <p>The <b>ui</b> command is intended for accessing the web interface
    from a local desktop.  The <b>ui</b> command binds to the loopback IP
    address only (and is thus makes the web interface visible only on the
    local machine) and it automatically start your web browser pointing at the
    server.  For cross-machine collaboration, use the <b>server</b> command,
................................................................................
    <p>Adjust the paths to suit your installation, of course.  Notice that
    fossil runs as root.  This is not required - you can run it as an
    unprivileged user.  But it is more secure to run fossil as root.
    When you do run fossil as root, it automatically puts itself in a
    chroot jail in the same directory as the repository, then drops
    root privileges prior to reading any information from the request.</p>


</blockquote><a name="proxy"></a><h2>HTTP Proxies</h2><blockquote>

    <p>If you are behind a restrictive firewall that requires you to use
    an HTTP proxy to reach the internet, then you can configure the proxy
    in three different ways.  You can tell fossil about your proxy using
    a command-line option on commands that use the network,
    <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.</p>

    <blockquote>
    <b>fossil clone </b><i>URL</i>  <b>--proxy</b> <i>Proxy-URL</i>
    </blockquote>

    <p>It is annoying to have to type in the proxy URL every time you
    sync your project, though, so you can make the proxy configuration
    persistent using the <b>setting</b> command:</p>

    <blockquote>
    <b>fossil setting proxy </b><i>Proxy-URL</i>
    </blockquote>

    <p>Or, you can set the "<b>http_proxy</b>" environment variable:</p>

................................................................................
    is easily done on the command-line.  For example, to sync with
    a co-workers repository on your LAN, you might type:</p>   

    <blockquote>
    <b>fossil sync http://192.168.1.36:8080/ --proxy off</b>
    </blockquote>

</blockquote><h2>More Hints</h2><blockquote>

    <p>Try these commands:</p>

    <blockquote><b>
    fossil help<br>
    fossil test-commands
    </b></blockquote>

    <p>Explore and have fun!</p>


</blockquote>
</nowiki>

<





|








<

<
|








|
|
|


|
|





<
<
|


<
>





<
<
|







|







 







|




|

|




|












|
|
|
|
|
|
|


|




|
>







 







|





|
|






|





|

>
|



|






|
|
|


|
|




|


|





|




|



|
|


|


|
>


>
|
|

|

<
>








|



|

|




|




|





|







 







>
|













|







 







|




|
|



<
<
<
<
1

2
3
4
5
6
7
8
9
10
11
12
13
14
15

16

17
18
19
20
21
22
23
24
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
..
73
74
75
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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
...
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
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225

226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
...
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
...
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358




<title>Fossil Quick Start Guide</title>

<h1 align="center">Fossil Quick Start</h1>

<p>This is a guide to get you started using fossil quickly
and painlessly.</p>

<h2>Installing</h2>

    <p>Fossil is a single self-contained C program.  You need to
    either download a 
    <a href="http://www.fossil-scm.org/download.html">precompiled binary</a>
    or <a href="build.wiki">build it yourself</a> from sources.
    Install fossil by putting the fossil binary
    someplace on your PATH environment variable.</p>
    

<a name="fslclone"></a>

<h2>General Work Flow</h2>

    <p>Fossil works with repository files, a database with the project's
    complete history, and with checked-out local trees, the working directory
    you use to do your work.  In most operations that require you to work on a
    specific repository you must have a checked out tree in place to work  from.
    The resulting workflow looks like this:</p>

    <ul>
        <li>Create or clone a repository file.  ([/help/new|fossil new] or
            [/help/clone | fossil clone])
        <li>Check out a local tree.  ([/help/open | fossil open])
        <li>Perform operations on the repository (including repository
            configuration).
        <li><em>Optionally</em> close the local tree.  
            ([/help/close | fossil close], but this is rarely used.)
    </ul>

    <p>The following sections will give you a brief overview of these
    operations.</p>



<h2>Starting A New Project</h2>

    <p>To start a new project with fossil, create a new empty repository

    this way: ([/help/new | more info]) </p>
    
    <blockquote>
    <b>fossil new </b><i> repository-filename</i>
    </blockquote>



<h2>Cloning An Existing Repository</h2>

    <p>Most fossil operations interact with a repository that is on the
    local disk drive, not on a remote system.  Hence, before accessing
    a remote repository it is necessary to make a local copy of that
    repository.  Making a local copy of a remote repository is called
    "cloning".</p>
    
    <p>Clone a remote repository as follows: ([/help/clone | more info])</p>
    
    <blockquote>
    <b>fossil clone</b> <i>URL  repository-filename</i>
    </blockquote>
    
    <p>The <i>URL</i> above is the http URL for the fossil repository
    you want to clone, and it may include a "user:password" part, e.g.
................................................................................
    which in the example above is named "myclone.fossil".
    You can name your repositories anything you want.  The ".fossil" suffix
    is not required.</p>

    <p>Note: If you are behind a restrictive firewall, you might need
    to <a href="#proxy">specify an HTTP proxy</a> to use.</p>
    
<h2>Importing From Another Version Control System</h2>

    <p>Rather than start a new project, or clone an existing Fossil project,
    you might prefer to 
    <a href="./inout.wiki">import an existing Git project</a>
    into Fossil using the [/help/import | fossil import] command.

<h2>Checking Out A Local Tree</h2>

    <p>To work on a project in fossil, you need to check out a local
    copy of the source tree.  Create the directory you want to be
    the root of your tree and cd into that directory.  Then
    do this: ([/help/open | more info])</p>
    
    <blockquote>
    <b>fossil open </b><i> repository-filename</i>
    </blockquote>
    
    <p>This leaves you with the newest version of the tree
    checked out.    
    From anywhere underneath the root of your local tree, you
    can type commands like the following to find out the status of
    your local tree:</p>

    <blockquote>
    <b>[/help/info | fossil info]</b><br>
    <b>[/help/status | fossil status]</b><br>
    <b>[/help/changes | fossil changes]</b><br>
    <b>[/help/diff | fossil diff]</b><br>
    <b>[/help/timeline | fossil timeline]</b><br>
    <b>[/help/ls | fossil ls]</b><br>
    <b>[/help/branch | fossil branch]</b><br>
    </blockquote>

<h2>Configuring Your Local Repository</h2>
    
    <p>When you create a new repository, either by cloning an existing
    project or create a new project of your own, you usually want to do some
    local configuration.  This is easily accomplished using the webserver
    that is built into fossil.  Start the fossil webserver like this:
    ([/help/ui | more info])</p>
    
    <blockquote>
    <b>fossil ui </b><i> repository-filename</i>
    </blockquote>

    <p>You can omit the <i>repository-filename</i> from the command above
    if you are inside a checked-out local tree.</p>
................................................................................
    <p>By default, fossil does not require a login for HTTP connections
    coming in from the IP loopback address 127.0.0.1.  You can, and perhaps
    should, change this after you create a few users.</p>
    
    <p>When you are finished configuring, just press Control-C or use
    the <b>kill</b> command to shut down the mini-server.</p>

<h2>Making Changes</h2>

    <p>To add new files to your project, or remove old files, use these
    commands:</p>

    <blockquote>
    <b>[/help/add | fossil add]</b> <i>file...</i><br>
    <b>[/help/rm | fossil rm]</b> <i>file...</i>
    </blockquote>

    <p>You can also edit files freely.  Once you are ready to commit
    your changes, type:</p>

    <blockquote>
    <b>[/help/commit | fossil commit]</b>
    </blockquote>

    <p>You will be prompted for check-in comments using whatever editor
    is specified by your VISUAL or EDITOR environment variable.</p>

<h2>Sharing Changes</h2>

    <p>The changes you [/help/commit | commit] are only
    on your local repository.
    To share those changes with other repositories, do:</p>

    <blockquote>
    <b>[/help/push | fossil push]</b> <i>URL</i>
    </blockquote>

    <p>Where <i>URL</i> is the http: URL of the server repository you
    want to share your changes with.  If you omit the <i>URL</i> argument,
    fossil will use whatever server you most recently synced with.</p>

    <p>The [/help/push | push] command only sends your changes to others.  To
    Receive changes from others, use [/help/pull | pull].  Or go both ways at
    once using [/help/sync | sync]:</p>

    <blockquote>
    <b>[/help/pull | fossil pull]</b> <i>URL</i><br>
    <b>[/help/sync | fossil sync]</b> <i>URL</i>
    </blockquote>

    <p>When you pull in changes from others, they go into your repository,
    not into your checked-out local tree.  To get the changes into your
    local tree, use [/help/update | update]:</p>

    <blockquote>
    <b>[/help/update | fossil update]</b> <i>VERSION</i>
    </blockquote>

    <p>The <i>VERSION</i> can be the name of a branch or tag or any
    abbreviation to the 40-character
    artifact identifier for a particular check-in, or it can be a
    date/time stamp.  ([./checkin_names.wiki | more info])
    If you omit
    the <i>VERSION</i>, then fossil moves you to the
    latest version of the branch your are currently on.</p>

<h2>Branching And Merging</h2>

    <p>You can create branches by doing multiple commits off of the
    same base version.  To merge to branches back together, first
    [/help/update | update] to the leaf of one branch.  Then do a
    [/help/merge | merge] of the leaf of the other branch:</p>

    <blockquote>
    <b>[/help/merge | fossil merge]</b> <i>VERSION</i>
    </blockquote>

    <p>The <i>VERSION</i> can be any of the forms allowed for 
    [/help/update | update].
    After performing the merge, you will normally want to test it to
    make sure it does not break anything, then
    [/help/commit | commit] your changes.
    In the default configuration, the [/help/commit|commit]
    command will also automatically [/help/push|push] your changes, but that
    feature can be disabled.  (More information about 
    [./concepts.wiki#workflow|autosync] and how to disable it.)
    Remember that your coworkers can not see your changes until you 

    commit and push them.</p>

    <p>The merge command has options to cherrypick individual
    changes, or to back out individual changes.</p>

    <p>If a merge or update doesn't work out (perhaps something breaks or
    there are many merge conflicts) then you back up using:</p>

    <blockquote>
    <b>[/help/undo | fossil undo]</b>
    </blockquote>

    <p>This will back out the changes that the merge or update made to the
    working checkout.  There is also a [/help/redo|redo] command if you undo by
    mistake.  Undo and redo only work for changes that have
    not yet been checked in using commit and there is only a single
    level of undo/redo.</p>


<a name="serversetup"></a>
<h2>Setting Up A Server</h2>

    <p>The easiest way to set up a server is:</p>

    <blockquote>
    <b>[/help/server | fossil server]</b> <i>repository-filename</i>
    </blockquote>

    <p>Or</b>

    <blockquote>
    <b>[/help/ui | fossil ui]</b> <i>repository-filename</i>
    </blockquote>

    <p>The <b>ui</b> command is intended for accessing the web interface
    from a local desktop.  The <b>ui</b> command binds to the loopback IP
    address only (and is thus makes the web interface visible only on the
    local machine) and it automatically start your web browser pointing at the
    server.  For cross-machine collaboration, use the <b>server</b> command,
................................................................................
    <p>Adjust the paths to suit your installation, of course.  Notice that
    fossil runs as root.  This is not required - you can run it as an
    unprivileged user.  But it is more secure to run fossil as root.
    When you do run fossil as root, it automatically puts itself in a
    chroot jail in the same directory as the repository, then drops
    root privileges prior to reading any information from the request.</p>

<a name="proxy"></a>
<h2>HTTP Proxies</h2>

    <p>If you are behind a restrictive firewall that requires you to use
    an HTTP proxy to reach the internet, then you can configure the proxy
    in three different ways.  You can tell fossil about your proxy using
    a command-line option on commands that use the network,
    <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.</p>

    <blockquote>
    <b>fossil clone </b><i>URL</i>  <b>--proxy</b> <i>Proxy-URL</i>
    </blockquote>

    <p>It is annoying to have to type in the proxy URL every time you
    sync your project, though, so you can make the proxy configuration
    persistent using the [/help/setting | setting] command:</p>

    <blockquote>
    <b>fossil setting proxy </b><i>Proxy-URL</i>
    </blockquote>

    <p>Or, you can set the "<b>http_proxy</b>" environment variable:</p>

................................................................................
    is easily done on the command-line.  For example, to sync with
    a co-workers repository on your LAN, you might type:</p>   

    <blockquote>
    <b>fossil sync http://192.168.1.36:8080/ --proxy off</b>
    </blockquote>

<h2>More Hints</h2>

    <p>Try these commands:</p>

    <blockquote><b>
    [/help/help | fossil help]<br>
    [/help/test-command | fossil test-commands]
    </b></blockquote>

    <p>Explore and have fun!</p>




Added www/tech_overview.wiki.





















































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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
71
72
73
74
75
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
106
<title>Technical Overview</title>
<h2 align="center">
A Technical Overview<br>Of The Design And Implementation<br>Of Fossil
</h2>

<h2>1.0 Introduction</h2>

At its lowest level, a Fossil repository consists of an unordered set
of immutable "artifacts".  Think of these artifacts as "files", since in
many cases the artifacts do indeed exactly correspond to source code files
that are stored in the Fossil repostory.  But other "control artifacts" 
are also included in the mix.  These control artifacts define the relationships
between artifacts - which files go together to form a particular
version of the project, who checked in that version and when, what was
the check-in comment, what wiki pages are included with the project, what
are the edit histories of each wiki page, what bug reports or tickets are
included, who contributed to the evolution of each ticket, and so forth,
and so on.  This low-level file format is called the "global state" of
the repository, since this is the information that is synced to peer
repositories using push and pull operations.   the low-level file format
is also called "enduring" since it is intended to last for generations.
The details of the low-level, enduring, global file format 
are [./fileformat.wiki | described separately].

This article is about how Fossil is currently implemented.  Instead of
dealing with vague abstractions of "enduring file formats" as the
[./fileformat.wiki | that other document] does, this article provides
some detail on how Fossil actually stores information on disk.  

<h2>2.0 Three Databases</h2>

Fossil stores state information in 
[http://www.sqlite.org/ | SQLite] database files.
SQLite stores an entire relational database, including multiple tables and
indices, in a single disk file.  The SQLite library allows the database
files to be efficiently queried and updated using the industry-standard
SQL language.  And SQLite makes updates to these database files atomic,
even in the face of system crashes and power failures, meaning that even
a power loss in the middle of a commit will not damage the Fossil repository
content.

Fossil uses three separate SQLite databases:

<ol>
<li>The configuration database
<li>Repository databases
<li>Checkout databases
</ol>

The configuration database is a one-per-user database that holds
global configuration information used by Fossil.  There is one
repository database per project.  The repository database is the
file that people are normally referring to when they say 
"a Fossil repository".  The checkout database is found in the working
checkout for a project and contains state information that is unique
to that working checkout.

The chart below provides a quick summary of how each of these
database files are used by Fossil, with detailed discussion following.

<center><table border="1" width="80%" cellpadding="0">
<tr>
<td width="33%" valign="top">
<h3 align="center">Configuration Database<br>"~/.fossil"</h3>
<ul>
<li>Global [/help/setting |settings]
<li>List of active repositories used by the [/help/all | all] command
</ul>
</td>
<td width="34%" valign="top">
<h3 align="center">Repository Database<br>"<i>project</i>.fossil"</h3>
<ul>
<li>[./fileformat.wiki | Global state of the project]
    encoded using delta-compression
<li>Local [/help/setting|settings]
<li>Web interface display preferences
<li>User credentials and permissions
<li>Meta-data about the global state to facilitate rapid
    queries
</ul>
</td>
<td width="33%" valign="top">
<h3 align="center">Checkout Database<br>"_FOSSIL_"</h3>
<ul>
<li>The version currently checked out
<li>Other versions [/help/merge | merged] in but not
    yet [/help/commit | committed]
<li>Changes from the [/help/add | add], [/help/delete | delete],
    and [/help/rename | rename] commands that have not yet been committed
<li>"mtime" values and other information used to efficiently detect
     local edits
<li>The "[/help/stash | stash]"
<li>Information needed to "[/help/undo|undo]" or "[/help/redo|redo]"
</ul>
</td>
</tr>
</table>
</center>

<h3>2.1 The Configuration Database</h3>




<h3>2.2 Repository Databases</h3>
<h3>2.3 Checkout Databases</h3>