|
1
|
# 101 Reasons Why Fossil Is Better Than Git |
|
2
|
|
|
3
|
1. **Fossil comes as a single self-contained executable file**.<p> |
|
4
|
Install Fossil by copying "fossil" (or "fossil.exe") to some place |
|
5
|
on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting |
|
6
|
that one file. Uninstall by deleting that one file.<p> |
|
7
|
A Git installation requires hundreds of files. You want to use a |
|
8
|
package manager to install, upgrade, or uninstall Git. If you |
|
9
|
tinker with individual files of a Git installation, you run a high |
|
10
|
risk of messing things up. |
|
11
|
|
|
12
|
1. **Fossil comes with a built-in full-featured web interface**.<p> |
|
13
|
The Fossil web interface meets or exceeds the capabilities |
|
14
|
of GitHub, GitLab, Gitea, Forgejo, and similar. |
|
15
|
Some people think of Fossil as "GitHub-in-a-box". |
|
16
|
Git has "gitweb", but that CGI program |
|
17
|
is so limited and difficult to set up and use that few people |
|
18
|
even know it exists, so I do not count it |
|
19
|
for the purposes of this point. |
|
20
|
|
|
21
|
1. **You can run the Fossil web interface locally |
|
22
|
using the "fossil ui" command.**<p> |
|
23
|
Just type the command "fossil ui" from any Fossil checkout, |
|
24
|
or add an argument that is the name of a Fossil repository file |
|
25
|
or a directory that is the root of an open checkout |
|
26
|
and Fossil automatically brings up a new window with the |
|
27
|
Fossil web interface in your preferred web browser. |
|
28
|
This works seamlessly on all platforms. There is nothing |
|
29
|
extra to install. There is no configuration or setup. |
|
30
|
It just works. |
|
31
|
|
|
32
|
1. **The Fossil web interface shows a graphical timeline of changes.**<p> |
|
33
|
See, for example <https://sqlite.org/src/timeline> or |
|
34
|
<https://fossil-scm.org/home/timeline>. Similar timeline features |
|
35
|
for Git are available from the command-line for a local clone |
|
36
|
(for example using "gitk" or other third-party programs), but |
|
37
|
nothing with anything close to the capabilities of the Fossil |
|
38
|
timeline is available via a web interface, as far as I know.<p> |
|
39
|
Using the web interface, one can easily check on the status |
|
40
|
of a project when away from the office and without access to a clone |
|
41
|
of the repository. |
|
42
|
|
|
43
|
1. **The Fossil web interface view of a single check-in shows a |
|
44
|
context graph of all other directly connected check-ins.**<p> |
|
45
|
See the page for [check-in 59985724d71229bf](/info/59985724d71229bf) |
|
46
|
for example. The context graph shows four other check-ins: |
|
47
|
two direct descendants, one merge descendant, and one ancestor. |
|
48
|
This context graph is useful in understanding how a particular |
|
49
|
check-in fits into the history of the project. The context graph |
|
50
|
can also be used to step forwards or backwards in time, by |
|
51
|
clicking on the "check-in:" hash links for nearby check-ins. |
|
52
|
|
|
53
|
1. **The graphical timeline dynamically adjusts its layout as you resize |
|
54
|
your browser window.**<p> |
|
55
|
The server sends down an HTML page that contains (among other things) |
|
56
|
a JSON object that gives the basic structure of the |
|
57
|
timeline graph, then Javascript renders the graph. The JS code is |
|
58
|
small, does not use any third-party frameworks, and is (by default) |
|
59
|
appended to the HTML page. Except for a separate CSS file, the HTML |
|
60
|
is completely stand-alone. The local |
|
61
|
web browser isn't required to go gather lots of separate resources. |
|
62
|
|
|
63
|
1. **The graphical timeline works on a phone.**<p> |
|
64
|
The graph layout automatically compresses on a small display, and |
|
65
|
can seem a little cramped for a complex project. The timeline |
|
66
|
does look better on a desktop. Even so, the timeline display is |
|
67
|
functional on a phone and it is very convenient |
|
68
|
to be able to see what is happening on a project |
|
69
|
while away from the office and without access to a laptop. |
|
70
|
|
|
71
|
1. **The graphical timeline is bandwidth efficient.**<p> |
|
72
|
To display a timeline of recent activity on Fossil uses less |
|
73
|
than 5% of the bandwidth as GitHub. In a typical example, |
|
74
|
GitHub requires about 3.5MB of transfer to retrieve 56 different |
|
75
|
resources compared to 150KB for just one HTML file and one CSS file |
|
76
|
with Fossil. And for all that 3.5MB, GitHub only gives you a list |
|
77
|
of recent check-ins without any indication of the branching |
|
78
|
structure, whereas Fossil gives you an easy-to-read color-coded |
|
79
|
graph. |
|
80
|
|
|
81
|
1. **The Fossil web interface makes it easy to see a diff between |
|
82
|
any two check-ins with just a couple of clicks.**<p> |
|
83
|
On the timeline display, click on one node of the graph to |
|
84
|
select it (a red dot will appear in the center of the node) and |
|
85
|
then click on any other graph node, and Fossil will compute and |
|
86
|
display a diff between those two check-ins. (Usage hint: |
|
87
|
click the selected node a second time to deselect it.) |
|
88
|
|
|
89
|
1. **The Fossil web-based diff page shows the context of the two |
|
90
|
check-ins being diffed.**<p> |
|
91
|
At the top of the web-based diff is a graph that shows |
|
92
|
specifically the two check-ins being diffed and the context |
|
93
|
around them. |
|
94
|
[Example](/vdiff?from=052390edaf04a5f5&to=9b686daeeda7b4ca). |
|
95
|
This helps to reduce any confusion about what you are looking at. |
|
96
|
|
|
97
|
1. **In Fossil, a repository is distinct from a working checkout.**<p> |
|
98
|
A Fossil repository can be colocated with the working checkout, as |
|
99
|
they are required to be in Git. But most people keep the repository |
|
100
|
separate. One common pattern is to put all Fossil repositories in |
|
101
|
a single directory named $HOME/Fossils or $HOME/Museum and then open |
|
102
|
working checkouts against each repository wherever they are needed. |
|
103
|
|
|
104
|
1. **A single Fossil repository can support multiple working checkouts.** |
|
105
|
<p> |
|
106
|
Git has worktrees, but all worktrees checkouts must be on separate |
|
107
|
branches. Fossil allows multiple working checkouts on the same branch |
|
108
|
or even on the same check-in. One common pattern is to have one |
|
109
|
checkout that is being edited, and another that is a pristine, unedited |
|
110
|
version of the same check-in. This allows both to be compiled |
|
111
|
simultaneously for performance comparison, or to step through both |
|
112
|
binaries in two separate "gdb" sessions to hunt down a bug. |
|
113
|
|
|
114
|
1. **A Fossil repository is a single disk file, not a directory |
|
115
|
hierarchy.**<p> |
|
116
|
You can "mv" a Fossil repository to a new place. You can "scp" |
|
117
|
a Fossil repository to another machine. It is just a file, |
|
118
|
specifically an SQLite database file. You can name a Fossil |
|
119
|
repository anything you like. The usual convention is to give the |
|
120
|
repository file a ".fossil" suffix, but that is not required. |
|
121
|
|
|
122
|
1. **Fossil does not have a staging area**.</p> |
|
123
|
A staging area does not add new capabilities, it only adds |
|
124
|
complication. (Partial commits |
|
125
|
are accomplished in Fossil simply by listing the subset of files to |
|
126
|
be committed on the "fossil commit" command line.) |
|
127
|
The staging area complicates the mental model |
|
128
|
of the project that Git users need to keep up with, forcing the |
|
129
|
developer to spend more effort thinking about the version control |
|
130
|
system and hence less time thinking about the project they are |
|
131
|
working on. |
|
132
|
|
|
133
|
1. **Fossil remembers where all your repositories and working |
|
134
|
checkouts are located.**<p> |
|
135
|
This and other information (such as all your global settings) |
|
136
|
is stored in a per-user database file |
|
137
|
at $HOME/.config/fossil.db on unix or in %LOCALAPPDATA%/_fossil on |
|
138
|
Windows. Fossil creates and manages that file automatically. |
|
139
|
The user never has to know the file even exists. If you |
|
140
|
move or rename repositories or checkouts, the database will get |
|
141
|
temporarily out of sync with reality, but Fossil will automatically |
|
142
|
fix the database the next time you do anything with the file or |
|
143
|
checkout that was moved or renamed.<p> |
|
144
|
You can get a list of repositories using the |
|
145
|
"<tt>fossil all ls</tt>" command, or a list of open |
|
146
|
checkouts using "<tt>fossil all ls --ckout</tt>". |
|
147
|
|
|
148
|
1. **Fossil lets you bring up a web-based UI that shows all of |
|
149
|
your repositories at once.**<p> |
|
150
|
Run the command "<tt>fossil ui /</tt>" and your |
|
151
|
default web browser will pop up a new tab that lists all of your |
|
152
|
repositories together with the |
|
153
|
associated project name and how recently that repository was modified. |
|
154
|
Click on links to bring up repository-specific web-pages. Or click |
|
155
|
on column headers to sort by that column.<p> |
|
156
|
If you are like me and have hundreds of repositories on your desktop |
|
157
|
system, this feature makes it easier to keep track of them all, or |
|
158
|
just to remember what you called each one. |
|
159
|
Are you on an infrequently used travel laptop and forgot where you |
|
160
|
put a particular repository, this feature helps you find it. |
|
161
|
|
|
162
|
1. **Fossil lets you quickly find uncommitted changes across all of |
|
163
|
your open checkouts.**<p> |
|
164
|
Simply run "<tt>fossil all changes</tt>" to get a quick |
|
165
|
summary of every checkout on your local machine that needs a commit. |
|
166
|
|
|
167
|
1. **Fossil lets you sync all of the changes in all of your local |
|
168
|
repositories to their remotes, with a single command.**<p> |
|
169
|
Run "<tt>fossil all sync</tt>" and all your local |
|
170
|
repositories will sync up. This is useful, for example when |
|
171
|
taking a laptop off-network. Before disconnecting, you sync |
|
172
|
all of your repositories. Fossil itself keeps track of all |
|
173
|
of your repositories, so you cannot accidentally forget one or two. |
|
174
|
While off-network, you might commit changes to one or |
|
175
|
more of those repositories. Once you reconnect, you simply |
|
176
|
run "<tt>fossil all sync</tt>" again to push out your edits |
|
177
|
back to the community. |
|
178
|
|
|
179
|
1. **Fossil allows multiple check-ins to have the same tag.**<p> |
|
180
|
For example, on the SQLite project, every release is tagged with |
|
181
|
"release". |
|
182
|
|
|
183
|
1. **The Fossil timeline can show all check-ins with a specific tag.**<p> |
|
184
|
For example, to see all SQLite releases visit |
|
185
|
<https://sqlite.org/src/timeline?t=release> or to see all |
|
186
|
Fossil releases go to |
|
187
|
<https://fossil-scm.org/home/timeline?t=release>. |
|
188
|
|
|
189
|
1. **Fossil has a built-in wiki**.<p> |
|
190
|
Wiki pages are stored in the same repository file as your code, so that |
|
191
|
they push, pull, sync, and clone together with your code. |
|
192
|
<p> |
|
193
|
Git does not itself have a wiki. The various Git forges usually add |
|
194
|
wikis, and store the wiki content in Git, though in a separate |
|
195
|
Git repository. There is no option to store the wiki and source code |
|
196
|
together such that they clone and sync as one, in the Git ecosystem. |
|
197
|
|
|
198
|
1. **Fossil can associate a wiki page with a particular check-in.**<p> |
|
199
|
Rather than including an oversized check-in comment on an |
|
200
|
important check-in (such as the merge of a big new feature), Fossil |
|
201
|
allows you to assign a wiki page to that check-in. That wiki page |
|
202
|
is shown as part of the check-in information in the web interface. |
|
203
|
See, for example, the "About" section of |
|
204
|
[SQLite check-in 2019-11-21T18:28:44.463Z](https://sqlite.org/src/info/2019-11-21T18:28:44.463Z). |
|
205
|
The wiki page associated with a check-in can be created and revised |
|
206
|
after the check-in is committed and pushed. This feature can be used |
|
207
|
to add notes or bug reports that occur long after the |
|
208
|
check-in itself has been inserted into the DAG. |
|
209
|
|
|
210
|
1. **Fossil can associate a wiki page with a particular branch.**<p> |
|
211
|
You can create a wiki page for a branch that documents the purpose |
|
212
|
of that branch. The wiki page can be displayed separately (like any |
|
213
|
other wiki page) but is also displayed automatically at the top of |
|
214
|
every timeline for that branch. See, for example, |
|
215
|
<https://sqlite.org/src/timeline?r=autosetup>. |
|
216
|
|
|
217
|
1. **Fossil keeps track of historical branch names.**<p> |
|
218
|
Git does not track branches. Git only names each leaf |
|
219
|
of the DAG and infers branches based on the names of leaves. |
|
220
|
Fossil actually remembers the name of branches. |
|
221
|
For example, suppose a customer asks |
|
222
|
"Whatever became of that setlk-snapshot-fix branch you |
|
223
|
started last year?" That branch still exists and you can |
|
224
|
[see it on GitHub](https://github.com/sqlite/sqlite/commits/setlk-snapshot-fix) |
|
225
|
and [in Fossil](https://sqlite.org/src/timeline?r=setlk-snapshot-fix). |
|
226
|
Notice, though, that GitHub does not show how the branch was resolved. |
|
227
|
(Aside: Also notice how much faster Fossil renders!) |
|
228
|
Fossil clearly shows that the branch ended up being merged into trunk. |
|
229
|
GitHub just shows us all ancestors of the leaf node labeled |
|
230
|
"setlk-snapshot-fix", including ancestors that were in other branches |
|
231
|
that got merged in, and ancestors that predate the founding of the |
|
232
|
setlk-snapshot-fix branch. |
|
233
|
<p> |
|
234
|
GitHub is unable to show you the check-ins of branch setlk-snapshot-fix |
|
235
|
only. There are other third-party tools that will show you that, I am |
|
236
|
told, but they all require a local clone of the repository. Apparently |
|
237
|
there is no way to see this information in a web browser using Git, |
|
238
|
with or without third-party tools. |
|
239
|
|
|
240
|
1. **Fossil has a built-in bug tracking system.**.<p> |
|
241
|
Tickets are stored in the repository together with source code and |
|
242
|
push/pull/sync the same as the code. The ticket system is configurable |
|
243
|
and distributed. Repository administrators can determine what |
|
244
|
fields appear in tickets and what users are allowed to create, |
|
245
|
edit, or moderate tickets. |
|
246
|
|
|
247
|
1. **Fossil allows multiple branches with the same name.**<p> |
|
248
|
As an example, the SQLite project has multiple branches |
|
249
|
named "experimental" |
|
250
|
<https://sqlite.org/src/timeline?r=experimental> and many |
|
251
|
others named "mistake" |
|
252
|
<https://sqlite.org/src/timeline?r=mistake>. |
|
253
|
Another example: |
|
254
|
[the empty-table-optimizations branch(es)](https://sqlite.org/src/timeline?r=empty-table-optimizations) |
|
255
|
which was initially merged to trunk and closed |
|
256
|
on 2025-07-02, but then reopened and continued with more enhancements |
|
257
|
until it was merged again on 2025-07-08. |
|
258
|
|
|
259
|
1. **Fossil allows both legacy SHA1 hashes and newer SHA3-256 hashes |
|
260
|
in the same repository.**<p> |
|
261
|
Both Fossil and Git started out using only SHA1 hashes. But when the |
|
262
|
[SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) |
|
263
|
against SHA1 was published on 2017-02-23, the need to migrate to a |
|
264
|
stronger hash algorithm was recognized. Fossil added the ability |
|
265
|
to use SHA3-256 as an alternative on 2017-03-01 (six days after the |
|
266
|
SHAttered attack was first published). |
|
267
|
SHA3-256 is now the default for all new repositories and check-ins |
|
268
|
in Fossil, though older check-ins that occurred |
|
269
|
prior to SHAttered can still use their original SHA1 hash. Hence, |
|
270
|
no repositories had to be rebuilt and no hyperlinks were broken.<p> |
|
271
|
In contrast, after nine years, a Git repository can still only |
|
272
|
support one hash algorithm at a time. |
|
273
|
Newer Git repositories are able to use SHA2, though the default |
|
274
|
is still SHA1. |
|
275
|
|
|
276
|
1. **Fossil allows check-ins to be identified by timestamp**<p> |
|
277
|
The canonical name for a check-in is its hash. Both Git and Fossil |
|
278
|
allow a check-in to be identified by any unique prefix of its hash. |
|
279
|
But only Fossil allows a check-in to also be identified by its |
|
280
|
timestamp. The names "2026-02-02T16:03:24.852Z" and "fdebbedbd9a99165" |
|
281
|
both refer to |
|
282
|
[the same check-in](https://sqlite.org/src/info/fdebbedbd9a99165), |
|
283
|
but the first one has the advantage of giving some time |
|
284
|
context rather than just being a seemingly random sequence of hexadecimal |
|
285
|
digits. It is possible that two or more check-ins can have the same |
|
286
|
timestamp, in which case the timestamp would be ambiguous. And a |
|
287
|
check-in timestamp can be changed after it is committed, by using |
|
288
|
a special tag. So timestamp identifiers do not have the uniqueness |
|
289
|
and stability guarantees as hash identifiers, but they are available |
|
290
|
as an option and are often useful. |
|
291
|
|
|
292
|
1. **Fossil has a built-in forum.**<p> |
|
293
|
The forum content is replicated via push, pull, sync, and clone just like |
|
294
|
source code. Forum posts can be enabled per user or for all users or |
|
295
|
for all users and anonymous passers-by. Some users can be appointed |
|
296
|
as moderators and posts from untrusted users can be held for |
|
297
|
moderation. |
|
298
|
<p> |
|
299
|
The [Fossil Forum](https://fossil-scm.org/forum), the |
|
300
|
[SQLite User Forum](https://sqlite.org/forum), and the |
|
301
|
[SQLite Bugs Forum](https://sqlite.org/bugs) are all forums |
|
302
|
set up for specific purposes and deliberately kept separate |
|
303
|
from source code. But other projects such as |
|
304
|
[Pikchr](https://pikchr.org/) comingle their forum and the source code |
|
305
|
in the same repository. Thus when you clone the |
|
306
|
Pikchr source repository, you also get all the Forum history. |
|
307
|
|
|
308
|
1. **Fossil makes it easy to set up a project website using CGI.**<p> |
|
309
|
If you have an internet-facing machine running a CGI-capable web |
|
310
|
server, you can stand up a complete self-hosting project |
|
311
|
website with a two-line CGI script. The canonical |
|
312
|
[Fossil website](https://fossil-scm.org/home) is really just such |
|
313
|
a CGI script. When you clone the Fossil source code, you don't |
|
314
|
just get the code, you get the entire website. |
|
315
|
<p> |
|
316
|
The CGI script used to run the Fossil website looks |
|
317
|
approximately like this: |
|
318
|
<pre> |
|
319
|
#!/usr/bin/fossil |
|
320
|
repository: /Fossils/fossil.fossil</pre> |
|
321
|
You can, of course, also create a self-hosting website using |
|
322
|
GitLab or Forgejo or similar, but the setup and maintenance is |
|
323
|
somewhat more involved. You'll also probably need a bigger machine |
|
324
|
if you are using GitLab, whereas a Fossil website |
|
325
|
works fine on a 2GiB Raspberry PI or a $6/month VPS. |
|
326
|
I am told that Gitea and Forgejo also work well on a small machine. |
|
327
|
No direct size and performance comparisons between Gitea/Forgejo and |
|
328
|
Fossil have been made, as of this writing. |
|
329
|
|
|
330
|
1. **Fossil makes it easy to set up a project website using SCGI.**<p> |
|
331
|
CGI is easier, but some web servers (ex: Nginx) do not support CGI. |
|
332
|
If you are using such a web server, you can also run a Fossil |
|
333
|
server using SCGI. See the |
|
334
|
[on-line Fossil SCGI documentation](/doc/trunk/www/scgi.wiki) |
|
335
|
for details. |
|
336
|
|
|
337
|
1. **Fossil makes it easy to set up a project website behind a |
|
338
|
reverse proxy.**<p> |
|
339
|
Simply run a [Fossil HTTP server](/doc/trunk/www/server/any/none.md) |
|
340
|
and have your reverse proxy redirect requests to this new Fossil |
|
341
|
server. You can also set up the Fossil server to work over named |
|
342
|
pipes rather than a loopback, if your reverse proxy supports that. |
|
343
|
|
|
344
|
1. **Fossil makes it easy to set up a project website without |
|
345
|
using any web server at all.**<p> |
|
346
|
The [fossil server command](/help/server) includes a --cert |
|
347
|
option with which you can specify a TLS cert for encrypted |
|
348
|
communication, and with the option, Fossil will accept ordinary |
|
349
|
HTTPS requests from the open internet. There is no need to |
|
350
|
install and configure a separate web server. Hence, the only |
|
351
|
software you need to stand up a project website using Fossil is |
|
352
|
the stand-alone "fossil" binary. |
|
353
|
|
|
354
|
1. **A single Fossil server is able to host multiple projects.**<p> |
|
355
|
By default, each Fossil server provides content for a single |
|
356
|
repository. But you can launch a Fossil server that hosts |
|
357
|
multiple repositories by putting all those repositories in a |
|
358
|
directory and giving the directory name as the object to serve |
|
359
|
instead of the repository name. For this mode of operation, |
|
360
|
the repositories must be named with the "<tt>.fossil</tt>" file |
|
361
|
suffix. Individual projects have URLs that begin with the |
|
362
|
repository base name, omitting the "<tt>.fossil</tt>" suffix. |
|
363
|
|
|
364
|
1. **Fossil automatically pushes after each commit, by default**.<p> |
|
365
|
The [autosync setting](/help/autosync), which defaults to "on", causes |
|
366
|
every commit to automatically push to the default remote. This helps |
|
367
|
to keep the remote up-to-date and helps all the developers working on |
|
368
|
the project keep up with what other developers are doing. |
|
369
|
<p> |
|
370
|
Long-time Git users might cringe at autosync, thinking that this |
|
371
|
could cause problems if another developer commits ahead of you. |
|
372
|
True enough, that would cause headaches for Git, but it does not |
|
373
|
create problems for Fossil. |
|
374
|
The worst that could happen is that the branch will fork. Fossil |
|
375
|
will usually detect an impending fork and warn you. |
|
376
|
But even if you don't get the warning (due to a race) or even if you |
|
377
|
override the warning and force the commit anyhow, a fork on a branch |
|
378
|
in Fossil is harmless. It shows cleanly in the timeline and |
|
379
|
is easily resolved. So while autosync might cause issues with Git, |
|
380
|
it is harmless when using Fossil. Since forks are harmless, |
|
381
|
the benefits of autosync far outweigh the risks. |
|
382
|
|
|
383
|
1. **Fossil supports embedded Pikchr in Wiki and in the Forum.**</p> |
|
384
|
[Pikchr](https://pikchr.org/) is a |
|
385
|
[PIC-like](https://en.wikipedia.org/wiki/Pic_language) markup language |
|
386
|
for diagrams. Pikchr is designed for use with Markdown, but also works |
|
387
|
with other markup languages. |
|
388
|
The diagrams that appear in the Fossil documentation are |
|
389
|
all drawn using Pikchr. |
|
390
|
|
|
391
|
1. **Fossil has a Pikchr sandbox for experimenting with Pikchr scripts.** |
|
392
|
<p> |
|
393
|
The [pikchrshow page](/pikchrshow) allows users to experiment with and |
|
394
|
refine their Pikchr diagrams prior to copy/pasting them into their |
|
395
|
documents. |
|
396
|
|
|
397
|
1. **The Fossil web interface supports "embedded documentation"**</p> |
|
398
|
See the [Project Documentation](/doc/trunk/www/embeddeddoc.wiki) page |
|
399
|
for details. Markdown, Wiki, plain-text, and HTML files in the |
|
400
|
source tree can be rendered and used as documentation pages. This |
|
401
|
is how all of the documentation files for Fossil itself are created. |
|
402
|
|
|
403
|
1. **Fossil can easily host an entire project website, using only the |
|
404
|
repository as the backing store.**<p> |
|
405
|
The embedded documentation and wiki features allow you to write |
|
406
|
web pages. The unversioned file feature gives you space to put |
|
407
|
precompiled binaries or other transient and/or derived resources |
|
408
|
without contaminating the source tree. The Forum and Ticket features |
|
409
|
provide for community discussion and bug tracking. Fossil provides |
|
410
|
everything you need to host a complete software project website. |
|
411
|
Indeed, the |
|
412
|
[canonical Fossil website](https://fossil-scm.org/home) is just |
|
413
|
an instance of Fossil running on the self-hosting Fossil repository. |
|
414
|
If you clone the Fossil self-hosting repository, you don't get just |
|
415
|
code - you get the entire website. (Exception: |
|
416
|
[Fossil Forum](https://sqlite.org/forum) is hosted separately using |
|
417
|
a separate Fossil repository, so you'd actually need to clone that |
|
418
|
one too, in order to get the whole website.) |
|
419
|
|
|
420
|
1. **Using Fossil, backing up your project website is just a sync.**<p> |
|
421
|
If you host your entire project website in a Fossil repository, |
|
422
|
as Fossil itself does, then backing up that website is as simple |
|
423
|
as creating a clone and keeping the clone synced. |
|
424
|
|
|
425
|
1. **Fossil will render uncommitted changes to embedded documentation.** |
|
426
|
<p> |
|
427
|
Using the "<tt>fossil ui</tt>" and the |
|
428
|
[/doc/VERSION/FILE](/help/www/doc) webpage, if the VERSION is the |
|
429
|
special keyword "ckout", then the content is taken from the local |
|
430
|
checkout rather than from the repository. This allows you to edit |
|
431
|
embedded documentation files and then press Reload on your browser |
|
432
|
to see how they will look and work on the |
|
433
|
actual website without having to commit. |
|
434
|
|
|
435
|
1. **Fossil has a wiki sandbox for experimenting with markup.**</p> |
|
436
|
The [wiki sandbox](/wikiedit?name=Sandbox) allows users to experiment |
|
437
|
with Markdown or other text markup languages supported by Fossil, |
|
438
|
without making permanent changes to the repository. |
|
439
|
|
|
440
|
1. **Fossil supports interwiki hyperlinks.**<p> |
|
441
|
Core Git does not have any kind of markup language. Check-in comments |
|
442
|
in Git are always displayed verbatim. But wrappers such as GitHub, |
|
443
|
GitLab, Gitea, Forgejo, and similar generally support some variant |
|
444
|
of Markdown. However, none of these system support links (apart from |
|
445
|
full URLs) to other wiki systems. Fossil does support interwiki links |
|
446
|
using the syntax "<tt>remote:path</tt>". So, for example, a check-in |
|
447
|
in the SQLite source repository (<https://sqlite.org/src>) that wants |
|
448
|
to reference a bug report (perhaps because it fixes the bug) can |
|
449
|
include a link of the form "<tt>bugs:/info/</tt><i>HASH</i>" to |
|
450
|
reference that bug. The source repository knows that "bugs:" refers |
|
451
|
to the [SQLite Bug Forum](https://sqlite.org/bugs) and completes the |
|
452
|
link accordingly. |
|
453
|
<p> |
|
454
|
Interwiki links are important because (1) they help keep hyperlinks |
|
455
|
shorter, and (2) if the target wiki |
|
456
|
ever moves to a new domain, all the links automatically adjust |
|
457
|
by changing a single server setting, and (3) clones can have |
|
458
|
different mappings for interwiki links, so that (for example) |
|
459
|
a "bugs:" link in a clone of the source repository can map to |
|
460
|
a clone of the Bugs Forum repository rather than the canonical |
|
461
|
Bugs Forum. |
|
462
|
|
|
463
|
1. **Fossil has a built-in chat server.**<p> |
|
464
|
Users with appropriate permissions (usually just registered |
|
465
|
developers, not anonymous passers-by) can bring up a web-based chat |
|
466
|
window on any Fossil web-server instance. This feature allows |
|
467
|
geographically distributed developers to collaborate interactively, |
|
468
|
without having to involve a third-party chat provider such as Slack. |
|
469
|
Nothing needs to be configured in order to activate Chat, other |
|
470
|
than enabling the Chat privilege on the permission bits of the |
|
471
|
users whom you want to have access to Chat. |
|
472
|
|
|
473
|
1. **Fossil chat can be configured to send automatic notifications |
|
474
|
when changes occur in the repository.**<p> |
|
475
|
This helps developers keep up with what is happening in the repository. |
|
476
|
The chat window beeps (or not, configurable individually by each user) |
|
477
|
when new messages arrive, as an alert. |
|
478
|
|
|
479
|
1. **The Fossil Chat system has hooks that allow external subsystems |
|
480
|
to inject chat messages.**<p> |
|
481
|
The SQLite developers use this to get notifications of testing |
|
482
|
failures from our fuzz testing infrastructure. It could also |
|
483
|
be leveraged to get chat notifications of CI/CD problems. |
|
484
|
|
|
485
|
1. **Fossil chat is able to send attachments.**<p> |
|
486
|
When the SQLite developers are working collaboratively on a problem |
|
487
|
(while working, literally, on three different continents) we easily |
|
488
|
send patches or diffs to one another over Chat. |
|
489
|
|
|
490
|
1. **Fossil supports hyperlinks in check-in comments.**<p> |
|
491
|
Check-in comments need not be just verbatim text (though they can |
|
492
|
be, depending on repository settings). By default, check-in |
|
493
|
comments can contain hyperlinks, including hyperlinks to |
|
494
|
wiki pages, prior check-ins, forum posts, and interwiki hyperlinks. |
|
495
|
|
|
496
|
1. **Fossil supports hyperlink back references**<p> |
|
497
|
If the check-in comment for a newer commit contains a hyperlink |
|
498
|
back to an older commit, then when the web interface shows the |
|
499
|
details of the older commit, it also provides a forward |
|
500
|
reference to the newer commit. |
|
501
|
|
|
502
|
1. **Fossil supports a graphical timeline display of a bisect.**<p> |
|
503
|
[For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). |
|
504
|
This is not strictly necessary to make effective use of bisect, but |
|
505
|
the graphical display does seem to help with situational awareness. |
|
506
|
|
|
507
|
1. **Fossil can show you the first release in which a particular |
|
508
|
check-in appears, with a single mouse click.**<p> |
|
509
|
You have to configure the repository by giving it the name of the |
|
510
|
tag that you use to mark releases, using the |
|
511
|
[path-to-tag setting](/help/path-to-tag). Suppose you use the tag |
|
512
|
name "release". Once you do that, then |
|
513
|
when you are looking at the "info" page for a check-in, a link |
|
514
|
named "path-to-release" appears in the overview section, and if |
|
515
|
you click on that link, it brings up a new graph showing the |
|
516
|
shortest path from that check-in to the next descendant check-in |
|
517
|
tagged with "release". |
|
518
|
<p> |
|
519
|
Example: On the info page at |
|
520
|
<https://sqlite.org/src/info/b1d7123bc619e3cb>, in the Overview |
|
521
|
section at the top, to the right of the "Timelines:" label, you |
|
522
|
will see the "path-to-release" link. Click that link to take you |
|
523
|
to a page showing an abbreviated path from the original check-in |
|
524
|
to the first "release" check-in that contains the change. To |
|
525
|
see the full path, uncheck the "Brief" checkbox near the top of the page. |
|
526
|
<p> |
|
527
|
This feature is useful for when you bisect to find a bug, or a bug |
|
528
|
fix, and you want to know the first release in which that bug or bug fix |
|
529
|
appeared. |
|
530
|
|
|
531
|
1. **Fossil allows you to revise a check-in comment without |
|
532
|
rewriting history.**<p> |
|
533
|
If you find a typo or other error in an historical check-in comment, |
|
534
|
you can fix the problem in Fossil without having to rewrite all |
|
535
|
subsequent history. The Fossil file format allows you to set |
|
536
|
a special tag on the check-in that provides revised comment text. |
|
537
|
The new tag causes both the command-line display |
|
538
|
and the web interface to show the revised check-in comment rather |
|
539
|
that the original. Note that the original check-in comment is |
|
540
|
preserved, so there is still an immutable audit trail. But for |
|
541
|
common use cases, only the newer revised comment is shown. |
|
542
|
<p> |
|
543
|
If you are using the web interface and if you have check-in privilege |
|
544
|
on the repository, then on the /info page for the check-in, under |
|
545
|
the "Overview" section, to the right of "Other Links:", there is |
|
546
|
an "edit" link that will take you to a page that lets you change |
|
547
|
the check-in comment from the web interface. This is the easiest |
|
548
|
way to edit a check-in comment. |
|
549
|
<p> |
|
550
|
See [Fossil check-in b63d654041](/info/b63d65404) for an |
|
551
|
example. The original comment is shown in the "Overview" |
|
552
|
section of the check-in details, but the revised comment is shown |
|
553
|
in the timeline. |
|
554
|
|
|
555
|
1. **Fossil allows you to revise a check-in timestamp without |
|
556
|
rewriting history.**<p> |
|
557
|
When generating a new check-in, Fossil uses the current time on the |
|
558
|
system where the commit is occurring. But if the system clock on |
|
559
|
that system is incorrect, that can lead to a check-in with an |
|
560
|
inaccurate timestamp. It can be the case that prior check-ins |
|
561
|
have later timestamps or that subsequent check-ins can have |
|
562
|
earlier timestamps, resulting in goofy-looking "time-warps" in the |
|
563
|
timeline. This can be fixed by add a timestamp correction tag |
|
564
|
to the faulty check-in to fix the timestamp. |
|
565
|
<p> |
|
566
|
If you are using the web interface and if you have check-in privilege |
|
567
|
on the repository, then on the /info page for the check-in, under |
|
568
|
the "Overview" section, to the right of "Other Links:", there is |
|
569
|
an "edit" link that will take you to a page that lets you change |
|
570
|
the timestamp for a check-in from the web interface. This is the |
|
571
|
easiest way to make the change. |
|
572
|
|
|
573
|
1. **Fossil allows you to move a check-in to a new branch without |
|
574
|
rewriting history.**<p> |
|
575
|
If you mistakenly commit to the wrong branch, you can move that |
|
576
|
check-in to a new branch by attaching a special tag. |
|
577
|
Note, however, that this will also move all subsequent check-ins |
|
578
|
to that same new branch. |
|
579
|
<p> |
|
580
|
In the SQLite and Fossil projects, when developers mistakenly commit |
|
581
|
on the wrong branch, the usual way we fix that is to move the |
|
582
|
mistaken check-in to a branch named "mistake". Sometimes we also |
|
583
|
set the "hidden" tag on that check-in as well, so that it does not |
|
584
|
show up on ordinary timelines (though it is still part of the |
|
585
|
immutable audit history and is visible with special options). |
|
586
|
Then we just cherrypick the check-in onto the correct branch. |
|
587
|
<p> |
|
588
|
If you are using the web interface and if you have check-in privilege |
|
589
|
on the repository, then on the /info page for the check-in, under |
|
590
|
the "Overview" section, to the right of "Other Links:", there is |
|
591
|
an "edit" link that will take you to a page that lets you move the |
|
592
|
check-in to a new branch from the web interface. You can also do this |
|
593
|
from the Fossil command-line, but the web interface is easier and less |
|
594
|
error prone. |
|
595
|
|
|
596
|
1. **Fossil supports unversioned files**.<p> |
|
597
|
[Unversioned Files](/doc/trunk/www/unvers.wiki) are files held |
|
598
|
in the repository but which are not versioned and which are not |
|
599
|
synced by default. Unversioned files are used by Fossil itself |
|
600
|
to store [Precompiled Binaries of Fossil](/uv/download.html). |
|
601
|
<p> |
|
602
|
Unversioned content is not synced *by default*. But unversioned |
|
603
|
files will sync if you add the -u option to the |
|
604
|
[fossil sync command](/help/sync). |
|
605
|
There is also the [fossil uv sync](/help/uv) command. |
|
606
|
|
|
607
|
1. **Fossil automatically selects check-in background colors according to |
|
608
|
the branch that each check-in occurs on.**<p> |
|
609
|
This helps to make the timeline easier to read at a glance, by |
|
610
|
clearly showing which check-ins are on which branches. Developers |
|
611
|
can assign specific colors to branches either when the branch is |
|
612
|
first created, or after the branch has been running for a while. |
|
613
|
But experience teaches us that it is better to just let the web |
|
614
|
interface pick the branch colors automatically. The color is |
|
615
|
derived from a hash of the branch name. |
|
616
|
|
|
617
|
1. **The Fossil web interface contains a page that allows you to |
|
618
|
preview what colors Fossil will choose for branch names.**<p> |
|
619
|
On the [/hash-color-test page](/hash-color-test), one can enter |
|
620
|
candidate branch names and see in advance what colors Fossil will |
|
621
|
pick for that branch name. This seems like cheating, but I will |
|
622
|
admit that I do this myself, sometimes... |
|
623
|
|
|
624
|
1. **The Fossil web interface timeline can be asked to pick check-in |
|
625
|
colors using the name of the committer, rather than the branch |
|
626
|
name.**<p> |
|
627
|
Simply add the "ubg" query parameter (mnemonic: User BackGround) and |
|
628
|
the check-in colors will be determined by the committer login name |
|
629
|
rather than the branch name or any preselected color name. This |
|
630
|
results in a timeline that gives the reader a clearer view of who is |
|
631
|
making changes. |
|
632
|
[Example](/timeline?n=200&y=ci&ubg). |
|
633
|
|
|
634
|
1. **Fossil tracks cherrypick merges.**<p> |
|
635
|
Cherrypicks are recorded as part of the underlying |
|
636
|
[Fossil file format](/doc/trunk/www/fileformat.wiki). |
|
637
|
Cherrypicks appear on the timeline as thin dashed lines. |
|
638
|
|
|
639
|
1. **Fossil draws arrows pointing forwards in time.**<p> |
|
640
|
Forward-pointing arrows are more intuitive than arrows |
|
641
|
that point backwards in time, like Git uses. Yes, I am aware |
|
642
|
that the underlying implementation of Git has pointers going from child |
|
643
|
to parent, and thus must necessarily go backwards in time. Fossil |
|
644
|
has the same pointers. But just because the *implementation* |
|
645
|
points backwards in time does not mean that the *user interface* |
|
646
|
needs to do the same. Fossil flips those pointers around so that |
|
647
|
they make more sense from the perspective of the human reader. |
|
648
|
|
|
649
|
1. **Fossil implements some unix-like shell commands to use as |
|
650
|
substitutes on systems that don't have them or that have inferior |
|
651
|
implementations.**<p> |
|
652
|
For example the "fossil system ls" command works like the standard |
|
653
|
"ls" command on unix. It doesn't support all the options that a typical |
|
654
|
"ls" implementation supports on Linux, but it is still way better than |
|
655
|
having to run "dir". Other substitute commands include |
|
656
|
"date", "pwd", "stty", "unzip", "which", and "zip". Probably |
|
657
|
more will be added as needs arise. Having ready access to these |
|
658
|
commands built into the standalone Fossil binary makes working on |
|
659
|
non-Linux platforms more comfortable for unix geeks, and saves having |
|
660
|
to hunt around and install system-specific alternatives. |
|
661
|
|
|
662
|
1. **Fossil can copy all uncommitted changes from a checkout on a |
|
663
|
remote system over to a checkout on the local machine.**<p> |
|
664
|
The command is [fossil patch pull](/help/patch). It contacts the |
|
665
|
remote system via SSH, updates its local checkout to the same baseline |
|
666
|
as is found on the remote, then pulls over a minimal set of diffs and |
|
667
|
applies them.<p> |
|
668
|
This is very useful in pre-commit testing. For example, if you have |
|
669
|
a big change on your desktop, and you want to test it before |
|
670
|
committing, on multiple platforms, you can ssh over to those other |
|
671
|
platforms and run "fossil patch pull ... && make test". When working |
|
672
|
on SQLite, I will typically do that on a remote Mac, a remote |
|
673
|
Win11 machine, and on a 32-core remote Linux machine that runs |
|
674
|
faster than my desktop. |
|
675
|
|
|
676
|
1. **Fossil can push uncommitted changes to a checkout on another |
|
677
|
machine.**<p> |
|
678
|
This is the same as the previous but in reverse. It is used, for |
|
679
|
example, to push proposed changes up to a secure sandbox to be |
|
680
|
reviewed by Claude/Codex/Copilot prior to commit. The sandbox is |
|
681
|
not able to pull, for security reasons, but it can accept a push. |
|
682
|
|
|
683
|
1. **Fossil lets you set up aliases for remote checkouts with which |
|
684
|
you commonly push or pull.**<p> |
|
685
|
My desktop is named "r21" and I normally do SQLite development |
|
686
|
work in the directory ~/sqlite/sqlite. If I have uncommitted |
|
687
|
changes that I want to test on Windows, I SSH over to the Win11 |
|
688
|
machine then run commands like:<pre> |
|
689
|
fossil patch pull r21:sqlite/sqlite -f |
|
690
|
make clean test</pre> |
|
691
|
But typing in "r21:sqlite/sqlite" can be tedious and error-prone, |
|
692
|
maybe not so much in this particular example but definitely the |
|
693
|
case for longer hostnames and subdirectory paths. Fortunately, |
|
694
|
Fossil allows us to define patch alias. On my Win11 machine, |
|
695
|
the alias named "@" is defined as "r21:sqlite/sqlite" and so I |
|
696
|
can get by with typing just:<pre> |
|
697
|
fossil patch pull @ -f</pre> |
|
698
|
(Aside: the -f option tells the command to first "revert" any |
|
699
|
uncommitted changes currently in the checkout prior to pulling |
|
700
|
over the new ones from r21:sqlite/sqlite. Without that option, the |
|
701
|
changes would be merged.) |
|
702
|
|
|
703
|
1. **Fossil allows you to view uncommitted changes on a remote machine |
|
704
|
in a web browser over SSH.**<p> |
|
705
|
Suppose you have some edits on a remote, headless machine and you |
|
706
|
would like to review those changes. Fossil lets you see those |
|
707
|
changes using a command like:<pre> |
|
708
|
fossil ui remote:path/to/checkout</pre> |
|
709
|
Substitute the name of your remote and the path to the checkout |
|
710
|
on the remote, of course.<p> |
|
711
|
The way this works is that Fossil opens an SSH connection to the |
|
712
|
remote machine that runs [fossil server](/help/server) on the |
|
713
|
remote and that tunnels the HTTP content back through the SSH connection |
|
714
|
to your desktop. At the same time, Fossil brings up your default |
|
715
|
web browser and points it to the local end of your SSH tunnel. |
|
716
|
That's a lot of network plumbing, but Fossil handles it all |
|
717
|
automatically, so that you the developer don't need to think about it. |
|
718
|
|
|
719
|
1. **Fossil lets you browse a repository on a remote, headless machine |
|
720
|
over an SSH connection.**<p> |
|
721
|
Just run "<tt>fossil ui remote:path/to/repository</tt>" (substituting |
|
722
|
in the name of the remote machine and the path to the repository you |
|
723
|
want to browse, of course) and Fossil will pop up a new page on your |
|
724
|
default web browser (on your desktop!) that is connected over an |
|
725
|
SSH tunnel to that remote repository. |
|
726
|
|
|
727
|
1. **Fossil lets you see all repositories on a remote, headless machine |
|
728
|
all at once, over SSH.**<p> |
|
729
|
The command is "<tt>fossil ui remote:/</tt>". Substitute the name of |
|
730
|
the remote machine, of course. The special pathname "/" indicates to |
|
731
|
Fossil that you want to view all of the repositories on that machine. |
|
732
|
It causes Fossil to consult the $HOME/.config/fossil.db file |
|
733
|
(or %LOCALAPPDATA%/_fossil on Windows) to find the locations of all |
|
734
|
repositories on the remote machine, then bring up a web page listing |
|
735
|
all those repositories. Links on that initial page let you explore |
|
736
|
deeper into the details of each repository. |
|
737
|
|
|
738
|
1. **The Fossil web interface supports multiple timeline formats, to |
|
739
|
accommodate personal tastes.**<p> |
|
740
|
The different formats are called "Views". The current repertoire |
|
741
|
includes "Modern", "Columnar", "Compact", "Simple", "Verbose", and |
|
742
|
"Classic". Users can select whichever format they want and their |
|
743
|
preference is remembered in a cookie. |
|
744
|
|
|
745
|
1. **A Fossil web server admin can set the default timeline format.**<p> |
|
746
|
Individual users have a lot of control over what their own timeline |
|
747
|
displays look like, but the repository administrator can set the |
|
748
|
default separately for each repository. |
|
749
|
|
|
750
|
1. **Fossil is open and transparent about the cookies that it uses.**<p> |
|
751
|
There are really only three: The login cookie if you are logged in, |
|
752
|
the robot cookie indicating that you have previously passed a captcha |
|
753
|
if you are not logged in, and the display preferences cookie. |
|
754
|
If you visit the |
|
755
|
[/cookies page](/cookies), Fossil will |
|
756
|
show you all the cookies it uses and it will decode them for you to |
|
757
|
show you exactly what they mean and what information they are holding, |
|
758
|
and Fossil will give you an opportunity to delete each cookie |
|
759
|
individually. |
|
760
|
|
|
761
|
1. **The Fossil web interface comes with a variety of "skins" built in.**<p> |
|
762
|
A skin determines the coloration and layout of Fossil web pages. |
|
763
|
Visit the [/skins page](/skins) to see all the available skins and |
|
764
|
which one is currently in use. |
|
765
|
|
|
766
|
1. **Individual users get to choose their favorite Fossil skin.**<p> |
|
767
|
The repository administrator sets the default skin, but if |
|
768
|
individual users do not like that choice, they can select a different |
|
769
|
skin and their choice is recorded in the display preferences cookie. |
|
770
|
|
|
771
|
1. **Repository administrators can create new custom skins.**<p> |
|
772
|
The current library of skins are mostly derived from custom skins that |
|
773
|
users of Fossil have created over the years and generously donated |
|
774
|
to the project. If none of the default skins work for you, you can |
|
775
|
create your own, perhaps using one of the existing skins as a template. |
|
776
|
|
|
777
|
1. **Most Fossil web-interface skins include a detailed hamburger |
|
778
|
(☰) menu.**<p> |
|
779
|
Clicking on the hamburger menu brings up a dropdown "site-map" |
|
780
|
page that lets you quickly navigate to the information you want. |
|
781
|
(Note: The presence and operation of the hamburger menu is a |
|
782
|
skin-specific feature and might not be available on every skin, but |
|
783
|
it is used on the more popular skins.) Git itself has nothing like |
|
784
|
this. The various Git forges sometimes have a limited hamburger |
|
785
|
menu, that it is not nearly as complete. I find it difficult to |
|
786
|
locate the screens I want without consulting an AI. |
|
787
|
|
|
788
|
1. **The Fossil web interface /sitemap page is responsive to |
|
789
|
individual user permissions and capabilities.**<p> |
|
790
|
Each user on the Fossil web interface, including the special |
|
791
|
user "nobody" used if no login is attempted, has |
|
792
|
"capabilities" assigned by the repository administrator. |
|
793
|
Depending on capabilities, some pages will display differently or |
|
794
|
will not display at all. Pages that a user does not have access |
|
795
|
to are automatically omitted from the [/sitemap page](/sitemap). |
|
796
|
|
|
797
|
1. **The Fossil web interface allows "anonymous" users.**<p> |
|
798
|
The "anonymous" user is a human (we think, because he has solved |
|
799
|
a captcha) but we do not know who. Users who do not want to |
|
800
|
identify themselves but who also don't want to be mistaken for |
|
801
|
a spider or robot can log in as anonymous. |
|
802
|
<p> |
|
803
|
The repository administrator has complete control over the capabilities |
|
804
|
of anonymous. Anonymous can be completely banned, or maybe given |
|
805
|
read-only capabilities, or given complete access, with lots of shade |
|
806
|
in between, according to the needs of the project. |
|
807
|
<p> |
|
808
|
The "anonymous" user is distinct from user "nobody" in that we |
|
809
|
believe anonymous is a real human, whereas user nobody is presumed |
|
810
|
to be a robot. The repository administrator also has complete control |
|
811
|
over the capabilities for user "nobody". |
|
812
|
|
|
813
|
1. **The Fossil web interface has lots of built-in defenses against |
|
814
|
abuse by spiders and robots.**<p> |
|
815
|
Sadly, the internet is rapidly devolving such that most HTTP requests |
|
816
|
now come from AI spiders trying to find training content, and/or robots |
|
817
|
looking for website vulnerabilities. The flood of requests can |
|
818
|
rapidly bog down an undefended server. Fossil includes a range of |
|
819
|
defenses against aggressive bots that help keep the server load and |
|
820
|
ISP costs down while still providing fast and detailed responses |
|
821
|
to real humans. This is an on-going battle. But Fossil is, at least, |
|
822
|
in the fight. Everything is easily configurable, via the web interface, |
|
823
|
by repository administrators. |
|
824
|
|
|
825
|
1. **The Fossil web interface includes a "security audit" page accessible |
|
826
|
to repository administrators.**<p> |
|
827
|
The security-audit pages give a succinct summary of how a repository |
|
828
|
web interface is configured, with an eye toward operational security. |
|
829
|
As with any full-featured web application, the Fossil web interface |
|
830
|
has a large number of settings. A common worry among system |
|
831
|
administrators is overlooking or omitting or misconfiguring some |
|
832
|
security-sensitive setting. The security-audit page is designed to |
|
833
|
reduce that worry. |
|
834
|
<p> |
|
835
|
The security-audit page shows at a glance how a repository web interface |
|
836
|
is set up, and raises alerts about any settings that are questionable |
|
837
|
or that might facilitate mischief. The page fits on a single screen |
|
838
|
with minimal or no scrolling. After standing up a new Fossil server, |
|
839
|
a quick glance at the security-audit page (accessible only to |
|
840
|
administrators) gives peace of mind that all is well and that nothing |
|
841
|
was overlooked. |
|
842
|
|
|
843
|
1. **The Fossil web interface menu bar can be customized.**<p> |
|
844
|
Repository administrators can customize the menu bar on the web |
|
845
|
interface. Individual items can be added or omitted from the |
|
846
|
menu bar based on user capabilities and/or whether or not the |
|
847
|
client is a phone or other narrow-screen mobile device, a standard |
|
848
|
desktop browser, or a wide-screen desktop browser. |
|
849
|
|
|
850
|
1. **The Fossil web interface sitemap can be customized.**<p> |
|
851
|
Repository administrators can add new entries to the |
|
852
|
[/sitemap](/sitemap) that are shown or omitted |
|
853
|
based on user capabilities. |
|
854
|
|
|
855
|
1. **The Fossil web interface can be augmented with auxiliary content |
|
856
|
and/or CGIs that exist outside of the repository.**<p> |
|
857
|
The auxiliary content or CGI result uses the same theme and skin as |
|
858
|
the default website, and blends right in. An example of this is |
|
859
|
the |
|
860
|
[SQLite Release Checklist](https://sqlite.org/src/ext/checklist/top/index). |
|
861
|
The SQLite Release Checklist is a CGI that is completely separate from |
|
862
|
Fossil, but appears to be integrated in the Fossil web interface. |
|
863
|
It uses the same skin and interface settings. But the content is |
|
864
|
created by a separate CGI program. Fossil passes down additional |
|
865
|
CGI variables to tell the CGI what the Fossil user name is and what |
|
866
|
capabilities that user has, among other things. In the case of the |
|
867
|
SQLite Release Checklist, those additional settings mean only project |
|
868
|
committers can make changes to the checklist (such as marking items |
|
869
|
as "done") and that the checklist is read-only for the general public. |
|
870
|
<p> |
|
871
|
Additional information about this advanced feature of Fossil |
|
872
|
can be seen at <https://fossil-scm.org/home/doc/trunk/www/serverext.wiki>. |
|
873
|
|
|
874
|
1. **Fossil makes convenience commands available to run its |
|
875
|
cryptographic hash algorithms (SHA1 and SHA3-256)**<p> |
|
876
|
The "<tt>fossil sha1sum FILE ...</tt>" and |
|
877
|
"<tt>fossil sha3sum FILE ...</tt>" commands will |
|
878
|
compute SHA1 and SHA3-256 hashes on files. These commands are not |
|
879
|
necessary to use Fossil, but they are still useful, and they are |
|
880
|
not commonly installed on non-Linux platforms. Fossil ensures that |
|
881
|
those hash functions are available wherever Fossil is available. |
|
882
|
|
|
883
|
1. **Fossil exposes its 3-way-diff algorithm for external use.**<p> |
|
884
|
The "<tt>fossil 3-way-merge ...</tt>" command works |
|
885
|
like the classic unix "diff3" command in that it does a merge |
|
886
|
of two variants of a file given a common ancestor. This is the |
|
887
|
exact same algorithm that Fossil uses to compute merges internally, |
|
888
|
simply exposed for external use. |
|
889
|
|
|
890
|
1. **On a merge conflict, Fossil shows the conflicting inputs just |
|
891
|
like other merge algorithms, but it also shows a suggested conflict |
|
892
|
resolution.**<p> |
|
893
|
The suggested conflict resolution is not always correct, but it is |
|
894
|
sometimes, and its presence often makes resolving merge conflicts |
|
895
|
simpler. |
|
896
|
|
|
897
|
1. **Fossil supports single sign-in when serving multiple repositories |
|
898
|
from the same host computer.**<p> |
|
899
|
If you have a server that is hosting Fossil web interfaces for |
|
900
|
multiple repositories, those repositories can be interconnected |
|
901
|
into a common "login group" such that when a user logs into one |
|
902
|
repository web interface, he is also automatically logged into |
|
903
|
all other repositories in that login graph that hold the same |
|
904
|
username. Furthermore, if the user |
|
905
|
changes his password on one repository, it is automatically changed |
|
906
|
on all the others within that login group. |
|
907
|
|
|
908
|
1. **Experts can browse low-level details of a Fossil repository |
|
909
|
using SQL.**<p> |
|
910
|
A Fossil repository is just an SQLite database file. Low-level content |
|
911
|
of that database file can be viewed and even changed using ordinary |
|
912
|
SQL and the "<tt>fossil sql</tt>" command. The "fossil sql" |
|
913
|
command brings up a standard SQLite command-line shell, already |
|
914
|
connected to the repository database, and extended to include extra |
|
915
|
functions (including table-valued functions) to help interpret the |
|
916
|
low-level content of the repository. This feature is not needed nor |
|
917
|
recommended for the average user. However, if you want to learn more |
|
918
|
about the inner workings of Fossil, or if you want to generate some |
|
919
|
custom reports about a repository, or if you are extending or |
|
920
|
troubleshooting Fossil, the SQL interface is a great tool. |
|
921
|
|
|
922
|
1. **The underlying artifacts of a Fossil repository are well-documented, |
|
923
|
human-readable, and human-understandable.**<p> |
|
924
|
A Fossil repository is an SQLite database file, but not every SQLite |
|
925
|
database file is a Fossil repository. Fossil repositories store |
|
926
|
"artifacts" in a very particular format. See |
|
927
|
<https://fossil-scm.org/home/doc/trunk/www/fileformat.wiki> for |
|
928
|
the details of that format. |
|
929
|
<p> |
|
930
|
This underlying format is text-only. It is designed to be easily |
|
931
|
parsed and interpreted by programs written in any language. It is |
|
932
|
designed to be easily understood by humans, even humans not yet born. |
|
933
|
Many of the low-level artifact formats for Git, in contrast, are |
|
934
|
binary and are only thinly documented. The only sure way to understand |
|
935
|
the low-level Git format is, in my experience, to read the Git source |
|
936
|
code. |
|
937
|
|
|
938
|
1. **The Fossil web interface has a "This Day In History" page.**<p> |
|
939
|
See that page for [Fossil](/thisdayinhistory) or |
|
940
|
[SQLite](https://sqlite.org/src/thisdayinhistory). |
|
941
|
The page shows multiple timeline snippets from various |
|
942
|
days in the past: 1, 2, 5, 10, 15, 20 years ago. |
|
943
|
<p> |
|
944
|
This is something of a vanity page. It is difficult to describe a |
|
945
|
real business need for this information. But the page does jog old |
|
946
|
memories and helps developers keep perspective on how a project has |
|
947
|
changed through the years. |
|
948
|
<p> |
|
949
|
The existence of this page illustrates how the |
|
950
|
robust and modular design of the Fossil implementation |
|
951
|
facilitates custom modifications that involve very little new code. |
|
952
|
|
|
953
|
1. **Fossil allows you to update your current checkout even if it |
|
954
|
contains uncommitted changes.**<p> |
|
955
|
This is a very common idiom in Fossil: You are working on changes |
|
956
|
and somebody commits ahead of you. You run |
|
957
|
"<tt>fossil up</tt>" ("up" is short for "update") and the new |
|
958
|
external changes are merged into your own uncommitted changes. You |
|
959
|
continue working. |
|
960
|
<p> |
|
961
|
Doing this in Git appears to require multiple commands (or maybe |
|
962
|
just one command with multiple verbose options) to interact with |
|
963
|
the stash and to rebase your changes. |
|
964
|
|
|
965
|
1. **Fossil lets you undo an update.**<p> |
|
966
|
If you run "<tt>fossil up</tt>" on a checkout that contains |
|
967
|
uncommitted changes, and the update does not go well (for example, |
|
968
|
if there are a lot of merge conflicts) you can back out the update |
|
969
|
by running "<tt>fossil undo</tt>". |
|
970
|
<p> |
|
971
|
The need for this does not arise often, because |
|
972
|
"<tt>fossil up</tt>" normally just works. But the ability to |
|
973
|
undo is a nice safety-net for the rare cases when the update goes awry. |
|
974
|
|
|
975
|
1. **Fossil warns you if you try to commit and somebody else has |
|
976
|
committed ahead of you.**<p> |
|
977
|
You can then run "<tt>fossil up</tt>" and then retest and retry. |
|
978
|
Or you can override the warning and force Fossil to commit anyhow, |
|
979
|
thus forking the branch. Either way, |
|
980
|
you enter the commit with more knowledge about what is happening, |
|
981
|
and thus improved situational awareness. |
|
982
|
|
|
983
|
1. **Every Fossil project has a unique identifier**.<p> |
|
984
|
When a new repository is created, the unique identifier is created |
|
985
|
and stored in the repository. That identifier is called the |
|
986
|
"project code". The identifier is copied with every |
|
987
|
clone. (Uniqueness is probabilistic. The identifier simply contains |
|
988
|
enough of high-quality randomness to make it unlikely that there |
|
989
|
will ever be a collision.) |
|
990
|
<p> |
|
991
|
It is not possible in Fossil to push to or pull from a repository |
|
992
|
with the wrong project code. Thus you cannot contaminate one |
|
993
|
project with code from another simply by specifying the wrong |
|
994
|
remote and adding the --force flag, as is apparently possible in Git. |
|
995
|
|
|
996
|
1. **Each Fossil repository keeps an audit trail.**<p> |
|
997
|
For each new artifact received into a Fossil repository, by push or |
|
998
|
pull, or by direct commit from the command line, Fossil records a |
|
999
|
timestamp, username, and an IP address (where applicable) for |
|
1000
|
that artifact. If harmful or malicious content is added to |
|
1001
|
a repository, the repository administrator has the capability to |
|
1002
|
trace that content back to its source, so that appropriate |
|
1003
|
sanctions can be applied to the malefactor. |
|
1004
|
|
|
1005
|
1. **Fossil stores content in a power-safe ACID database.**<p> |
|
1006
|
The repository content cannot be corrupted by a program crash, |
|
1007
|
system crash, or unexpected power loss. The repository moves |
|
1008
|
from one consistent state to another, atomically. This helps |
|
1009
|
ensure that the resources stored in Fossil are kept safe, |
|
1010
|
even if the Fossil implementation itself contains bugs. |
|
1011
|
<p> |
|
1012
|
The underlying database engine used by Fossil is SQLite, of course. |
|
1013
|
<p> |
|
1014
|
Git also claims to be transactional. However, because Git does |
|
1015
|
not use a separate database engine, the transactional integrity |
|
1016
|
of Git depends entirely upon the correctness of the Git code |
|
1017
|
itself. Git is thus far more sensitive to implementation errors. |
|
1018
|
|
|
1019
|
1. **Fossil supports a built-in graphical diff tool.**<p> |
|
1020
|
Running "<tt>fossil gdiff</tt>" show the currently |
|
1021
|
uncommitted changes in a Tk-based graphical display. This |
|
1022
|
is built into Fossil and does not require any external tools |
|
1023
|
(though it does require Tcl/Tk). Git requires external tooling |
|
1024
|
in order to do the same. |
|
1025
|
|
|
1026
|
1. **Fossil supports showing diffs in a web browser.**<p> |
|
1027
|
Adding the "<tt>-b</tt>" or "<tt>-by</tt>" option to any Fossil |
|
1028
|
diff command causes that diff to be rendered as a new page in |
|
1029
|
the users default web browser. Git does not have any such |
|
1030
|
capability, even with the aid of external programs, as far as |
|
1031
|
I am aware. |
|
1032
|
|
|
1033
|
1. **The Fossil web interface provides a captcha-gated method to download |
|
1034
|
tarballs and ZIP archives for any check-in.**<p> |
|
1035
|
See, for example, <https://sqlite.org/src/rchvdwnld/20260704>. |
|
1036
|
That link provides access to the last check-in for the day 2026-07-04. |
|
1037
|
The last element of the patch can be any hash prefix, timestamp prefix, |
|
1038
|
or tag that references a check-in.<p> |
|
1039
|
Tarballs and ZIP archives are expensive to compute, not because Fossil |
|
1040
|
has trouble assembling the content, |
|
1041
|
but rather because the result must be run through zlib compression. |
|
1042
|
When computing a new archive, almost all of the CPU time is spent |
|
1043
|
inside of the zlib compression library. |
|
1044
|
For an SQLite-size tarball, the zlib compression alone can take as |
|
1045
|
much as 10 seconds of CPU time. If the tarball/ZIP-archive download |
|
1046
|
link is not protected by a captcha, multiple spiders will attempt to |
|
1047
|
download every possible tarball and ZIP archive, multiple times per |
|
1048
|
day, bringing your server to its knees. |
|
1049
|
|
|
1050
|
1. **Repository administrators can create a cache of recently downloaded |
|
1051
|
tarballs and ZIP archives**<p> |
|
1052
|
That way, if there are common downloads (like the most recent release) |
|
1053
|
the archive does not get recomputed from scratch with each download. |
|
1054
|
A download of a cached archive file is fast. |
|
1055
|
The size of the cache is configurable by the repository administrator. |
|
1056
|
|
|
1057
|
1. **The Fossil web interface has a "Repository Status" page that shows |
|
1058
|
interesting and useful facts about the repository being served.**<p> |
|
1059
|
See the [stat page for Fossil](/stat) for example. |
|
1060
|
|
|
1061
|
1. **The Fossil web interface easily shows all of the contributors to |
|
1062
|
a project, and the number of changes they have committed.**<p> |
|
1063
|
See <https://fossil-scm.org/home/reports> for that report about |
|
1064
|
Fossil itself. |
|
1065
|
Many other reports can be generated from the same page by selecting |
|
1066
|
different options from the pull-down menus at the top. |
|
1067
|
<p>The page is captcha-gated since it is a magnet for spiders. |
|
1068
|
|
|
1069
|
1. **The Fossil source code is easy to enhance with new web pages and |
|
1070
|
commands.**<p> |
|
1071
|
The design of the Fossil implementation makes it easy to extend with |
|
1072
|
new capabilities as needs arise. |
|
1073
|
<ul type="disk"> |
|
1074
|
<li> The code is simple C89. |
|
1075
|
<li> Each command or web page runs as a separate process which |
|
1076
|
exits when the action completes, so minor memory leaks are not |
|
1077
|
a concern. |
|
1078
|
<li> Preprocessors run over the Fossil source code before the |
|
1079
|
code reaches the C compiler to verify |
|
1080
|
that there are no SQL injections nor XSS vulnerabilities. |
|
1081
|
<li> New commands and webpages can be added simply by adding a new |
|
1082
|
procedure to do the necessary computation. The name, properties, |
|
1083
|
and documentation for the command or webpage are extracted from |
|
1084
|
specially formatted comments just prior to the procedure. |
|
1085
|
</ul><p> |
|
1086
|
The ease with which Fossil can be enhanced is part of the reason why |
|
1087
|
it has picked up so many useful features and has become so |
|
1088
|
powerful over its 19-year history. |
|
1089
|
|
|
1090
|
## Conclusion |
|
1091
|
|
|
1092
|
There are more reasons to prefer Fossil over Git, but |
|
1093
|
I think 101 are sufficient to prove my point. |
|
1094
|
|