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