Fossil SCM

fossil-scm / www / quickstart.wiki
Source Rendered
Blame History Raw 578 lines
1
<title>Fossil Quick Start Guide</title>
2
3
This is a guide to help you get started using the Fossil [https://en.wikipedia.org/wiki/Distributed_version_control|Distributed Version Control System] quickly
4
and painlessly.
5
6
<h2 id="install">Installing</h2>
7
8
Fossil is a single self-contained C program. You need to
9
either download a
10
[https://fossil-scm.org/home/uv/download.html|precompiled
11
binary]
12
or <a href="build.wiki">compile it yourself</a> from sources.
13
Install Fossil by putting the fossil binary
14
someplace on your $PATH.
15
16
You can test that Fossil is present and working like this:
17
18
<pre><b>fossil version
19
This is fossil version 2.25 [8f798279d5] 2024-11-06 12:59:09 UTC
20
</b></pre>
21
22
<h2 id="workflow" name="fslclone">General Work Flow</h2>
23
24
Fossil works with [./glossary.md#repository | repository files]
25
and [./glossary.md#check-out | check-out directories] using a
26
workflow like this:
27
28
<ul>
29
<li>Create or clone a repository file. ([/help/init|fossil init] or
30
[/help/clone | fossil clone])
31
<li>Check out a local tree. ([/help/open | fossil open])
32
<li>Perform operations on the repository (including repository
33
configuration).
34
</ul>
35
36
Fossil can be entirely driven from the command line. Many features
37
can also be conveniently accessed from the built-in web user interface.
38
39
The following sections give a brief overview of these
40
operations.
41
42
<h2 id="new">Starting A New Project</h2>
43
44
To start a new project with Fossil, [/help/init | create a new empty repository]:
45
46
<pre><b>fossil init</b> <i>repository-filename</i>
47
</pre>
48
49
You can name the database anything you like, and you can place it anywhere in the filesystem.
50
The <tt>.fossil</tt> extension is traditional, but it is only required if you are going to use the
51
<tt>[/help/server | fossil server DIRECTORY]</tt> feature.
52
53
Next, do something along the lines of:
54
55
<pre>
56
<b>mkdir -p ~/src/project/trunk</b>
57
<b>cd ~/src/project/trunk</b>
58
<b>fossil open</b> <i>repository-filename</i>
59
<b>fossil add</b> foo.c bar.h qux.md
60
<b>fossil commit</b>
61
</pre>
62
63
If your project directory already exists, obviating the <b>mkdir</b>
64
step, you will instead need to add the <tt>--force</tt> flag to the
65
<b>open</b> command to authorize Fossil to open the repo into a
66
non-empty checkout directory. (This is to avoid accidental opens into,
67
for example, your home directory.)
68
69
The convention of naming your checkout directory after a long-lived
70
branch name like "trunk" is in support of Fossil's ability to have as
71
many open checkouts as you like. This author frequently has additional
72
checkout directories named <tt>../release</tt>, <tt>../scratch</tt>,
73
etc. The release directory is open to the branch of the same name, while
74
the scratch directory is used when disturbing one of the other
75
long-lived checkout directories is undesireable, as when performing a
76
[/help/bisect | bisect] operation.
77
78
79
<h2 id="clone">Cloning An Existing Repository</h2>
80
81
Most fossil operations interact with a repository that is on the
82
local disk drive, not on a remote system. Hence, before accessing
83
a remote repository it is necessary to make a local copy of that
84
repository, a process called
85
"[/help/clone | cloning]".
86
87
This is done as follows:
88
89
<pre><b>fossil clone</b> <i>URL repository-filename</i>
90
</pre>
91
92
The <i>URL</i> specifies the fossil repository
93
you want to clone. The <i>repository-filename</i> is the new local
94
filename into which the cloned repository will be written. For
95
example, to clone the source code of Fossil itself:
96
97
<pre><b>fossil clone https://fossil-scm.org/ myclone.fossil</b></pre>
98
99
If your logged-in username is 'exampleuser', you should see output something like this:
100
101
<pre><b>Round-trips: 8 Artifacts sent: 0 received: 39421
102
Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0
103
Rebuilding repository meta-data...
104
100% complete...
105
Extra delta compression...
106
Vacuuming the database...
107
project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333
108
server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42
109
admin-user: exampleuser (intial remote-access password is "yoWgDR42iv")>
110
</b></pre>
111
112
This <i>exampleuser</i> will be used by Fossil as the author of commits when
113
you checkin changes to the repository. It is also used by Fossil when you
114
make your repository available to others using the built-in server mode by
115
running <tt>[/help/server | fossil server]</tt> and will also be used when
116
running <tt>[/help/ui | fossil ui]</tt> to view the repository through
117
the Fossil UI. See the quick start topic for setting up a
118
<a href="#server">server</a> for more details.
119
120
If the remote repository requires a login, include a
121
userid in the URL like this:
122
123
<pre><b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b></pre>
124
125
You will be prompted separately for the password.
126
Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid.
127
For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget")
128
129
If you are behind a restrictive firewall, you might need
130
to <a href="#proxy">specify an HTTP proxy</a>.
131
132
A Fossil repository is a single disk file. Instead of cloning,
133
you can just make a copy of the repository file (for example, using
134
"scp"). Note, however, that the repository file contains auxiliary
135
information above and beyond the versioned files, including some
136
sensitive information such as password hashes and email addresses. If you
137
want to share Fossil repositories directly by copying, consider running the
138
[/help/scrub|fossil scrub] command to remove sensitive information
139
before transmitting the file.
140
141
<h2 id="import">Importing From Another Version Control System</h2>
142
143
Rather than start a new project, or clone an existing Fossil project,
144
you might prefer to
145
<a href="./inout.wiki">import an existing Git project</a>
146
into Fossil using the [/help/import | fossil import] command.
147
148
You can even decide to export your project back into git using the
149
[/help/git | fossil git] command, which is how the Fossil project maintains
150
[https://github.com/drhsqlite/fossil-mirror | its public GitHub mirror]. There
151
is no limit to the number of times a tree can be imported and exported between
152
Fossil and git.
153
154
The [https://git-scm.com/docs/git-fast-export|Git fast-export format] has become
155
a popular way to move files between version management systems, including from
156
[https://www.mercurial-scm.org/|Mercurial].
157
Fossil can also import [https://subversion.apache.org/|Subversion projects] directly.
158
159
<h2 id="checkout">Checking Out A Local Tree</h2>
160
161
To work on a project in fossil, you need to check out a local
162
copy of the source tree. Create the directory you want to be
163
the root of your tree, <tt>cd</tt> into that directory, and then:
164
165
<pre><b>fossil open</b> <i>repository-filename</i></pre>
166
167
For example:
168
169
<pre><b>fossil open ../myclone.fossil
170
BUILD.txt
171
COPYRIGHT-BSD2.txt
172
README.md
173
︙
174
</tt></b></pre>
175
176
This leaves you with the newest version of the tree
177
checked out.
178
From anywhere underneath the root of your local tree, you
179
can type commands like the following to find out the status of
180
your local tree:
181
182
<pre>
183
<b>[/help/info | fossil info]</b>
184
<b>[/help/status | fossil status]</b>
185
<b>[/help/changes | fossil changes]</b>
186
<b>[/help/diff | fossil diff]</b>
187
<b>[/help/timeline | fossil timeline]</b>
188
<b>[/help/ls | fossil ls]</b>
189
<b>[/help/branch | fossil branch]</b>
190
</pre>
191
192
If you created a new repository using "fossil init" some commands will not
193
produce much output.
194
195
Note that Fossil allows you to make multiple check-outs in
196
separate directories from the same repository. This enables you,
197
for example, to do builds from multiple branches or versions at
198
the same time without having to generate extra clones.
199
200
To switch a checkout between different versions and branches,
201
use:
202
203
<pre>
204
<b>[/help/update | fossil update]</b>
205
<b>[/help/checkout | fossil checkout]</b>
206
</pre>
207
208
[/help/update | update] honors the "autosync" option and
209
does a "soft" switch, merging any local changes into the target
210
version, whereas [/help/checkout | checkout] does not
211
automatically sync and does a "hard" switch, overwriting local
212
changes if told to do so.
213
214
<h2 id="changes">Making and Committing Changes</h2>
215
216
To add new files to your project or remove existing ones, use these
217
commands:
218
219
<pre>
220
<b>[/help/add | fossil add]</b> <i>file...</i>
221
<b>[/help/rm | fossil rm]</b> <i>file...</i>
222
<b>[/help/addremove | fossil addremove]</b> <i>file...</i>
223
</pre>
224
225
The command:
226
227
<pre><b>[/help/changes | fossil changes]</b></pre>
228
229
lists files that have changed since the last commit to the repository. For
230
example, if you edit the file "README.md":
231
232
<pre><b>fossil changes
233
EDITED README.md
234
</b></pre>
235
236
To see exactly what change was made you can use the command
237
<b>[/help/diff | fossil diff]</b>:
238
239
<pre><b>fossil diff
240
Index: README.md
241
============================================================
242
--- README.md
243
+++ README.md
244
@@ -1,5 +1,6 @@
245
+Made some changes to the project
246
# Original text
247
</b></pre>
248
249
"fossil diff" shows the difference between your tree on disk now and as
250
the tree was when you last committed changes. If you haven't committed
251
yet, then it shows the difference relative to the tip-of-trunk commit in
252
the repository, being what you get when you "fossil open" a repository
253
without specifying a version, populating the working directory.
254
255
To see the most recent changes made to the repository by other users, use "fossil timeline" to
256
find out the most recent commit, and then "fossil diff" between that commit and the
257
current tree:
258
259
<pre><b><verbatim>fossil timeline
260
=== 2021-03-28 ===
261
03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk)
262
=== 2021-03-27 ===
263
23:58:05 [ab975c6632] Update README.md. (user: user-two tags: trunk)
264
⋮
265
266
fossil diff --from current --to ab975c6632
267
Index: frobnicate.c
268
============================================================
269
--- frobnicate.c
270
+++ frobnicate.c
271
@@ -1,10 +1,11 @@
272
+/* made a change to the source file */
273
# Original text
274
</verbatim></b></pre>
275
276
"current" is an alias for the checkout version, so the command
277
"fossil diff --from ad75dfa4a0 --to ab975c6632" gives identical results.
278
279
To commit your changes to a local-only repository:
280
281
<pre><b>fossil commit</b> <i>(... Fossil will start your editor, if defined)</i><b>
282
# Enter a commit message for this check-in. Lines beginning with # are ignored.
283
#
284
# user: exampleuser
285
# tags: trunk
286
#
287
# EDITED README.md
288
Edited file to add description of code changes
289
New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab
290
</b></pre>
291
292
You will be prompted for check-in comments using whatever editor
293
is specified by your VISUAL or EDITOR environment variable. If none is
294
specified Fossil uses line-editing in the terminal.
295
296
To commit your changes to a repository that was cloned from a remote
297
repository, you give the same command, but the results are different.
298
Fossil defaults to [./concepts.wiki#workflow|autosync] mode, a
299
single-stage commit that sends all changes committed to the local
300
repository immediately on to the remote parent repository. This only
301
works if you have write permission to the remote repository.
302
303
<h2 id="naming">Naming of Files, Checkins, and Branches</h2>
304
305
Fossil deals with information artifacts. This Quickstart document only deals
306
with files and collections of files, but be aware there are also tickets, wiki pages and more.
307
Every artifact in Fossil has a universally-unique hash id, and may also have a
308
human-readable name.
309
310
The following are all equivalent ways of identifying a Fossil file,
311
checkin or branch artifact:
312
313
<ul>
314
<li> the full unique SHA-256 hash, such as be836de35a821523beac2e53168e135d5ebd725d7af421e5f736a28e8034673a
315
<li> an abbreviated hash prefix, such as the first ten characters: be836de35a . This won't be universally unique, but it is usually unique within any one repository. As an example, the [https://fossil-scm.org/home/hash-collisions|Fossil project hash collisions] showed at the time of writing that there are no artifacts with identical first 8 characters
316
<li> a branch name, such as "special-features" or "juliet-testing". Each branch also has a unique SHA-256 hash
317
</ul>
318
319
A special convenience branch is "trunk", which is Fossil's default branch name for
320
the first checkin, and the default for any time a branch name is needed but not
321
specified.
322
323
This will get you started on identifying checkins. The
324
<a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including
325
how timestamps can also be used.
326
327
<h2 id="config">Accessing Your Local Repository's Web User Interface</h2>
328
329
After you create a new repository, you usually want to do some local
330
configuration. This is most easily accomplished by firing up the Fossil
331
UI:
332
333
<pre>
334
<b>fossil ui</b> <i>repository-filename</i>
335
</pre>
336
337
You can shorten that to just [/help/ui | <b>fossil ui</b>]
338
if you are inside a checked-out local tree.
339
340
This command starts an internal web server, after which Fossil
341
automatically launches your default browser, pointed at itself,
342
presenting a special view of the repository, its web user interface.
343
344
You may override Fossil's logic for selecting the default browser so:
345
346
<pre>
347
<b>fossil setting web-browser</b> <i>path-to-web-browser</i>
348
</pre>
349
350
When launched this way, Fossil binds its internal web server to the IP
351
loopback address, 127.0.0.1, which it treats specially, bypassing all
352
user controls, effectively giving visitors the
353
[./caps/admin-v-setup.md#apsu | all-powerful Setup capabliity].
354
355
Why is that a good idea, you ask? Because it is a safe
356
presumption that only someone with direct file access to the repository
357
database file could be using the resulting web interface. Anyone who can
358
modify the repo DB directly could give themselves any and all access
359
with a SQL query, or even by direct file manipulation; no amount of
360
access control matters to such a user.
361
362
(Contrast the [#server | many <i>other</i> ways] of setting Fossil up
363
as an HTTP server, where the repo DB is on the other side of the HTTP
364
server wall, inaccessible by all means other than Fossil's own
365
mediation. For this reason, the "localhost bypasses access control"
366
policy does <i>not</i> apply to these other interfaces. That is a very
367
good thing, since without this difference in policy, it would be unsafe
368
to bind a [/help/server | <b>fossil server</b>] instance to
369
localhost on a high-numbered port and then reverse-proxy it out to the
370
world via HTTPS, a practice this author does engage in, with confidence.)
371
372
Once you are finished configuring Fossil, you may safely Control-C out
373
of the <b>fossil&nbsp;ui</b> command to shut down this privileged
374
built-in web server. Moreover, you may by grace of SQLite do this <i>at
375
any time</i>: all changes are either committed durably to the repo DB or
376
rolled back, in their totality. This includes configuration changes.
377
378
<h2 id="sharing">Sharing Changes</h2>
379
380
When [./concepts.wiki#workflow|autosync] is turned off,
381
the changes you [/help/commit | commit] are only
382
on your local repository.
383
To share those changes with other repositories, do:
384
385
<pre>
386
<b>[/help/push | fossil push]</b> <i>URL</i>
387
</pre>
388
389
Where <i>URL</i> is the http: URL of the server repository you
390
want to share your changes with. If you omit the <i>URL</i> argument,
391
fossil will use whatever server you most recently synced with.
392
393
The [/help/push | push] command only sends your changes to others. To
394
Receive changes from others, use [/help/pull | pull]. Or go both ways at
395
once using [/help/sync | sync]:
396
397
<pre>
398
<b>[/help/pull | fossil pull]</b> <i>URL</i>
399
<b>[/help/sync | fossil sync]</b> <i>URL</i>
400
</pre>
401
402
When you pull in changes from others, they go into your repository,
403
not into your checked-out local tree. To get the changes into your
404
local tree, use [/help/update | update]:
405
406
<pre>
407
<b>[/help/update | fossil update]</b> <i>VERSION</i>
408
</pre>
409
410
The <i>VERSION</i> can be the name of a branch or tag or any
411
abbreviation to the 40-character
412
artifact identifier for a particular check-in, or it can be a
413
date/time stamp. ([./checkin_names.wiki | more info])
414
If you omit
415
the <i>VERSION</i>, then fossil moves you to the
416
latest version of the branch you are currently on.
417
418
The default behavior is for [./concepts.wiki#workflow|autosync] to
419
be turned on. That means that a [/help/pull|pull] automatically occurs
420
when you run [/help/update|update] and a [/help/push|push] happens
421
automatically after you [/help/commit|commit]. So in normal practice,
422
the push, pull, and sync commands are rarely used. But it is important
423
to know about them, all the same.
424
425
<pre>
426
<b>[/help/checkout | fossil checkout]</b> <i>VERSION</i>
427
</pre>
428
429
Is similar to update except that it does not honor the autosync
430
setting, nor does it merge in local changes - it prefers to overwrite
431
them and fails if local changes exist unless the <tt>--force</tt>
432
flag is used.
433
434
<h2 id="branch" name="merge">Branching And Merging</h2>
435
436
Use the --branch option to the [/help/commit | commit] command to start
437
a new branch at the point of need. ([./gitusers.md#bneed | Contrast git].)
438
439
To merge two branches back together, first
440
[/help/update | update] to the branch you want to merge into.
441
Then do a [/help/merge|merge] of the other branch that you want to incorporate
442
the changes from. For example, to merge "featureX" changes into "trunk"
443
do this:
444
445
<pre>
446
<b>fossil [/help/update|update] trunk</b>
447
<b>fossil [/help/merge|merge] featureX</b>
448
<i># make sure the merge didn't break anything...</i>
449
<b>fossil [/help/commit|commit]
450
</pre>
451
452
The argument to the [/help/merge|merge] command can be any of the
453
version identifier forms that work for [/help/update|update].
454
([./checkin_names.wiki|more info].)
455
The merge command has options to cherry-pick individual
456
changes, or to back out individual changes, if you don't want to
457
do a full merge.
458
459
The merge command puts all changes in your working check-out.
460
No changes are made to the repository.
461
You must run [/help/commit|commit] separately
462
to add the merge changes into your repository to make them persistent
463
and so that your coworkers can see them.
464
But before you do that, you will normally want to run a few tests
465
to verify that the merge didn't cause logic breaks in your code.
466
467
The same branch can be merged multiple times without trouble. Fossil
468
automatically keeps up with things and avoids conflicts when doing
469
multiple merges. So even if you have merged the featureX branch
470
into trunk previously, you can do so again and Fossil will automatically
471
know to pull in only those changes that have occurred since the previous
472
merge.
473
474
If a merge or update doesn't work out (perhaps something breaks or
475
there are many merge conflicts) then you back up using:
476
477
<pre>
478
<b>[/help/undo | fossil undo]</b>
479
</pre>
480
481
This will back out the changes that the merge or update made to the
482
working checkout. There is also a [/help/redo|redo] command if you undo by
483
mistake. Undo and redo only work for changes that have
484
not yet been checked in using commit and there is only a single
485
level of undo/redo.
486
487
488
<h2 id="server">Setting Up A Server</h2>
489
490
In addition to the inward-facing <b>fossil ui</b> mode covered [#config
491
| above], Fossil can also act as an outward-facing web server:
492
493
<pre>
494
<b>[/help/server | fossil server]</b> <i>repository-filename</i>
495
</pre>
496
497
Just as with <b>fossil ui</b>, you may omit the
498
<i>repository-filename</i> parameter when running this from within an open
499
check-out.
500
501
<i>Unlike</i> <b>fossil ui</b> mode, Fossil binds to all network
502
interfaces by default in this mode, and it enforces the configured
503
[./caps/ | role-based access controls]. Further, because it is meant to
504
provide external web service, it doesn't try to launch a local web
505
browser pointing to a "Fossil UI" presentation; external visitors see
506
your repository's configured home page instead.
507
508
To serve varying needs, there are additional ways to serve a Fossil repo
509
to external users:
510
511
<ul>
512
<li>[./server/any/cgi.md|CGI], as used by Fossil's [./selfhost.wiki |
513
self-hosting repositories]
514
<li>[./server/any/scgi.md|SCGI]
515
<li>[./server/any/inetd.md|inetd]
516
<li>[./server/debian/service.md|systemd]
517
</ul>
518
519
…along with [./server/#matrix | several other options].
520
521
We recommend that you read the [./server/whyuseaserver.wiki | Benefits
522
of a Fossil Server] article, because you might <i>need</i> to do this
523
and not yet know it.
524
525
<h2 id="proxy">HTTP Proxies</h2>
526
527
If you are behind a restrictive firewall that requires you to use
528
an HTTP proxy to reach the internet, then you can configure the proxy
529
in three different ways. You can tell fossil about your proxy using
530
a command-line option on commands that use the network,
531
<b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.
532
533
<pre>
534
<b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i>
535
</pre>
536
537
It is annoying to have to type in the proxy URL every time you
538
sync your project, though, so you can make the proxy configuration
539
persistent using the [/help/setting | setting] command:
540
541
<pre>
542
<b>fossil setting proxy </b><i>Proxy-URL</i>
543
</pre>
544
545
Or, you can set the "<b>http_proxy</b>" environment variable:
546
547
<pre>
548
<b>export http_proxy=</b><i>Proxy-URL</i>
549
</pre>
550
551
To stop using the proxy, do:
552
553
<pre>
554
<b>fossil setting proxy off</b>
555
</pre>
556
557
Or unset the environment variable. The fossil setting for the
558
HTTP proxy takes precedence over the environment variable and the
559
command-line option overrides both. If you have a persistent
560
proxy setting that you want to override for a one-time sync, that
561
is easily done on the command-line. For example, to sync with
562
a co-worker's repository on your LAN, you might type:
563
564
<pre>
565
<b>fossil sync http://192.168.1.36:8080/ --proxy off</b>
566
</pre>
567
568
<h2 id="links">Other Resources</h2>
569
570
<ul>
571
<li> <a href="./gitusers.md">Hints For Users With Prior Git Experience</a>
572
<li> <a href="./whyusefossil.wiki">Why You Should Use Fossil</a>
573
<li> <a href="./history.md">The History and Purpose of Fossil</a>
574
<li> <a href="./branching.wiki">Branching, Forking, and Tagging</a>
575
<li> <a href="./hints.wiki">Fossil Tips and Usage Hints</a>
576
<li> <a href="./permutedindex.html">Comprehensive Fossil Doc Index</a>
577
</ul>
578

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button