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