Fossil SCM
More work on 101 reasons. Still far from complete.
Commit
12c0936eb1f91bfafd6de1e4832def1c84292bfad51f061fc72f798cd6d153f9
Parent
92693e3e8a5dcee…
1 file changed
+153
-86
+153
-86
| --- www/hundredandone.md | ||
| +++ www/hundredandone.md | ||
| @@ -1,13 +1,13 @@ | ||
| 1 | 1 | # 101 Reasons Why Fossil Is Better Than Git |
| 2 | 2 | |
| 3 | 3 | *This is a work in progress. I only have 38 reasons typed in so far, |
| 4 | 4 | but I have a separate text file of notes that lists 104 candidate reasons. |
| 5 | 5 | It's just taking me a while to compose and edit the rationale for each |
| 6 | -one, so it seems expedient to check-in this draft.* | |
| 6 | +one, so it seems expedient to checkin this draft.* | |
| 7 | 7 | |
| 8 | - 1. **Fossil comes as a single executable file**.<p> | |
| 8 | + 1. **Fossil comes as a single self-contained executable file**.<p> | |
| 9 | 9 | Install Fossil by copying "fossil" (or "fossil.exe") to someplace |
| 10 | 10 | on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting |
| 11 | 11 | that one file. Uninstall by deleting that one file.<p> |
| 12 | 12 | A Git installation requires hundreds of files. You want to use |
| 13 | 13 | package manager to install, upgrade, or uninstall Git. If you |
| @@ -45,12 +45,12 @@ | ||
| 45 | 45 | |
| 46 | 46 | 1. **In Fossil, a repository is distinct from a working check-out.**<p> |
| 47 | 47 | A Fossil repository can be colocated with the working check-out, as |
| 48 | 48 | they are required to be in Git. But most people keep the repository |
| 49 | 49 | separate. One common pattern is to put all Fossil repositories in |
| 50 | - a single directory name $HOME/Fossils or $HOME/Museum, and then open | |
| 51 | - working check-outs against each repository whereever they are needed. | |
| 50 | + a single directory named $HOME/Fossils or $HOME/Museum, and then open | |
| 51 | + working check-outs against each repository whereever they are needed. | |
| 52 | 52 | |
| 53 | 53 | 1. **A single Fossil repository can support multiple working check-outs.** |
| 54 | 54 | <p> |
| 55 | 55 | Git has worktrees, but all worktrees checkouts must be on separate |
| 56 | 56 | branches. Fossil allows multiple working check-outs on the same branch |
| @@ -65,17 +65,18 @@ | ||
| 65 | 65 | You can "mv" a Fossil repository to a new place. You can "scp" |
| 66 | 66 | a Fossil repository to another machine. It is just a file, |
| 67 | 67 | specifically an SQLite database file. |
| 68 | 68 | |
| 69 | 69 | 1. **Fossil does not have a staging area**.</p> |
| 70 | - A user-visible staging area adds no capabilities. (Partial commits | |
| 70 | + A staging area adds no new capabilities. (Partial commits | |
| 71 | 71 | are accomplished in Fossil simply by listing the subset of files to |
| 72 | - be committed on the "fossil commit" command line.) But the staging | |
| 73 | - area does complicate the mental model of the project that Git users | |
| 74 | - need to keep up with, forcing the developer to spend more time thinking | |
| 75 | - about the version control system and hence less time thinking about | |
| 76 | - the project they are working on. | |
| 72 | + be committed on the "fossil commit" command line.) A staging area | |
| 73 | + only adds complication. The staging area adds to the mental model | |
| 74 | + of the project that Git users need to keep up with, forcing the | |
| 75 | + developer to spend more time thinking about the version control | |
| 76 | + system and hence less time thinking about the project they are | |
| 77 | + working on. | |
| 77 | 78 | |
| 78 | 79 | 1. **Fossil remembers where all your repositories and working |
| 79 | 80 | check-outs are located.**<p> |
| 80 | 81 | This and other information (such as all your global settings) |
| 81 | 82 | is stored in a per-user database file |
| @@ -99,35 +100,35 @@ | ||
| 99 | 100 | If you are like me and have hundreds of repositories on your desktop |
| 100 | 101 | system, this feature makes it easier to keep track of them all. |
| 101 | 102 | Are you on an infrequently used travel laptop and forgot where you |
| 102 | 103 | put a particular repository, this feature helps you find it. |
| 103 | 104 | |
| 104 | - 1. **Fossil allows multiple check-ins to have the same tag.**<p> | |
| 105 | + 1. **Fossil allows multiple checkins to have the same tag.**<p> | |
| 105 | 106 | For example, on the SQLite project, every release is tagged with |
| 106 | 107 | "release". |
| 107 | 108 | |
| 108 | - 1. **The Fossil timeline can show all check-ins with a specific tag.**<p> | |
| 109 | + 1. **The Fossil timeline can show all checkins with a specific tag.**<p> | |
| 109 | 110 | For example, to see all SQLite releases visit |
| 110 | 111 | <https://sqlite.org/src/timeline?t=release> or to see all |
| 111 | 112 | Fossil releases go to |
| 112 | 113 | <https://fossil-scm.org/home/timeline?t=release>. |
| 113 | 114 | |
| 114 | 115 | 1. **Fossil has a built-in wiki**.<p> |
| 115 | 116 | Wiki pages are colocated in the same repository as your code, so that |
| 116 | 117 | they push, pull, sync, and clone together with your code. |
| 117 | 118 | |
| 118 | - 1. **Fossil can associated a wiki page with a particular check-in.**<p> | |
| 119 | - Rather than including a massive and verbose check-in comment on an | |
| 120 | - important check-in (such as the merge of a big new feature), Fossil | |
| 121 | - allows you to assign a wiki page to that check-in. That wiki page | |
| 122 | - is show as part of the check-in information in the web interface. | |
| 119 | + 1. **Fossil can associated a wiki page with a particular checkin.**<p> | |
| 120 | + Rather than including a massive and verbose checkin comment on an | |
| 121 | + important checkin (such as the merge of a big new feature), Fossil | |
| 122 | + allows you to assign a wiki page to that checkin. That wiki page | |
| 123 | + is show as part of the checkin information in the web interface. | |
| 123 | 124 | See, for example, the "About" section of |
| 124 | - [SQLite check-in 2019-11-21T18:28:44.463Z](https://sqlite.org/src/info/2019-11-21T18:28:44.463Z). | |
| 125 | - The wiki page associated with a check-in can be created and revised | |
| 126 | - after the check-in is comimtted and pushed. So it can be used, for | |
| 125 | + [SQLite checkin 2019-11-21T18:28:44.463Z](https://sqlite.org/src/info/2019-11-21T18:28:44.463Z). | |
| 126 | + The wiki page associated with a checkin can be created and revised | |
| 127 | + after the checkin is comimtted and pushed. So it can be used, for | |
| 127 | 128 | example, to add notes or bug reports that occur long after the |
| 128 | - check-in itself has been inserted into the DAG. | |
| 129 | + checkin itself has been inserted into the DAG. | |
| 129 | 130 | |
| 130 | 131 | 1. **Fossil can associate a wiki page with a particular branch.**<p> |
| 131 | 132 | You can create a wiki page for a branch that documents the purpose |
| 132 | 133 | of the branch. The wiki page can be displayed separately (like any |
| 133 | 134 | other wiki page) but is also displayed automatically at the top of |
| @@ -142,56 +143,60 @@ | ||
| 142 | 143 | "Whatever became of that setlk-snapshot-fix branch you |
| 143 | 144 | started last year?" That branch still exists and you |
| 144 | 145 | can [see it on GitHub](https://github.com/sqlite/sqlite/commits/setlk-snapshot-fix) |
| 145 | 146 | and [in Fossil](https://sqlite.org/src/timeline?r=setlk-snapshot-fix). |
| 146 | 147 | Notice, thought, that GitHub does not show how the branch was resolved. |
| 148 | + (Aside: Also notice how much faster Fossil renders!) | |
| 147 | 149 | Fossil clearly shows that the branch ended up being merged into trunk. |
| 148 | 150 | GitHub just shows us all ancestors of the leaf node labeled |
| 149 | 151 | "setlk-snapshot-fix", including ancestors that were in other branches |
| 150 | 152 | that got merged in, and ancestors that predate the founding of the |
| 151 | 153 | setlk-snapshot-fix branch. |
| 152 | 154 | <p> |
| 153 | - GitHub just cannot shows you the check-ins of branch setlk-snapshot-fix | |
| 155 | + GitHub just cannot shows you the checkins of branch setlk-snapshot-fix | |
| 154 | 156 | only. There are other third-party tools that will show you that, I am |
| 155 | 157 | told, but they all require a local clone of the repository. Apparently |
| 156 | 158 | there is no way to see this information in a web browser runnig on |
| 157 | 159 | your phone. |
| 158 | 160 | |
| 159 | 161 | 1. **Fossil allows multiple branches with the same name.**<p> |
| 160 | - This feature is used a lot for branches named "experimental" and | |
| 161 | - "mistake". See | |
| 162 | + This is used, for example, to name a lot for branches "experimental" | |
| 163 | + and mistake". See | |
| 162 | 164 | <https://sqlite.org/src/timeline?r=experimental> and |
| 163 | 165 | <https://sqlite.org/src/timeline?r=mistake>. Or see |
| 164 | - [the empty-table-optimizations branch(es)](https://sqlite.org/src/timeline?r=empty-table-optimizations) which was initially merge to trunk and closed | |
| 166 | + [the empty-table-optimizations branch(es)](https://sqlite.org/src/timeline?r=empty-table-optimizations) which was initially mergde to trunk and closed | |
| 165 | 167 | on 2025-07-02, but then reopened and continued with more enhancements |
| 166 | 168 | until it was merged again on 2025-07-08. |
| 167 | 169 | |
| 168 | 170 | 1. **Fossil allows legacy SHA1 hashes and newer SHA3-256 hashes in the |
| 169 | 171 | same repository.**<p> |
| 170 | 172 | Both Fossil and Git started out using SHA1 hashes. But when the |
| 171 | - SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) | |
| 173 | + [SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) | |
| 172 | 174 | against SHA1 was published on 2017-02-23, the need to migrate to a |
| 173 | 175 | stronger hash algorithm was recognized. Fossil added the ability |
| 174 | - to use SHA3-256 as an alternative on 2017-03-01, and to this day | |
| 175 | - it continues to support both, though SHA3-256 is the default for all | |
| 176 | - new repositories and check-ins. But older check-ins that occurred | |
| 177 | - prior to ShAttered still use their original SHA1 hash and so no | |
| 178 | - repositories had to be rebuilt and no hyperlinks were broken.<p> | |
| 179 | - In contrast, a Git repository supports only one hash algorithm. | |
| 180 | - Newer repos can use SHA2, though the default is still SHA1. | |
| 181 | - | |
| 182 | - 1. **Fossil allows check-ins to be identified by timestamp**<p> | |
| 183 | - The canonical name for a check-in is its hash. Both Git and Fossil | |
| 184 | - allow a check-in to be identified by any unique prefix of its hash. | |
| 185 | - But only Fossil allows a check-in to also be identified by its | |
| 186 | - timestamp. The names "2026-02-02T16:03:24.852Z" and "fdebbedbd9a99165" | |
| 187 | - both refer to [the same check-in](https://sqlite.org/src/fdebbedbd9a99165) | |
| 176 | + to use SHA3-256 as an alternative on 2017-03-01 (six days after the | |
| 177 | + attack was first published), and to this day | |
| 178 | + it continues to support both. SHA3-256 is now the default for all | |
| 179 | + new repositories and checkins, though older checkins that occurred | |
| 180 | + prior to ShAttered can still use their original SHA1 hash and so no | |
| 181 | + repositories had to be rebuilt and no hyperlinks were broken.<p> | |
| 182 | + In contrast, after nine years, a Git repository can still only | |
| 183 | + support only one hash algorithm at a time. | |
| 184 | + Newer Git repositories are able to use SHA2, though the default | |
| 185 | + is still SHA1. | |
| 186 | + | |
| 187 | + 1. **Fossil allows checkins to be identified by timestamp**<p> | |
| 188 | + The canonical name for a checkin is its hash. Both Git and Fossil | |
| 189 | + allow a checkin to be identified by any unique prefix of its hash. | |
| 190 | + But only Fossil allows a checkin to also be identified by its | |
| 191 | + timestamp. The names "2026-02-02T16:03:24.852Z" and "fdebbedbd9a99165" | |
| 192 | + both refer to [the same checkin](https://sqlite.org/src/fdebbedbd9a99165) | |
| 188 | 193 | in SQLite, but the first one has the advantage of giving some time |
| 189 | 194 | context rather than just being a seemingly random sequence of hexadecimal |
| 190 | - digits. It is possible that two or more check-ins can have the same | |
| 195 | + digits. It is possible that two or more checkins can have the same | |
| 191 | 196 | timestamp, in which case the timestamp would be ambiguous. And a |
| 192 | - check-in timestamp can be changed after it is committed, by using | |
| 197 | + checkin timestamp can be changed after it is committed, by using | |
| 193 | 198 | a special tag. So timestamp identifiers do not have the uniqueness |
| 194 | 199 | and stability guarantees as hash identifiers, but they are available |
| 195 | 200 | as an option and are often useful. |
| 196 | 201 | |
| 197 | 202 | 1. **Fossil has a built-in forum.**<p> |
| @@ -234,22 +239,22 @@ | ||
| 234 | 239 | The [autosync setting](/help/autosync), which defaults to "on", causes |
| 235 | 240 | every commit to automatically push to the default remote. This helps |
| 236 | 241 | to keep the remote up-to-date and helps all the developers working on |
| 237 | 242 | the software keep up with what other developers are doing. |
| 238 | 243 | <p> |
| 239 | - Users whose prior experience is only with Git might object to | |
| 240 | - autosync, saying that this could cause all kinds of problems for Git | |
| 241 | - if another developer commits ahead of you. True enough, that would | |
| 242 | - cause headaches for Git, but it does not cause any problems for Fossil. | |
| 244 | + Long-time Git users might cringe at autosync, thinking that this | |
| 245 | + could cause problems if another developer commits ahead of you. | |
| 246 | + True enough, that would cause headaches for Git, but it does not | |
| 247 | + create problems for Fossil. | |
| 243 | 248 | The worse that could happen is that the branch will fork. Fossil |
| 244 | - will usually detect that a fork is about to happen and warn you. | |
| 249 | + will usually detect an impending fork and warn you. | |
| 245 | 250 | But even if you don't get the warning (due to a race) or even if you |
| 246 | 251 | override the warning and force the commit anyhow, a fork on a branch |
| 247 | - in Fossil is quite harmless. It shows cleanly on the timeline and | |
| 248 | - is easily resolved. So while autosync might case issues with Git, | |
| 249 | - it does not cause issues in Fossil and so the benefits far outweigh | |
| 250 | - the risks and autosync is the default behavior. | |
| 252 | + in Fossil is harmless. It shows cleanly on the timeline and | |
| 253 | + is easily resolved. So while autosync might cause issues with Git, | |
| 254 | + it is harmless to Fossil. Since forks are harmless, the benefits | |
| 255 | + of autosync far outweigh the risks. | |
| 251 | 256 | |
| 252 | 257 | 1. **Fossil supports embedded Pikchr in Wiki and in the Forum.**</p> |
| 253 | 258 | [Pikchr](https://pikchr.org/) is a |
| 254 | 259 | [PIC-like](https://en.wikipedia.org/wiki/Pic_language) markup language |
| 255 | 260 | for diagram. The diagrams that appear in the Fossil documentation are |
| @@ -276,11 +281,11 @@ | ||
| 276 | 281 | Core Git does not have any kind of markup language. Check-in comments |
| 277 | 282 | in Git are always displayed verbatim. But wrappers such as GitHub, |
| 278 | 283 | GitLab, Gitea, Forgejo, and similar generally support some variant |
| 279 | 284 | of Markdown. However, none of these system support links (apart from |
| 280 | 285 | full URLs) to other wiki systems. Fossil does support interwiki links |
| 281 | - using the syntax "<tt>remote:path</tt>". So, for example, a check-in | |
| 286 | + using the syntax "<tt>remote:path</tt>". So, for example, a checkin | |
| 282 | 287 | in the SQLite source repository (<https://sqlite.org/src>) that wants |
| 283 | 288 | to reference a bug report (perhaps because it fixes the bug) can |
| 284 | 289 | include a link of the form "<tt>bugs:/info/</tt><i>HASH</i>" to |
| 285 | 290 | reference that bug. The source repository knows that "bugs:" refers |
| 286 | 291 | to the [SQLite Bug Forum](https://sqlite.org/bugs) and completes the |
| @@ -293,44 +298,57 @@ | ||
| 293 | 298 | to go stale, and (3) clone can have different mappings for |
| 294 | 299 | interwiki links, so that (for example) a "bugs:" link in a clone |
| 295 | 300 | of the source repository can map to a clone of the Bugs Forum |
| 296 | 301 | repository. |
| 297 | 302 | |
| 298 | - 1. **Fossil has a built-in chat server**<p> | |
| 303 | + 1. **Fossil has a built-in chat server.**<p> | |
| 299 | 304 | Users with appropriate permissions (usually just known and registered |
| 300 | 305 | developers, not anonymous passers-by) can bring up a web-based chat |
| 301 | 306 | server on any Fossil web-server instance. This feature allow |
| 302 | 307 | geographically distributed developers to collaborate interactively, |
| 303 | 308 | without having to involve a third-party chat provider such as Slack. |
| 304 | - Fossil can be configured to automatically report new check-ins and | |
| 305 | - other activities as chat messages, so that developers are alerted to | |
| 306 | - changes. This feature is built-in to every Fossil web interface | |
| 307 | - and it works with any modern web browser. No extra plugins or | |
| 308 | - JS frameworks are required. Nothing need to be configured, other | |
| 309 | + Nothing need to be configured in order to activate Chat, other | |
| 309 | 310 | that enabling the Chat privilege on the permission bits of the |
| 310 | 311 | users whom you want to have access to Chat. |
| 311 | 312 | |
| 312 | - 1. **Fossil supports hyperlinks in check-in comments.**<p> | |
| 313 | + 1. **Fossil chat can be configured to send automatic notifications | |
| 314 | + when changes occur in the repository.**<p> | |
| 315 | + This helps developers keep up with what is happening in the repository. | |
| 316 | + The chat window beeps (or not, configurable individually by each user) | |
| 317 | + when new messages arrive, as an alert. | |
| 318 | + | |
| 319 | + 1. **The Fossil Chat system has hooks that allow external subsystems | |
| 320 | + to inject chat message.**<p> | |
| 321 | + The SQLite developers use this to get notifications of testing | |
| 322 | + failures from our fuzz testing infrastructure. It could also | |
| 323 | + be leveraged to get chat notifications of CI/CD problems. | |
| 324 | + | |
| 325 | + 1. **Fossil chat is able to send attachments.**<p> | |
| 326 | + When the SQLite developers are working collaboratively on a problem | |
| 327 | + (while sitting, literally, in three different continents) we easily | |
| 328 | + send patches or diffs to one another over Chat. | |
| 329 | + | |
| 330 | + 1. **Fossil supports hyperlinks in checkin comments.**<p> | |
| 313 | 331 | Check-in comments need not be just verbatim text (though they can |
| 314 | - be depending on repository settings). By default, check-in | |
| 332 | + be depending on repository settings). By default, checkin | |
| 315 | 333 | comments can contain hyperlinks, including hyperlinks to |
| 316 | - wiki pages, prior check-ins, forum posts, and interwiki hyperlinks. | |
| 334 | + wiki pages, prior checkins, forum posts, and interwiki hyperlinks. | |
| 317 | 335 | |
| 318 | 336 | 1. **Fossil supports hyperlink back references**<p> |
| 319 | - If the check-in comment for a newer commits contains a hyperlink | |
| 337 | + If the checkin comment for a newer commits contains a hyperlink | |
| 320 | 338 | back to an older commit, then when the web interface show the |
| 321 | 339 | details of the older commit, it also provides are forward |
| 322 | 340 | reference to the newer commit. |
| 323 | 341 | |
| 324 | 342 | 1. **Fossil supports a graphical timeline display of a bisect.**<p> |
| 325 | 343 | [For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). |
| 326 | 344 | This is not strictly necessary to make effective use of bisect, but |
| 327 | 345 | the graphical display does seem to help with situational awareness. |
| 328 | 346 | |
| 329 | - 1. **Fossil allows you to revise a check-in comment without | |
| 347 | + 1. **Fossil allows you to revise a checkin comment without | |
| 330 | 348 | rewriting history.**<p> |
| 331 | - If you find a typo or other error in an historical check-in comment, | |
| 349 | + If you find a typo or other error in an historical checkin comment, | |
| 332 | 350 | you can fix the problem in Fossil without having to rewrite all |
| 333 | 351 | subsequent history. The Fossil file format allows you to set |
| 334 | 352 | a special tag on the checkin you want to revise (actually a |
| 335 | 353 | "property", not a "tag", since it also carries a value - the new |
| 336 | 354 | comment text). The new tag causes both the command-line display |
| @@ -337,59 +355,59 @@ | ||
| 337 | 355 | and the web interface to show the revised checkin comment rather |
| 338 | 356 | that the original. Note that the original checkin comment is |
| 339 | 357 | preserved, so there is still an immutable audit trail. But for |
| 340 | 358 | common use cases, only the new revised comment is shown. |
| 341 | 359 | <p> |
| 342 | - If you are using the web interface and if you have check-in privilege | |
| 343 | - on the repository, then on the /info page for the check-in, under | |
| 360 | + If you are using the web interface and if you have checkin privilege | |
| 361 | + on the repository, then on the /info page for the checkin, under | |
| 344 | 362 | the "Overview" section, to the right of "Other Links:", there is |
| 345 | 363 | an "edit" link that will take you to a page that lets you change |
| 346 | - the check-in comment from the web interface. This is the easiest | |
| 364 | + the checkin comment from the web interface. This is the easiest | |
| 347 | 365 | way to make the change. |
| 348 | 366 | <p> |
| 349 | - See [Fossil check-in b63d654041](/info/b63d65404) for a | |
| 367 | + See [Fossil checkin b63d654041](/info/b63d65404) for a | |
| 350 | 368 | recent example. The original comment is shown in the "Overview" |
| 351 | 369 | section of the checkin details, but the revised comment is show |
| 352 | 370 | in the timeline. |
| 353 | 371 | |
| 354 | - 1. **Fossil allows you to revise a check-in timestamp without | |
| 372 | + 1. **Fossil allows you to revise a checkin timestamp without | |
| 355 | 373 | rewriting history.**<p> |
| 356 | 374 | When generating a new checkin, Fossil uses the current time on the |
| 357 | 375 | system where the commit is occurring. But if the system clock on |
| 358 | - that system is incorrect, that can lead to a check-in with an | |
| 359 | - inaccurate timestamp. It can be the case that prior check-ins | |
| 360 | - have later timestamps or that subsequent check-ins can have | |
| 376 | + that system is incorrect, that can lead to a checkin with an | |
| 377 | + inaccurate timestamp. It can be the case that prior checkins | |
| 378 | + have later timestamps or that subsequent checkins can have | |
| 361 | 379 | earlier timestamps, resulting in goofy-looking "time-warps" in the |
| 362 | 380 | timeline. This can be correct by add a timestamp correction tag |
| 363 | - to the faulty check-in to fix the timestamp. | |
| 381 | + to the faulty checkin to fix the timestamp. | |
| 364 | 382 | <p> |
| 365 | - If you are using the web interface and if you have check-in privilege | |
| 366 | - on the repository, then on the /info page for the check-in, under | |
| 383 | + If you are using the web interface and if you have checkin privilege | |
| 384 | + on the repository, then on the /info page for the checkin, under | |
| 367 | 385 | the "Overview" section, to the right of "Other Links:", there is |
| 368 | 386 | an "edit" link that will take you to a page that lets you change |
| 369 | - the timestamp for a check-in from the web interface. This is the | |
| 387 | + the timestamp for a checkin from the web interface. This is the | |
| 370 | 388 | easiest way to make the change. |
| 371 | 389 | |
| 372 | - 1. **Fossil allows you to move a check-in to a new branch without | |
| 390 | + 1. **Fossil allows you to move a checkin to a new branch without | |
| 373 | 391 | rewriting history.**<p> |
| 374 | 392 | If you mistakenly commit to the wrong branch, you can move that |
| 375 | - check-in to a new branch by attaching a special tag. | |
| 376 | - Note, however, that this will also move all subsequent check-ins | |
| 393 | + checkin to a new branch by attaching a special tag. | |
| 394 | + Note, however, that this will also move all subsequent checkins | |
| 377 | 395 | to that same new branch. |
| 378 | 396 | <p> |
| 379 | 397 | In the SQLite and Fossil projects, when developers mistakenly commit |
| 380 | 398 | on the wrong branch, the usual way we fix that is to move the |
| 381 | - mistaken check-in to a branch named "mistake". Sometimes we also | |
| 382 | - set the "hidden" tag on that check-in as well, so that it does not | |
| 399 | + mistaken checkin to a branch named "mistake". Sometimes we also | |
| 400 | + set the "hidden" tag on that checkin as well, so that it does not | |
| 383 | 401 | show up on ordinary timelines (though it is still part of the |
| 384 | 402 | immutable audit history and is visible with special options). |
| 385 | 403 | Then we just redo the commit on the correct branch. |
| 386 | 404 | <p> |
| 387 | - If you are using the web interface and if you have check-in privilege | |
| 388 | - on the repository, then on the /info page for the check-in, under | |
| 405 | + If you are using the web interface and if you have checkin privilege | |
| 406 | + on the repository, then on the /info page for the checkin, under | |
| 389 | 407 | the "Overview" section, to the right of "Other Links:", there is |
| 390 | - an "edit" link that will take you to a page that lets move the check-in | |
| 408 | + an "edit" link that will take you to a page that lets move the checkin | |
| 391 | 409 | to a new branch from the web interface. You can also do this |
| 392 | 410 | from the Fossil commit-line, but the web interface is easier and less |
| 393 | 411 | error prone. |
| 394 | 412 | |
| 395 | 413 | 1. **Fossil supports unversioned files**.<p> |
| @@ -396,11 +414,11 @@ | ||
| 396 | 414 | [Unversioned Files](/doc/trunk/www/unvers.wiki) are files held |
| 397 | 415 | in the repository but which are not versioned are which are not |
| 398 | 416 | synced by default. Unversioned files are used by Fossil itself |
| 399 | 417 | to store [Precompiled Binaries of Fossil](/uv/download.html). |
| 400 | 418 | |
| 401 | - 1. **Fossil automatically select checkin background colors according to | |
| 419 | + 1. **Fossil automatically selects checkin background colors according to | |
| 402 | 420 | the branch that each checkin occurs on.**<p> |
| 403 | 421 | This helps to make the timeline easier to read at a glance, by |
| 404 | 422 | clearly showing which checkins are on which branches. Developers |
| 405 | 423 | can assign specific colors to branches either when the branch is |
| 406 | 424 | first created, or after the branch has been running for a while. |
| @@ -413,14 +431,63 @@ | ||
| 413 | 431 | On the [/hash-color-test page](/hash-color-test), one can enter |
| 414 | 432 | candidate branch names and see in advance what colors Fossil will |
| 415 | 433 | pick for that branch name. This seems like cheating, but I will |
| 416 | 434 | admit that I do this myself, sometimes... |
| 417 | 435 | |
| 418 | - 1. **The Fossil web interface timeline can be asked to pick check-in | |
| 436 | + 1. **The Fossil web interface timeline can be asked to pick checkin | |
| 419 | 437 | colors according to the name of the committer, rather than the branch |
| 420 | 438 | name.**<p> |
| 421 | 439 | Simply add the "ubg" query parameter (mnemonic: User BackGround) and |
| 422 | 440 | the checkin colors will be determined by the committer login name |
| 423 | 441 | rather than the branch name or any preselected color name. This |
| 424 | 442 | results in a timeline that gives reader a clearer view of who is |
| 425 | 443 | making changes. |
| 426 | 444 | [Example](/timeline?n=200&y=ci&ubg). |
| 445 | + | |
| 446 | + 1. **Fossil tracks cherrypick merges.**<p> | |
| 447 | + Cherrypicks are recorded as part of the underlying | |
| 448 | + [Fossil file format](/doc/trunk/www/fileformat.wiki). | |
| 449 | + Cherrypicks appear on the timeline as thin dashed lines. | |
| 450 | + | |
| 451 | + 1. **Fossil draws arrows pointing forwards in time.**<p> | |
| 452 | + Forward-pointing arrows are far more intuitive than arrows | |
| 453 | + that point backwards in times, like Git uses. Yes, I am aware | |
| 454 | + that the underlying implementation of Git has pointers going from child | |
| 455 | + to parent, and thus must necessarily go backwards in time. Fossil | |
| 456 | + has the same pointers. But just because the *implementation* | |
| 457 | + points backwards in time does not mean that the *user interface* | |
| 458 | + needs to do the same. Fossil flips those pointers around so that | |
| 459 | + they make more sense from the perspective of the human reader. | |
| 460 | + | |
| 461 | + 1. **Fossil implements some unix-like shell commands to use as | |
| 462 | + substitutes on systems that don't have them or that have inferior | |
| 463 | + implementations.**<p> | |
| 464 | + For example the "fossil system ls" command works like the standard | |
| 465 | + "ls" command on unix. It doesn't support all the options that a typical | |
| 466 | + "ls" implementation supports on Linux, but it is still way better than | |
| 467 | + having to run "dir". Other substitute commands include | |
| 468 | + "date", "pwd", "stty", "unzip", "which", and "zip". Probably | |
| 469 | + more will be added as needs arise. Having ready access to these | |
| 470 | + commands built into the standalone Fossil binary makes working on | |
| 471 | + non-Linux platforms more comfortable for unix geeks, and saves having | |
| 472 | + to hunt around and install system-specific alternatives. | |
| 473 | + | |
| 474 | + 1. **Fossil can transfer all uncommited changes from a check-out on a | |
| 475 | + remote system over to a check-out on the local machine.**<p> | |
| 476 | + The command is [fossil patch pull](/help?patch). It contacts the | |
| 477 | + remote system via SSH, updates its local check-out to the same baseline | |
| 478 | + as is found on the remote, then pulls over a minimal set of diffs and | |
| 479 | + applies them.<p> | |
| 480 | + This is very useful in pre-commit testing. For example, if you have | |
| 481 | + a big change on your desktop, and you want to test it before | |
| 482 | + committing, on multiple platforms, you can ssh over to those other | |
| 483 | + platforms and run "fossil patch pull ... && make test". When working | |
| 484 | + on SQLite, I will typically do that on a remote Mac, and remote | |
| 485 | + Win11 machine, and on a 32-core remote Linux machine that runs | |
| 486 | + faster than my desktop. | |
| 487 | + | |
| 488 | + 1. **Fossil can push uncommitted chagnes to a remote check-out for the | |
| 489 | + same project.**<p> | |
| 490 | + This is the same as the previous but in reverse. It is used, for | |
| 491 | + example, to push proposed changes up to a secure sandbox to be | |
| 492 | + reviewed by Claude/Codex/Copilot prior to commit. The sandbox is | |
| 493 | + not able to pull, for security reasons, but it can accept a push. | |
| 427 | 494 |
| --- www/hundredandone.md | |
| +++ www/hundredandone.md | |
| @@ -1,13 +1,13 @@ | |
| 1 | # 101 Reasons Why Fossil Is Better Than Git |
| 2 | |
| 3 | *This is a work in progress. I only have 38 reasons typed in so far, |
| 4 | but I have a separate text file of notes that lists 104 candidate reasons. |
| 5 | It's just taking me a while to compose and edit the rationale for each |
| 6 | one, so it seems expedient to check-in this draft.* |
| 7 | |
| 8 | 1. **Fossil comes as a single executable file**.<p> |
| 9 | Install Fossil by copying "fossil" (or "fossil.exe") to someplace |
| 10 | on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting |
| 11 | that one file. Uninstall by deleting that one file.<p> |
| 12 | A Git installation requires hundreds of files. You want to use |
| 13 | package manager to install, upgrade, or uninstall Git. If you |
| @@ -45,12 +45,12 @@ | |
| 45 | |
| 46 | 1. **In Fossil, a repository is distinct from a working check-out.**<p> |
| 47 | A Fossil repository can be colocated with the working check-out, as |
| 48 | they are required to be in Git. But most people keep the repository |
| 49 | separate. One common pattern is to put all Fossil repositories in |
| 50 | a single directory name $HOME/Fossils or $HOME/Museum, and then open |
| 51 | working check-outs against each repository whereever they are needed. |
| 52 | |
| 53 | 1. **A single Fossil repository can support multiple working check-outs.** |
| 54 | <p> |
| 55 | Git has worktrees, but all worktrees checkouts must be on separate |
| 56 | branches. Fossil allows multiple working check-outs on the same branch |
| @@ -65,17 +65,18 @@ | |
| 65 | You can "mv" a Fossil repository to a new place. You can "scp" |
| 66 | a Fossil repository to another machine. It is just a file, |
| 67 | specifically an SQLite database file. |
| 68 | |
| 69 | 1. **Fossil does not have a staging area**.</p> |
| 70 | A user-visible staging area adds no capabilities. (Partial commits |
| 71 | are accomplished in Fossil simply by listing the subset of files to |
| 72 | be committed on the "fossil commit" command line.) But the staging |
| 73 | area does complicate the mental model of the project that Git users |
| 74 | need to keep up with, forcing the developer to spend more time thinking |
| 75 | about the version control system and hence less time thinking about |
| 76 | the project they are working on. |
| 77 | |
| 78 | 1. **Fossil remembers where all your repositories and working |
| 79 | check-outs are located.**<p> |
| 80 | This and other information (such as all your global settings) |
| 81 | is stored in a per-user database file |
| @@ -99,35 +100,35 @@ | |
| 99 | If you are like me and have hundreds of repositories on your desktop |
| 100 | system, this feature makes it easier to keep track of them all. |
| 101 | Are you on an infrequently used travel laptop and forgot where you |
| 102 | put a particular repository, this feature helps you find it. |
| 103 | |
| 104 | 1. **Fossil allows multiple check-ins to have the same tag.**<p> |
| 105 | For example, on the SQLite project, every release is tagged with |
| 106 | "release". |
| 107 | |
| 108 | 1. **The Fossil timeline can show all check-ins with a specific tag.**<p> |
| 109 | For example, to see all SQLite releases visit |
| 110 | <https://sqlite.org/src/timeline?t=release> or to see all |
| 111 | Fossil releases go to |
| 112 | <https://fossil-scm.org/home/timeline?t=release>. |
| 113 | |
| 114 | 1. **Fossil has a built-in wiki**.<p> |
| 115 | Wiki pages are colocated in the same repository as your code, so that |
| 116 | they push, pull, sync, and clone together with your code. |
| 117 | |
| 118 | 1. **Fossil can associated a wiki page with a particular check-in.**<p> |
| 119 | Rather than including a massive and verbose check-in comment on an |
| 120 | important check-in (such as the merge of a big new feature), Fossil |
| 121 | allows you to assign a wiki page to that check-in. That wiki page |
| 122 | is show as part of the check-in information in the web interface. |
| 123 | See, for example, the "About" section of |
| 124 | [SQLite check-in 2019-11-21T18:28:44.463Z](https://sqlite.org/src/info/2019-11-21T18:28:44.463Z). |
| 125 | The wiki page associated with a check-in can be created and revised |
| 126 | after the check-in is comimtted and pushed. So it can be used, for |
| 127 | example, to add notes or bug reports that occur long after the |
| 128 | check-in itself has been inserted into the DAG. |
| 129 | |
| 130 | 1. **Fossil can associate a wiki page with a particular branch.**<p> |
| 131 | You can create a wiki page for a branch that documents the purpose |
| 132 | of the branch. The wiki page can be displayed separately (like any |
| 133 | other wiki page) but is also displayed automatically at the top of |
| @@ -142,56 +143,60 @@ | |
| 142 | "Whatever became of that setlk-snapshot-fix branch you |
| 143 | started last year?" That branch still exists and you |
| 144 | can [see it on GitHub](https://github.com/sqlite/sqlite/commits/setlk-snapshot-fix) |
| 145 | and [in Fossil](https://sqlite.org/src/timeline?r=setlk-snapshot-fix). |
| 146 | Notice, thought, that GitHub does not show how the branch was resolved. |
| 147 | Fossil clearly shows that the branch ended up being merged into trunk. |
| 148 | GitHub just shows us all ancestors of the leaf node labeled |
| 149 | "setlk-snapshot-fix", including ancestors that were in other branches |
| 150 | that got merged in, and ancestors that predate the founding of the |
| 151 | setlk-snapshot-fix branch. |
| 152 | <p> |
| 153 | GitHub just cannot shows you the check-ins of branch setlk-snapshot-fix |
| 154 | only. There are other third-party tools that will show you that, I am |
| 155 | told, but they all require a local clone of the repository. Apparently |
| 156 | there is no way to see this information in a web browser runnig on |
| 157 | your phone. |
| 158 | |
| 159 | 1. **Fossil allows multiple branches with the same name.**<p> |
| 160 | This feature is used a lot for branches named "experimental" and |
| 161 | "mistake". See |
| 162 | <https://sqlite.org/src/timeline?r=experimental> and |
| 163 | <https://sqlite.org/src/timeline?r=mistake>. Or see |
| 164 | [the empty-table-optimizations branch(es)](https://sqlite.org/src/timeline?r=empty-table-optimizations) which was initially merge to trunk and closed |
| 165 | on 2025-07-02, but then reopened and continued with more enhancements |
| 166 | until it was merged again on 2025-07-08. |
| 167 | |
| 168 | 1. **Fossil allows legacy SHA1 hashes and newer SHA3-256 hashes in the |
| 169 | same repository.**<p> |
| 170 | Both Fossil and Git started out using SHA1 hashes. But when the |
| 171 | SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) |
| 172 | against SHA1 was published on 2017-02-23, the need to migrate to a |
| 173 | stronger hash algorithm was recognized. Fossil added the ability |
| 174 | to use SHA3-256 as an alternative on 2017-03-01, and to this day |
| 175 | it continues to support both, though SHA3-256 is the default for all |
| 176 | new repositories and check-ins. But older check-ins that occurred |
| 177 | prior to ShAttered still use their original SHA1 hash and so no |
| 178 | repositories had to be rebuilt and no hyperlinks were broken.<p> |
| 179 | In contrast, a Git repository supports only one hash algorithm. |
| 180 | Newer repos can use SHA2, though the default is still SHA1. |
| 181 | |
| 182 | 1. **Fossil allows check-ins to be identified by timestamp**<p> |
| 183 | The canonical name for a check-in is its hash. Both Git and Fossil |
| 184 | allow a check-in to be identified by any unique prefix of its hash. |
| 185 | But only Fossil allows a check-in to also be identified by its |
| 186 | timestamp. The names "2026-02-02T16:03:24.852Z" and "fdebbedbd9a99165" |
| 187 | both refer to [the same check-in](https://sqlite.org/src/fdebbedbd9a99165) |
| 188 | in SQLite, but the first one has the advantage of giving some time |
| 189 | context rather than just being a seemingly random sequence of hexadecimal |
| 190 | digits. It is possible that two or more check-ins can have the same |
| 191 | timestamp, in which case the timestamp would be ambiguous. And a |
| 192 | check-in timestamp can be changed after it is committed, by using |
| 193 | a special tag. So timestamp identifiers do not have the uniqueness |
| 194 | and stability guarantees as hash identifiers, but they are available |
| 195 | as an option and are often useful. |
| 196 | |
| 197 | 1. **Fossil has a built-in forum.**<p> |
| @@ -234,22 +239,22 @@ | |
| 234 | The [autosync setting](/help/autosync), which defaults to "on", causes |
| 235 | every commit to automatically push to the default remote. This helps |
| 236 | to keep the remote up-to-date and helps all the developers working on |
| 237 | the software keep up with what other developers are doing. |
| 238 | <p> |
| 239 | Users whose prior experience is only with Git might object to |
| 240 | autosync, saying that this could cause all kinds of problems for Git |
| 241 | if another developer commits ahead of you. True enough, that would |
| 242 | cause headaches for Git, but it does not cause any problems for Fossil. |
| 243 | The worse that could happen is that the branch will fork. Fossil |
| 244 | will usually detect that a fork is about to happen and warn you. |
| 245 | But even if you don't get the warning (due to a race) or even if you |
| 246 | override the warning and force the commit anyhow, a fork on a branch |
| 247 | in Fossil is quite harmless. It shows cleanly on the timeline and |
| 248 | is easily resolved. So while autosync might case issues with Git, |
| 249 | it does not cause issues in Fossil and so the benefits far outweigh |
| 250 | the risks and autosync is the default behavior. |
| 251 | |
| 252 | 1. **Fossil supports embedded Pikchr in Wiki and in the Forum.**</p> |
| 253 | [Pikchr](https://pikchr.org/) is a |
| 254 | [PIC-like](https://en.wikipedia.org/wiki/Pic_language) markup language |
| 255 | for diagram. The diagrams that appear in the Fossil documentation are |
| @@ -276,11 +281,11 @@ | |
| 276 | Core Git does not have any kind of markup language. Check-in comments |
| 277 | in Git are always displayed verbatim. But wrappers such as GitHub, |
| 278 | GitLab, Gitea, Forgejo, and similar generally support some variant |
| 279 | of Markdown. However, none of these system support links (apart from |
| 280 | full URLs) to other wiki systems. Fossil does support interwiki links |
| 281 | using the syntax "<tt>remote:path</tt>". So, for example, a check-in |
| 282 | in the SQLite source repository (<https://sqlite.org/src>) that wants |
| 283 | to reference a bug report (perhaps because it fixes the bug) can |
| 284 | include a link of the form "<tt>bugs:/info/</tt><i>HASH</i>" to |
| 285 | reference that bug. The source repository knows that "bugs:" refers |
| 286 | to the [SQLite Bug Forum](https://sqlite.org/bugs) and completes the |
| @@ -293,44 +298,57 @@ | |
| 293 | to go stale, and (3) clone can have different mappings for |
| 294 | interwiki links, so that (for example) a "bugs:" link in a clone |
| 295 | of the source repository can map to a clone of the Bugs Forum |
| 296 | repository. |
| 297 | |
| 298 | 1. **Fossil has a built-in chat server**<p> |
| 299 | Users with appropriate permissions (usually just known and registered |
| 300 | developers, not anonymous passers-by) can bring up a web-based chat |
| 301 | server on any Fossil web-server instance. This feature allow |
| 302 | geographically distributed developers to collaborate interactively, |
| 303 | without having to involve a third-party chat provider such as Slack. |
| 304 | Fossil can be configured to automatically report new check-ins and |
| 305 | other activities as chat messages, so that developers are alerted to |
| 306 | changes. This feature is built-in to every Fossil web interface |
| 307 | and it works with any modern web browser. No extra plugins or |
| 308 | JS frameworks are required. Nothing need to be configured, other |
| 309 | that enabling the Chat privilege on the permission bits of the |
| 310 | users whom you want to have access to Chat. |
| 311 | |
| 312 | 1. **Fossil supports hyperlinks in check-in comments.**<p> |
| 313 | Check-in comments need not be just verbatim text (though they can |
| 314 | be depending on repository settings). By default, check-in |
| 315 | comments can contain hyperlinks, including hyperlinks to |
| 316 | wiki pages, prior check-ins, forum posts, and interwiki hyperlinks. |
| 317 | |
| 318 | 1. **Fossil supports hyperlink back references**<p> |
| 319 | If the check-in comment for a newer commits contains a hyperlink |
| 320 | back to an older commit, then when the web interface show the |
| 321 | details of the older commit, it also provides are forward |
| 322 | reference to the newer commit. |
| 323 | |
| 324 | 1. **Fossil supports a graphical timeline display of a bisect.**<p> |
| 325 | [For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). |
| 326 | This is not strictly necessary to make effective use of bisect, but |
| 327 | the graphical display does seem to help with situational awareness. |
| 328 | |
| 329 | 1. **Fossil allows you to revise a check-in comment without |
| 330 | rewriting history.**<p> |
| 331 | If you find a typo or other error in an historical check-in comment, |
| 332 | you can fix the problem in Fossil without having to rewrite all |
| 333 | subsequent history. The Fossil file format allows you to set |
| 334 | a special tag on the checkin you want to revise (actually a |
| 335 | "property", not a "tag", since it also carries a value - the new |
| 336 | comment text). The new tag causes both the command-line display |
| @@ -337,59 +355,59 @@ | |
| 337 | and the web interface to show the revised checkin comment rather |
| 338 | that the original. Note that the original checkin comment is |
| 339 | preserved, so there is still an immutable audit trail. But for |
| 340 | common use cases, only the new revised comment is shown. |
| 341 | <p> |
| 342 | If you are using the web interface and if you have check-in privilege |
| 343 | on the repository, then on the /info page for the check-in, under |
| 344 | the "Overview" section, to the right of "Other Links:", there is |
| 345 | an "edit" link that will take you to a page that lets you change |
| 346 | the check-in comment from the web interface. This is the easiest |
| 347 | way to make the change. |
| 348 | <p> |
| 349 | See [Fossil check-in b63d654041](/info/b63d65404) for a |
| 350 | recent example. The original comment is shown in the "Overview" |
| 351 | section of the checkin details, but the revised comment is show |
| 352 | in the timeline. |
| 353 | |
| 354 | 1. **Fossil allows you to revise a check-in timestamp without |
| 355 | rewriting history.**<p> |
| 356 | When generating a new checkin, Fossil uses the current time on the |
| 357 | system where the commit is occurring. But if the system clock on |
| 358 | that system is incorrect, that can lead to a check-in with an |
| 359 | inaccurate timestamp. It can be the case that prior check-ins |
| 360 | have later timestamps or that subsequent check-ins can have |
| 361 | earlier timestamps, resulting in goofy-looking "time-warps" in the |
| 362 | timeline. This can be correct by add a timestamp correction tag |
| 363 | to the faulty check-in to fix the timestamp. |
| 364 | <p> |
| 365 | If you are using the web interface and if you have check-in privilege |
| 366 | on the repository, then on the /info page for the check-in, under |
| 367 | the "Overview" section, to the right of "Other Links:", there is |
| 368 | an "edit" link that will take you to a page that lets you change |
| 369 | the timestamp for a check-in from the web interface. This is the |
| 370 | easiest way to make the change. |
| 371 | |
| 372 | 1. **Fossil allows you to move a check-in to a new branch without |
| 373 | rewriting history.**<p> |
| 374 | If you mistakenly commit to the wrong branch, you can move that |
| 375 | check-in to a new branch by attaching a special tag. |
| 376 | Note, however, that this will also move all subsequent check-ins |
| 377 | to that same new branch. |
| 378 | <p> |
| 379 | In the SQLite and Fossil projects, when developers mistakenly commit |
| 380 | on the wrong branch, the usual way we fix that is to move the |
| 381 | mistaken check-in to a branch named "mistake". Sometimes we also |
| 382 | set the "hidden" tag on that check-in as well, so that it does not |
| 383 | show up on ordinary timelines (though it is still part of the |
| 384 | immutable audit history and is visible with special options). |
| 385 | Then we just redo the commit on the correct branch. |
| 386 | <p> |
| 387 | If you are using the web interface and if you have check-in privilege |
| 388 | on the repository, then on the /info page for the check-in, under |
| 389 | the "Overview" section, to the right of "Other Links:", there is |
| 390 | an "edit" link that will take you to a page that lets move the check-in |
| 391 | to a new branch from the web interface. You can also do this |
| 392 | from the Fossil commit-line, but the web interface is easier and less |
| 393 | error prone. |
| 394 | |
| 395 | 1. **Fossil supports unversioned files**.<p> |
| @@ -396,11 +414,11 @@ | |
| 396 | [Unversioned Files](/doc/trunk/www/unvers.wiki) are files held |
| 397 | in the repository but which are not versioned are which are not |
| 398 | synced by default. Unversioned files are used by Fossil itself |
| 399 | to store [Precompiled Binaries of Fossil](/uv/download.html). |
| 400 | |
| 401 | 1. **Fossil automatically select checkin background colors according to |
| 402 | the branch that each checkin occurs on.**<p> |
| 403 | This helps to make the timeline easier to read at a glance, by |
| 404 | clearly showing which checkins are on which branches. Developers |
| 405 | can assign specific colors to branches either when the branch is |
| 406 | first created, or after the branch has been running for a while. |
| @@ -413,14 +431,63 @@ | |
| 413 | On the [/hash-color-test page](/hash-color-test), one can enter |
| 414 | candidate branch names and see in advance what colors Fossil will |
| 415 | pick for that branch name. This seems like cheating, but I will |
| 416 | admit that I do this myself, sometimes... |
| 417 | |
| 418 | 1. **The Fossil web interface timeline can be asked to pick check-in |
| 419 | colors according to the name of the committer, rather than the branch |
| 420 | name.**<p> |
| 421 | Simply add the "ubg" query parameter (mnemonic: User BackGround) and |
| 422 | the checkin colors will be determined by the committer login name |
| 423 | rather than the branch name or any preselected color name. This |
| 424 | results in a timeline that gives reader a clearer view of who is |
| 425 | making changes. |
| 426 | [Example](/timeline?n=200&y=ci&ubg). |
| 427 |
| --- www/hundredandone.md | |
| +++ www/hundredandone.md | |
| @@ -1,13 +1,13 @@ | |
| 1 | # 101 Reasons Why Fossil Is Better Than Git |
| 2 | |
| 3 | *This is a work in progress. I only have 38 reasons typed in so far, |
| 4 | but I have a separate text file of notes that lists 104 candidate reasons. |
| 5 | It's just taking me a while to compose and edit the rationale for each |
| 6 | one, so it seems expedient to checkin this draft.* |
| 7 | |
| 8 | 1. **Fossil comes as a single self-contained executable file**.<p> |
| 9 | Install Fossil by copying "fossil" (or "fossil.exe") to someplace |
| 10 | on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting |
| 11 | that one file. Uninstall by deleting that one file.<p> |
| 12 | A Git installation requires hundreds of files. You want to use |
| 13 | package manager to install, upgrade, or uninstall Git. If you |
| @@ -45,12 +45,12 @@ | |
| 45 | |
| 46 | 1. **In Fossil, a repository is distinct from a working check-out.**<p> |
| 47 | A Fossil repository can be colocated with the working check-out, as |
| 48 | they are required to be in Git. But most people keep the repository |
| 49 | separate. One common pattern is to put all Fossil repositories in |
| 50 | a single directory named $HOME/Fossils or $HOME/Museum, and then open |
| 51 | working check-outs against each repository whereever they are needed. |
| 52 | |
| 53 | 1. **A single Fossil repository can support multiple working check-outs.** |
| 54 | <p> |
| 55 | Git has worktrees, but all worktrees checkouts must be on separate |
| 56 | branches. Fossil allows multiple working check-outs on the same branch |
| @@ -65,17 +65,18 @@ | |
| 65 | You can "mv" a Fossil repository to a new place. You can "scp" |
| 66 | a Fossil repository to another machine. It is just a file, |
| 67 | specifically an SQLite database file. |
| 68 | |
| 69 | 1. **Fossil does not have a staging area**.</p> |
| 70 | A staging area adds no new capabilities. (Partial commits |
| 71 | are accomplished in Fossil simply by listing the subset of files to |
| 72 | be committed on the "fossil commit" command line.) A staging area |
| 73 | only adds complication. The staging area adds to the mental model |
| 74 | of the project that Git users need to keep up with, forcing the |
| 75 | developer to spend more time thinking about the version control |
| 76 | system and hence less time thinking about the project they are |
| 77 | working on. |
| 78 | |
| 79 | 1. **Fossil remembers where all your repositories and working |
| 80 | check-outs are located.**<p> |
| 81 | This and other information (such as all your global settings) |
| 82 | is stored in a per-user database file |
| @@ -99,35 +100,35 @@ | |
| 100 | If you are like me and have hundreds of repositories on your desktop |
| 101 | system, this feature makes it easier to keep track of them all. |
| 102 | Are you on an infrequently used travel laptop and forgot where you |
| 103 | put a particular repository, this feature helps you find it. |
| 104 | |
| 105 | 1. **Fossil allows multiple checkins to have the same tag.**<p> |
| 106 | For example, on the SQLite project, every release is tagged with |
| 107 | "release". |
| 108 | |
| 109 | 1. **The Fossil timeline can show all checkins with a specific tag.**<p> |
| 110 | For example, to see all SQLite releases visit |
| 111 | <https://sqlite.org/src/timeline?t=release> or to see all |
| 112 | Fossil releases go to |
| 113 | <https://fossil-scm.org/home/timeline?t=release>. |
| 114 | |
| 115 | 1. **Fossil has a built-in wiki**.<p> |
| 116 | Wiki pages are colocated in the same repository as your code, so that |
| 117 | they push, pull, sync, and clone together with your code. |
| 118 | |
| 119 | 1. **Fossil can associated a wiki page with a particular checkin.**<p> |
| 120 | Rather than including a massive and verbose checkin comment on an |
| 121 | important checkin (such as the merge of a big new feature), Fossil |
| 122 | allows you to assign a wiki page to that checkin. That wiki page |
| 123 | is show as part of the checkin information in the web interface. |
| 124 | See, for example, the "About" section of |
| 125 | [SQLite checkin 2019-11-21T18:28:44.463Z](https://sqlite.org/src/info/2019-11-21T18:28:44.463Z). |
| 126 | The wiki page associated with a checkin can be created and revised |
| 127 | after the checkin is comimtted and pushed. So it can be used, for |
| 128 | example, to add notes or bug reports that occur long after the |
| 129 | checkin itself has been inserted into the DAG. |
| 130 | |
| 131 | 1. **Fossil can associate a wiki page with a particular branch.**<p> |
| 132 | You can create a wiki page for a branch that documents the purpose |
| 133 | of the branch. The wiki page can be displayed separately (like any |
| 134 | other wiki page) but is also displayed automatically at the top of |
| @@ -142,56 +143,60 @@ | |
| 143 | "Whatever became of that setlk-snapshot-fix branch you |
| 144 | started last year?" That branch still exists and you |
| 145 | can [see it on GitHub](https://github.com/sqlite/sqlite/commits/setlk-snapshot-fix) |
| 146 | and [in Fossil](https://sqlite.org/src/timeline?r=setlk-snapshot-fix). |
| 147 | Notice, thought, that GitHub does not show how the branch was resolved. |
| 148 | (Aside: Also notice how much faster Fossil renders!) |
| 149 | Fossil clearly shows that the branch ended up being merged into trunk. |
| 150 | GitHub just shows us all ancestors of the leaf node labeled |
| 151 | "setlk-snapshot-fix", including ancestors that were in other branches |
| 152 | that got merged in, and ancestors that predate the founding of the |
| 153 | setlk-snapshot-fix branch. |
| 154 | <p> |
| 155 | GitHub just cannot shows you the checkins of branch setlk-snapshot-fix |
| 156 | only. There are other third-party tools that will show you that, I am |
| 157 | told, but they all require a local clone of the repository. Apparently |
| 158 | there is no way to see this information in a web browser runnig on |
| 159 | your phone. |
| 160 | |
| 161 | 1. **Fossil allows multiple branches with the same name.**<p> |
| 162 | This is used, for example, to name a lot for branches "experimental" |
| 163 | and mistake". See |
| 164 | <https://sqlite.org/src/timeline?r=experimental> and |
| 165 | <https://sqlite.org/src/timeline?r=mistake>. Or see |
| 166 | [the empty-table-optimizations branch(es)](https://sqlite.org/src/timeline?r=empty-table-optimizations) which was initially mergde to trunk and closed |
| 167 | on 2025-07-02, but then reopened and continued with more enhancements |
| 168 | until it was merged again on 2025-07-08. |
| 169 | |
| 170 | 1. **Fossil allows legacy SHA1 hashes and newer SHA3-256 hashes in the |
| 171 | same repository.**<p> |
| 172 | Both Fossil and Git started out using SHA1 hashes. But when the |
| 173 | [SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) |
| 174 | against SHA1 was published on 2017-02-23, the need to migrate to a |
| 175 | stronger hash algorithm was recognized. Fossil added the ability |
| 176 | to use SHA3-256 as an alternative on 2017-03-01 (six days after the |
| 177 | attack was first published), and to this day |
| 178 | it continues to support both. SHA3-256 is now the default for all |
| 179 | new repositories and checkins, though older checkins that occurred |
| 180 | prior to ShAttered can still use their original SHA1 hash and so no |
| 181 | repositories had to be rebuilt and no hyperlinks were broken.<p> |
| 182 | In contrast, after nine years, a Git repository can still only |
| 183 | support only one hash algorithm at a time. |
| 184 | Newer Git repositories are able to use SHA2, though the default |
| 185 | is still SHA1. |
| 186 | |
| 187 | 1. **Fossil allows checkins to be identified by timestamp**<p> |
| 188 | The canonical name for a checkin is its hash. Both Git and Fossil |
| 189 | allow a checkin to be identified by any unique prefix of its hash. |
| 190 | But only Fossil allows a checkin to also be identified by its |
| 191 | timestamp. The names "2026-02-02T16:03:24.852Z" and "fdebbedbd9a99165" |
| 192 | both refer to [the same checkin](https://sqlite.org/src/fdebbedbd9a99165) |
| 193 | in SQLite, but the first one has the advantage of giving some time |
| 194 | context rather than just being a seemingly random sequence of hexadecimal |
| 195 | digits. It is possible that two or more checkins can have the same |
| 196 | timestamp, in which case the timestamp would be ambiguous. And a |
| 197 | checkin timestamp can be changed after it is committed, by using |
| 198 | a special tag. So timestamp identifiers do not have the uniqueness |
| 199 | and stability guarantees as hash identifiers, but they are available |
| 200 | as an option and are often useful. |
| 201 | |
| 202 | 1. **Fossil has a built-in forum.**<p> |
| @@ -234,22 +239,22 @@ | |
| 239 | The [autosync setting](/help/autosync), which defaults to "on", causes |
| 240 | every commit to automatically push to the default remote. This helps |
| 241 | to keep the remote up-to-date and helps all the developers working on |
| 242 | the software keep up with what other developers are doing. |
| 243 | <p> |
| 244 | Long-time Git users might cringe at autosync, thinking that this |
| 245 | could cause problems if another developer commits ahead of you. |
| 246 | True enough, that would cause headaches for Git, but it does not |
| 247 | create problems for Fossil. |
| 248 | The worse that could happen is that the branch will fork. Fossil |
| 249 | will usually detect an impending fork and warn you. |
| 250 | But even if you don't get the warning (due to a race) or even if you |
| 251 | override the warning and force the commit anyhow, a fork on a branch |
| 252 | in Fossil is harmless. It shows cleanly on the timeline and |
| 253 | is easily resolved. So while autosync might cause issues with Git, |
| 254 | it is harmless to Fossil. Since forks are harmless, the benefits |
| 255 | of autosync far outweigh the risks. |
| 256 | |
| 257 | 1. **Fossil supports embedded Pikchr in Wiki and in the Forum.**</p> |
| 258 | [Pikchr](https://pikchr.org/) is a |
| 259 | [PIC-like](https://en.wikipedia.org/wiki/Pic_language) markup language |
| 260 | for diagram. The diagrams that appear in the Fossil documentation are |
| @@ -276,11 +281,11 @@ | |
| 281 | Core Git does not have any kind of markup language. Check-in comments |
| 282 | in Git are always displayed verbatim. But wrappers such as GitHub, |
| 283 | GitLab, Gitea, Forgejo, and similar generally support some variant |
| 284 | of Markdown. However, none of these system support links (apart from |
| 285 | full URLs) to other wiki systems. Fossil does support interwiki links |
| 286 | using the syntax "<tt>remote:path</tt>". So, for example, a checkin |
| 287 | in the SQLite source repository (<https://sqlite.org/src>) that wants |
| 288 | to reference a bug report (perhaps because it fixes the bug) can |
| 289 | include a link of the form "<tt>bugs:/info/</tt><i>HASH</i>" to |
| 290 | reference that bug. The source repository knows that "bugs:" refers |
| 291 | to the [SQLite Bug Forum](https://sqlite.org/bugs) and completes the |
| @@ -293,44 +298,57 @@ | |
| 298 | to go stale, and (3) clone can have different mappings for |
| 299 | interwiki links, so that (for example) a "bugs:" link in a clone |
| 300 | of the source repository can map to a clone of the Bugs Forum |
| 301 | repository. |
| 302 | |
| 303 | 1. **Fossil has a built-in chat server.**<p> |
| 304 | Users with appropriate permissions (usually just known and registered |
| 305 | developers, not anonymous passers-by) can bring up a web-based chat |
| 306 | server on any Fossil web-server instance. This feature allow |
| 307 | geographically distributed developers to collaborate interactively, |
| 308 | without having to involve a third-party chat provider such as Slack. |
| 309 | Nothing need to be configured in order to activate Chat, other |
| 310 | that enabling the Chat privilege on the permission bits of the |
| 311 | users whom you want to have access to Chat. |
| 312 | |
| 313 | 1. **Fossil chat can be configured to send automatic notifications |
| 314 | when changes occur in the repository.**<p> |
| 315 | This helps developers keep up with what is happening in the repository. |
| 316 | The chat window beeps (or not, configurable individually by each user) |
| 317 | when new messages arrive, as an alert. |
| 318 | |
| 319 | 1. **The Fossil Chat system has hooks that allow external subsystems |
| 320 | to inject chat message.**<p> |
| 321 | The SQLite developers use this to get notifications of testing |
| 322 | failures from our fuzz testing infrastructure. It could also |
| 323 | be leveraged to get chat notifications of CI/CD problems. |
| 324 | |
| 325 | 1. **Fossil chat is able to send attachments.**<p> |
| 326 | When the SQLite developers are working collaboratively on a problem |
| 327 | (while sitting, literally, in three different continents) we easily |
| 328 | send patches or diffs to one another over Chat. |
| 329 | |
| 330 | 1. **Fossil supports hyperlinks in checkin comments.**<p> |
| 331 | Check-in comments need not be just verbatim text (though they can |
| 332 | be depending on repository settings). By default, checkin |
| 333 | comments can contain hyperlinks, including hyperlinks to |
| 334 | wiki pages, prior checkins, forum posts, and interwiki hyperlinks. |
| 335 | |
| 336 | 1. **Fossil supports hyperlink back references**<p> |
| 337 | If the checkin comment for a newer commits contains a hyperlink |
| 338 | back to an older commit, then when the web interface show the |
| 339 | details of the older commit, it also provides are forward |
| 340 | reference to the newer commit. |
| 341 | |
| 342 | 1. **Fossil supports a graphical timeline display of a bisect.**<p> |
| 343 | [For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). |
| 344 | This is not strictly necessary to make effective use of bisect, but |
| 345 | the graphical display does seem to help with situational awareness. |
| 346 | |
| 347 | 1. **Fossil allows you to revise a checkin comment without |
| 348 | rewriting history.**<p> |
| 349 | If you find a typo or other error in an historical checkin comment, |
| 350 | you can fix the problem in Fossil without having to rewrite all |
| 351 | subsequent history. The Fossil file format allows you to set |
| 352 | a special tag on the checkin you want to revise (actually a |
| 353 | "property", not a "tag", since it also carries a value - the new |
| 354 | comment text). The new tag causes both the command-line display |
| @@ -337,59 +355,59 @@ | |
| 355 | and the web interface to show the revised checkin comment rather |
| 356 | that the original. Note that the original checkin comment is |
| 357 | preserved, so there is still an immutable audit trail. But for |
| 358 | common use cases, only the new revised comment is shown. |
| 359 | <p> |
| 360 | If you are using the web interface and if you have checkin privilege |
| 361 | on the repository, then on the /info page for the checkin, under |
| 362 | the "Overview" section, to the right of "Other Links:", there is |
| 363 | an "edit" link that will take you to a page that lets you change |
| 364 | the checkin comment from the web interface. This is the easiest |
| 365 | way to make the change. |
| 366 | <p> |
| 367 | See [Fossil checkin b63d654041](/info/b63d65404) for a |
| 368 | recent example. The original comment is shown in the "Overview" |
| 369 | section of the checkin details, but the revised comment is show |
| 370 | in the timeline. |
| 371 | |
| 372 | 1. **Fossil allows you to revise a checkin timestamp without |
| 373 | rewriting history.**<p> |
| 374 | When generating a new checkin, Fossil uses the current time on the |
| 375 | system where the commit is occurring. But if the system clock on |
| 376 | that system is incorrect, that can lead to a checkin with an |
| 377 | inaccurate timestamp. It can be the case that prior checkins |
| 378 | have later timestamps or that subsequent checkins can have |
| 379 | earlier timestamps, resulting in goofy-looking "time-warps" in the |
| 380 | timeline. This can be correct by add a timestamp correction tag |
| 381 | to the faulty checkin to fix the timestamp. |
| 382 | <p> |
| 383 | If you are using the web interface and if you have checkin privilege |
| 384 | on the repository, then on the /info page for the checkin, under |
| 385 | the "Overview" section, to the right of "Other Links:", there is |
| 386 | an "edit" link that will take you to a page that lets you change |
| 387 | the timestamp for a checkin from the web interface. This is the |
| 388 | easiest way to make the change. |
| 389 | |
| 390 | 1. **Fossil allows you to move a checkin to a new branch without |
| 391 | rewriting history.**<p> |
| 392 | If you mistakenly commit to the wrong branch, you can move that |
| 393 | checkin to a new branch by attaching a special tag. |
| 394 | Note, however, that this will also move all subsequent checkins |
| 395 | to that same new branch. |
| 396 | <p> |
| 397 | In the SQLite and Fossil projects, when developers mistakenly commit |
| 398 | on the wrong branch, the usual way we fix that is to move the |
| 399 | mistaken checkin to a branch named "mistake". Sometimes we also |
| 400 | set the "hidden" tag on that checkin as well, so that it does not |
| 401 | show up on ordinary timelines (though it is still part of the |
| 402 | immutable audit history and is visible with special options). |
| 403 | Then we just redo the commit on the correct branch. |
| 404 | <p> |
| 405 | If you are using the web interface and if you have checkin privilege |
| 406 | on the repository, then on the /info page for the checkin, under |
| 407 | the "Overview" section, to the right of "Other Links:", there is |
| 408 | an "edit" link that will take you to a page that lets move the checkin |
| 409 | to a new branch from the web interface. You can also do this |
| 410 | from the Fossil commit-line, but the web interface is easier and less |
| 411 | error prone. |
| 412 | |
| 413 | 1. **Fossil supports unversioned files**.<p> |
| @@ -396,11 +414,11 @@ | |
| 414 | [Unversioned Files](/doc/trunk/www/unvers.wiki) are files held |
| 415 | in the repository but which are not versioned are which are not |
| 416 | synced by default. Unversioned files are used by Fossil itself |
| 417 | to store [Precompiled Binaries of Fossil](/uv/download.html). |
| 418 | |
| 419 | 1. **Fossil automatically selects checkin background colors according to |
| 420 | the branch that each checkin occurs on.**<p> |
| 421 | This helps to make the timeline easier to read at a glance, by |
| 422 | clearly showing which checkins are on which branches. Developers |
| 423 | can assign specific colors to branches either when the branch is |
| 424 | first created, or after the branch has been running for a while. |
| @@ -413,14 +431,63 @@ | |
| 431 | On the [/hash-color-test page](/hash-color-test), one can enter |
| 432 | candidate branch names and see in advance what colors Fossil will |
| 433 | pick for that branch name. This seems like cheating, but I will |
| 434 | admit that I do this myself, sometimes... |
| 435 | |
| 436 | 1. **The Fossil web interface timeline can be asked to pick checkin |
| 437 | colors according to the name of the committer, rather than the branch |
| 438 | name.**<p> |
| 439 | Simply add the "ubg" query parameter (mnemonic: User BackGround) and |
| 440 | the checkin colors will be determined by the committer login name |
| 441 | rather than the branch name or any preselected color name. This |
| 442 | results in a timeline that gives reader a clearer view of who is |
| 443 | making changes. |
| 444 | [Example](/timeline?n=200&y=ci&ubg). |
| 445 | |
| 446 | 1. **Fossil tracks cherrypick merges.**<p> |
| 447 | Cherrypicks are recorded as part of the underlying |
| 448 | [Fossil file format](/doc/trunk/www/fileformat.wiki). |
| 449 | Cherrypicks appear on the timeline as thin dashed lines. |
| 450 | |
| 451 | 1. **Fossil draws arrows pointing forwards in time.**<p> |
| 452 | Forward-pointing arrows are far more intuitive than arrows |
| 453 | that point backwards in times, like Git uses. Yes, I am aware |
| 454 | that the underlying implementation of Git has pointers going from child |
| 455 | to parent, and thus must necessarily go backwards in time. Fossil |
| 456 | has the same pointers. But just because the *implementation* |
| 457 | points backwards in time does not mean that the *user interface* |
| 458 | needs to do the same. Fossil flips those pointers around so that |
| 459 | they make more sense from the perspective of the human reader. |
| 460 | |
| 461 | 1. **Fossil implements some unix-like shell commands to use as |
| 462 | substitutes on systems that don't have them or that have inferior |
| 463 | implementations.**<p> |
| 464 | For example the "fossil system ls" command works like the standard |
| 465 | "ls" command on unix. It doesn't support all the options that a typical |
| 466 | "ls" implementation supports on Linux, but it is still way better than |
| 467 | having to run "dir". Other substitute commands include |
| 468 | "date", "pwd", "stty", "unzip", "which", and "zip". Probably |
| 469 | more will be added as needs arise. Having ready access to these |
| 470 | commands built into the standalone Fossil binary makes working on |
| 471 | non-Linux platforms more comfortable for unix geeks, and saves having |
| 472 | to hunt around and install system-specific alternatives. |
| 473 | |
| 474 | 1. **Fossil can transfer all uncommited changes from a check-out on a |
| 475 | remote system over to a check-out on the local machine.**<p> |
| 476 | The command is [fossil patch pull](/help?patch). It contacts the |
| 477 | remote system via SSH, updates its local check-out to the same baseline |
| 478 | as is found on the remote, then pulls over a minimal set of diffs and |
| 479 | applies them.<p> |
| 480 | This is very useful in pre-commit testing. For example, if you have |
| 481 | a big change on your desktop, and you want to test it before |
| 482 | committing, on multiple platforms, you can ssh over to those other |
| 483 | platforms and run "fossil patch pull ... && make test". When working |
| 484 | on SQLite, I will typically do that on a remote Mac, and remote |
| 485 | Win11 machine, and on a 32-core remote Linux machine that runs |
| 486 | faster than my desktop. |
| 487 | |
| 488 | 1. **Fossil can push uncommitted chagnes to a remote check-out for the |
| 489 | same project.**<p> |
| 490 | This is the same as the previous but in reverse. It is used, for |
| 491 | example, to push proposed changes up to a secure sandbox to be |
| 492 | reviewed by Claude/Codex/Copilot prior to commit. The sandbox is |
| 493 | not able to pull, for security reasons, but it can accept a push. |
| 494 |