Fossil SCM
Proofreading changes to the 101-document.
Commit
d494477e0a0bd7e17f1aab8c50697642a4c32a79f67c5477ffba961b6c04e5f0
Parent
4f5533bd00ebc07…
1 file changed
+123
-123
+123
-123
| --- www/hundredandone.md | ||
| +++ www/hundredandone.md | ||
| @@ -2,11 +2,11 @@ | ||
| 2 | 2 | |
| 3 | 3 | 1. **Fossil comes as a single self-contained executable file**.<p> |
| 4 | 4 | Install Fossil by copying "fossil" (or "fossil.exe") to someplace |
| 5 | 5 | on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting |
| 6 | 6 | that one file. Uninstall by deleting that one file.<p> |
| 7 | - A Git installation requires hundreds of files. You want to use | |
| 7 | + A Git installation requires hundreds of files. You want to use a | |
| 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> |
| @@ -38,19 +38,19 @@ | ||
| 38 | 38 | timeline is available via a web interface, as far as I know.<p> |
| 39 | 39 | Using the web interface, one can easily check on the status |
| 40 | 40 | of a project when away from the office and without access to a clone |
| 41 | 41 | of the repository. |
| 42 | 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: | |
| 43 | + 1. **The Fossil web interface view of a single check-in shows a | |
| 44 | + context graph of all other directly connected check-ins.**<p> | |
| 45 | + See the page for [check-in 59985724d71229bf](/info/59985724d71229bf) | |
| 46 | + for example. The context graph shows four other check-ins: | |
| 47 | 47 | two direct descendants, one merge descendant, and one ancestor. |
| 48 | 48 | This context graph is useful in understanding how a particular |
| 49 | - checkin fits into the history of the project. The context graph | |
| 49 | + check-in fits into the history of the project. The context graph | |
| 50 | 50 | can also be used to step forwards or backwards in time, by |
| 51 | - clicking on the "check-in:" hash links for nearby checkins. | |
| 51 | + clicking on the "check-in:" hash links for nearby check-ins. | |
| 52 | 52 | |
| 53 | 53 | 1. **The graphical timeline dynamically adjusts its layout as you resize |
| 54 | 54 | your browser window.**<p> |
| 55 | 55 | The server sends down an HTML page that contains (among other things) |
| 56 | 56 | a JSON object that gives the basic structure of the |
| @@ -60,11 +60,11 @@ | ||
| 60 | 60 | is completely stand-alone. The local |
| 61 | 61 | web browser isn't required to go gather lots of separate resources. |
| 62 | 62 | |
| 63 | 63 | 1. **The graphical timeline works on a phone.**<p> |
| 64 | 64 | The graph layout automatically compresses on a small display, and |
| 65 | - can seem a little cramped for a complex project. The timeline does | |
| 65 | + can seem a little cramped for a complex project. The timeline | |
| 66 | 66 | does look better on a desktop. Even so, the timeline display is |
| 67 | 67 | functional on a phone and it is very convenient |
| 68 | 68 | to be able to see what is happening on a project |
| 69 | 69 | while away from the office and without access to a laptop. |
| 70 | 70 | |
| @@ -77,40 +77,40 @@ | ||
| 77 | 77 | of recent check-ins without any indication of the branching |
| 78 | 78 | structure, whereas Fossil gives you an easy-to-read color-coded |
| 79 | 79 | graph. |
| 80 | 80 | |
| 81 | 81 | 1. **The Fossil web interface makes it easy to see a diff between |
| 82 | - any two checkins with just a couple of clicks.**<p> | |
| 82 | + any two check-ins with just a couple of clicks.**<p> | |
| 83 | 83 | On the timeline display, click on one node of the graph to |
| 84 | 84 | select it (a red dot will appear in the center of the node) and |
| 85 | 85 | then click on any other graph node, and Fossil will compute and |
| 86 | 86 | display a diff between those two check-ins. (Usage hint: |
| 87 | 87 | click the selected node a second time to deselect it.) |
| 88 | 88 | |
| 89 | 89 | 1. **The Fossil web-based diff page shows the context of the two |
| 90 | - checkins being diffed.**<p> | |
| 90 | + check-ins being diffed.**<p> | |
| 91 | 91 | At the top of the web-based diff is a graph that shows |
| 92 | - specifically the two checkins being diffed and the context | |
| 92 | + specifically the two check-ins being diffed and the context | |
| 93 | 93 | around them. |
| 94 | 94 | [Example](/vdiff?from=052390edaf04a5f5&to=9b686daeeda7b4ca). |
| 95 | 95 | This helps to reduce any confusion about what you are looking at. |
| 96 | 96 | |
| 97 | 97 | 1. **In Fossil, a repository is distinct from a working checkout.**<p> |
| 98 | 98 | A Fossil repository can be colocated with the working checkout, as |
| 99 | 99 | they are required to be in Git. But most people keep the repository |
| 100 | 100 | separate. One common pattern is to put all Fossil repositories in |
| 101 | 101 | a single directory named $HOME/Fossils or $HOME/Museum and then open |
| 102 | - working checkouts against each repository whereever they are needed. | |
| 102 | + working checkouts against each repository wherever they are needed. | |
| 103 | 103 | |
| 104 | 104 | 1. **A single Fossil repository can support multiple working checkouts.** |
| 105 | 105 | <p> |
| 106 | 106 | Git has worktrees, but all worktrees checkouts must be on separate |
| 107 | 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 | |
| 108 | + or even on the same check-in. One common pattern is to have one | |
| 109 | + checkout that is being edited, and another that is a pristine, unedited | |
| 110 | + version of the same check-in. This allows both to be compiled | |
| 111 | + simultaneously for performance comparison, or to step through both | |
| 112 | 112 | binaries in two separate "gdb" sessions to hunt down a bug. |
| 113 | 113 | |
| 114 | 114 | 1. **A Fossil repository is a single disk file, not a directory |
| 115 | 115 | hierarchy.**<p> |
| 116 | 116 | You can "mv" a Fossil repository to a new place. You can "scp" |
| @@ -134,20 +134,20 @@ | ||
| 134 | 134 | checkouts are located.**<p> |
| 135 | 135 | This and other information (such as all your global settings) |
| 136 | 136 | is stored in a per-user database file |
| 137 | 137 | at $HOME/.config/fossil.db on unix or in %LOCALAPPDATA%/_fossil on |
| 138 | 138 | Windows. Fossil creates and manages that file automatically. |
| 139 | - The user never has know the file even exists. If you | |
| 139 | + The user never has to know the file even exists. If you | |
| 140 | 140 | move or rename repositories or checkouts, the database will get |
| 141 | 141 | temporarily out of sync with reality, but Fossil will automatically |
| 142 | 142 | fix the database the next time you do anything with the file or |
| 143 | 143 | checkout that was moved or renamed.<p> |
| 144 | 144 | You can get a list of repositories using the |
| 145 | 145 | "<tt>fossil all ls</tt>" command, or a list of open |
| 146 | 146 | checkouts using "<tt>fossil all ls --ckout</tt>". |
| 147 | 147 | |
| 148 | - 1. **Fossil lets you to bring up a web-based UI that shows all of | |
| 148 | + 1. **Fossil lets you bring up a web-based UI that shows all of | |
| 149 | 149 | your repositories at once.**<p> |
| 150 | 150 | Run the command "<tt>fossil ui /</tt>" and your |
| 151 | 151 | default web browser will pop up a new tab that lists all of your |
| 152 | 152 | repositories together with the |
| 153 | 153 | associated project name and how recently that repository was modified. |
| @@ -174,45 +174,45 @@ | ||
| 174 | 174 | While off-network, you might commit changes to one or |
| 175 | 175 | more of those repositories. Once you reconnect, you simply |
| 176 | 176 | run "<tt>fossil all sync</tt>" again to push out your edits |
| 177 | 177 | back to the community. |
| 178 | 178 | |
| 179 | - 1. **Fossil allows multiple checkins to have the same tag.**<p> | |
| 179 | + 1. **Fossil allows multiple check-ins to have the same tag.**<p> | |
| 180 | 180 | For example, on the SQLite project, every release is tagged with |
| 181 | 181 | "release". |
| 182 | 182 | |
| 183 | - 1. **The Fossil timeline can show all checkins with a specific tag.**<p> | |
| 183 | + 1. **The Fossil timeline can show all check-ins with a specific tag.**<p> | |
| 184 | 184 | For example, to see all SQLite releases visit |
| 185 | 185 | <https://sqlite.org/src/timeline?t=release> or to see all |
| 186 | 186 | Fossil releases go to |
| 187 | 187 | <https://fossil-scm.org/home/timeline?t=release>. |
| 188 | 188 | |
| 189 | 189 | 1. **Fossil has a built-in wiki**.<p> |
| 190 | 190 | Wiki pages are stored in the same repository file as your code, so that |
| 191 | 191 | they push, pull, sync, and clone together with your code. |
| 192 | 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. | |
| 193 | + 1. **Fossil can associate a wiki page with a particular check-in.**<p> | |
| 194 | + Rather than including an oversized check-in comment on an | |
| 195 | + important check-in (such as the merge of a big new feature), Fossil | |
| 196 | + allows you to assign a wiki page to that check-in. That wiki page | |
| 197 | + is shown as part of the check-in information in the web interface. | |
| 198 | 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 | |
| 199 | + [SQLite check-in 2019-11-21T18:28:44.463Z](https://sqlite.org/src/info/2019-11-21T18:28:44.463Z). | |
| 200 | + The wiki page associated with a check-in can be created and revised | |
| 201 | + after the check-in is committed and pushed. This feature can be used | |
| 202 | 202 | to add notes or bug reports that occur long after the |
| 203 | - checkin itself has been inserted into the DAG. | |
| 203 | + check-in itself has been inserted into the DAG. | |
| 204 | 204 | |
| 205 | 205 | 1. **Fossil can associate a wiki page with a particular branch.**<p> |
| 206 | 206 | You can create a wiki page for a branch that documents the purpose |
| 207 | 207 | of that branch. The wiki page can be displayed separately (like any |
| 208 | 208 | other wiki page) but is also displayed automatically at the top of |
| 209 | 209 | every timeline for that branch. See, for example, |
| 210 | 210 | <https://sqlite.org/src/timeline?r=autosetup>. |
| 211 | 211 | |
| 212 | 212 | 1. **Fossil keeps track of historical branch names.**<p> |
| 213 | - Git does not track of branches. Git only names each leaf | |
| 213 | + Git does not track branches. Git only names each leaf | |
| 214 | 214 | of the DAG and infers branches based on the names of leaves. |
| 215 | 215 | Fossil actually remembers the name of branches. |
| 216 | 216 | For example, suppose a customer asks |
| 217 | 217 | "Whatever became of that setlk-snapshot-fix branch you |
| 218 | 218 | started last year?" That branch still exists and you can |
| @@ -224,11 +224,11 @@ | ||
| 224 | 224 | GitHub just shows us all ancestors of the leaf node labeled |
| 225 | 225 | "setlk-snapshot-fix", including ancestors that were in other branches |
| 226 | 226 | that got merged in, and ancestors that predate the founding of the |
| 227 | 227 | setlk-snapshot-fix branch. |
| 228 | 228 | <p> |
| 229 | - GitHub is unable to show you the checkins of branch setlk-snapshot-fix | |
| 229 | + GitHub is unable to show you the check-ins of branch setlk-snapshot-fix | |
| 230 | 230 | only. There are other third-party tools that will show you that, I am |
| 231 | 231 | told, but they all require a local clone of the repository. Apparently |
| 232 | 232 | there is no way to see this information in a web browser using Git, |
| 233 | 233 | with or without third-party tools. |
| 234 | 234 | |
| @@ -257,38 +257,38 @@ | ||
| 257 | 257 | [SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) |
| 258 | 258 | against SHA1 was published on 2017-02-23, the need to migrate to a |
| 259 | 259 | stronger hash algorithm was recognized. Fossil added the ability |
| 260 | 260 | to use SHA3-256 as an alternative on 2017-03-01 (six days after the |
| 261 | 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, | |
| 262 | + SHA3-256 is now the default for all new repositories and check-ins | |
| 263 | + in Fossil, though older check-ins that occurred | |
| 264 | + prior to SHAttered can still use their original SHA1 hash. Hence, | |
| 265 | 265 | no repositories had to be rebuilt and no hyperlinks were broken.<p> |
| 266 | 266 | In contrast, after nine years, a Git repository can still only |
| 267 | - support only one hash algorithm at a time. | |
| 267 | + support one hash algorithm at a time. | |
| 268 | 268 | Newer Git repositories are able to use SHA2, though the default |
| 269 | 269 | is still SHA1. |
| 270 | 270 | |
| 271 | - 1. **Fossil allows checkins to be identified by timestamp**<p> | |
| 272 | - The canonical name for a checkin is its hash. Both Git and Fossil | |
| 273 | - allow a checkin to be identified by any unique prefix of its hash. | |
| 274 | - But only Fossil allows a checkin to also be identified by its | |
| 271 | + 1. **Fossil allows check-ins to be identified by timestamp**<p> | |
| 272 | + The canonical name for a check-in is its hash. Both Git and Fossil | |
| 273 | + allow a check-in to be identified by any unique prefix of its hash. | |
| 274 | + But only Fossil allows a check-in to also be identified by its | |
| 275 | 275 | timestamp. The names "2026-02-02T16:03:24.852Z" and "fdebbedbd9a99165" |
| 276 | - both refer to [the same checkin](https://sqlite.org/src/fdebbedbd9a99165), | |
| 276 | + both refer to [the same check-in](https://sqlite.org/src/fdebbedbd9a99165), | |
| 277 | 277 | but the first one has the advantage of giving some time |
| 278 | 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 | |
| 279 | + digits. It is possible that two or more check-ins can have the same | |
| 280 | 280 | timestamp, in which case the timestamp would be ambiguous. And a |
| 281 | - checkin timestamp can be changed after it is committed, by using | |
| 281 | + check-in timestamp can be changed after it is committed, by using | |
| 282 | 282 | a special tag. So timestamp identifiers do not have the uniqueness |
| 283 | 283 | and stability guarantees as hash identifiers, but they are available |
| 284 | 284 | as an option and are often useful. |
| 285 | 285 | |
| 286 | 286 | 1. **Fossil has a built-in forum.**<p> |
| 287 | 287 | The forum content is replicated via push, pull, sync, and clone just like |
| 288 | - source code. Forum posts can be enabled per user or for all user or | |
| 289 | - for all users and anonymous passers-by. Some user can be appointed | |
| 288 | + source code. Forum posts can be enabled per user or for all users or | |
| 289 | + for all users and anonymous passers-by. Some users can be appointed | |
| 290 | 290 | as moderators and posts from untrusted users can be held for |
| 291 | 291 | moderation. |
| 292 | 292 | <p> |
| 293 | 293 | The [Fossil Forum](https://fossil-scm.org/forum), the |
| 294 | 294 | [SQLite User Forum](https://sqlite.org/forum), and the |
| @@ -363,11 +363,11 @@ | ||
| 363 | 363 | <p> |
| 364 | 364 | Long-time Git users might cringe at autosync, thinking that this |
| 365 | 365 | could cause problems if another developer commits ahead of you. |
| 366 | 366 | True enough, that would cause headaches for Git, but it does not |
| 367 | 367 | create problems for Fossil. |
| 368 | - The worse that could happen is that the branch will fork. Fossil | |
| 368 | + The worst that could happen is that the branch will fork. Fossil | |
| 369 | 369 | will usually detect an impending fork and warn you. |
| 370 | 370 | But even if you don't get the warning (due to a race) or even if you |
| 371 | 371 | override the warning and force the commit anyhow, a fork on a branch |
| 372 | 372 | in Fossil is harmless. It shows cleanly in the timeline and |
| 373 | 373 | is easily resolved. So while autosync might cause issues with Git, |
| @@ -395,11 +395,11 @@ | ||
| 395 | 395 | is how all of the documentation files for Fossil itself are created. |
| 396 | 396 | |
| 397 | 397 | 1. **Fossil can easily host an entire project website, using only the |
| 398 | 398 | repository as the backing store.**<p> |
| 399 | 399 | The embedded documentation and wiki features allow you to write |
| 400 | - web pages. The unversioned file feature gives you space to put of | |
| 400 | + web pages. The unversioned file feature gives you space to put off | |
| 401 | 401 | precompiled binaries or other transient and/or derived resources |
| 402 | 402 | without contaminating the source tree. The Forum and Ticket features |
| 403 | 403 | provide for community discussion and bug tracking. Fossil provides |
| 404 | 404 | everything you need to host a complete software project website. |
| 405 | 405 | Indeed, the |
| @@ -435,11 +435,11 @@ | ||
| 435 | 435 | Core Git does not have any kind of markup language. Check-in comments |
| 436 | 436 | in Git are always displayed verbatim. But wrappers such as GitHub, |
| 437 | 437 | GitLab, Gitea, Forgejo, and similar generally support some variant |
| 438 | 438 | of Markdown. However, none of these system support links (apart from |
| 439 | 439 | full URLs) to other wiki systems. Fossil does support interwiki links |
| 440 | - using the syntax "<tt>remote:path</tt>". So, for example, a checkin | |
| 440 | + using the syntax "<tt>remote:path</tt>". So, for example, a check-in | |
| 441 | 441 | in the SQLite source repository (<https://sqlite.org/src>) that wants |
| 442 | 442 | to reference a bug report (perhaps because it fixes the bug) can |
| 443 | 443 | include a link of the form "<tt>bugs:/info/</tt><i>HASH</i>" to |
| 444 | 444 | reference that bug. The source repository knows that "bugs:" refers |
| 445 | 445 | to the [SQLite Bug Forum](https://sqlite.org/bugs) and completes the |
| @@ -479,131 +479,131 @@ | ||
| 479 | 479 | 1. **Fossil chat is able to send attachments.**<p> |
| 480 | 480 | When the SQLite developers are working collaboratively on a problem |
| 481 | 481 | (while working, literally, on three different continents) we easily |
| 482 | 482 | send patches or diffs to one another over Chat. |
| 483 | 483 | |
| 484 | - 1. **Fossil supports hyperlinks in checkin comments.**<p> | |
| 484 | + 1. **Fossil supports hyperlinks in check-in comments.**<p> | |
| 485 | 485 | Check-in comments need not be just verbatim text (though they can |
| 486 | - be depending on repository settings). By default, checkin | |
| 486 | + be, depending on repository settings). By default, check-in | |
| 487 | 487 | comments can contain hyperlinks, including hyperlinks to |
| 488 | - wiki pages, prior checkins, forum posts, and interwiki hyperlinks. | |
| 488 | + wiki pages, prior check-ins, forum posts, and interwiki hyperlinks. | |
| 489 | 489 | |
| 490 | 490 | 1. **Fossil supports hyperlink back references**<p> |
| 491 | - If the checkin comment for a newer commits contains a hyperlink | |
| 492 | - back to an older commit, then when the web interface show the | |
| 493 | - details of the older commit, it also provides are forward | |
| 491 | + If the check-in comment for a newer commits contains a hyperlink | |
| 492 | + back to an older commit, then when the web interface shows the | |
| 493 | + details of the older commit, it also provides a forward | |
| 494 | 494 | reference to the newer commit. |
| 495 | 495 | |
| 496 | 496 | 1. **Fossil supports a graphical timeline display of a bisect.**<p> |
| 497 | 497 | [For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). |
| 498 | 498 | This is not strictly necessary to make effective use of bisect, but |
| 499 | 499 | the graphical display does seem to help with situational awareness. |
| 500 | 500 | |
| 501 | 501 | 1. **Fossil can show you the first release in which a particular |
| 502 | - checkin appears, in a single mouse click.**<p> | |
| 502 | + check-in appears, with a single mouse click.**<p> | |
| 503 | 503 | You have to configure the repository by giving it the name of the |
| 504 | 504 | tag that you use to mark releases, using the |
| 505 | 505 | [path-to-tag setting](/help/path-to-tag). Suppose you use the tag |
| 506 | 506 | name "release". Once you do that, then |
| 507 | - when your are looking at the "info" page for a checkin, a link | |
| 507 | + when your are looking at the "info" page for a check-in, a link | |
| 508 | 508 | named "path-to-release" appears in the overview section, and if |
| 509 | 509 | you click on that link, it brings up a new graph showing the |
| 510 | - shortest path from that checkin to the next descendant checkin | |
| 510 | + shortest path from that check-in to the next descendant check-in | |
| 511 | 511 | tagged with "release". |
| 512 | 512 | <p> |
| 513 | 513 | Example: On the info page at |
| 514 | 514 | <https://sqlite.org/src/info/b1d7123bc619e3cb>, in the Overview |
| 515 | 515 | section at the top, to the right of the "Timelines:" label, you |
| 516 | 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 | |
| 517 | + to a page showing an abbreviated path from the original check-in | |
| 518 | + to the first "release" check-in that contains the change. To | |
| 519 | 519 | See the full path, uncheck the "Brief" checkbox near the top of the page. |
| 520 | 520 | <p> |
| 521 | 521 | This feature is useful for when you bisect to find a bug, or a bug |
| 522 | 522 | fix, and you want to know the first release in which that bug or bug fix |
| 523 | 523 | appeared. |
| 524 | 524 | |
| 525 | - 1. **Fossil allows you to revise a checkin comment without | |
| 525 | + 1. **Fossil allows you to revise a check-in comment without | |
| 526 | 526 | rewriting history.**<p> |
| 527 | - If you find a typo or other error in an historical checkin comment, | |
| 527 | + If you find a typo or other error in an historical check-in comment, | |
| 528 | 528 | you can fix the problem in Fossil without having to rewrite all |
| 529 | 529 | subsequent history. The Fossil file format allows you to set |
| 530 | - a special tag on the checkin that provides revised comment text. | |
| 530 | + a special tag on the check-in that provides revised comment text. | |
| 531 | 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 | |
| 532 | + and the web interface to show the revised check-in comment rather | |
| 533 | + that the original. Note that the original check-in comment is | |
| 534 | 534 | preserved, so there is still an immutable audit trail. But for |
| 535 | 535 | common use cases, only the newer revised comment is shown. |
| 536 | 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 | |
| 537 | + If you are using the web interface and if you have check-in privilege | |
| 538 | + on the repository, then on the /info page for the check-in, under | |
| 539 | 539 | the "Overview" section, to the right of "Other Links:", there is |
| 540 | 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. | |
| 541 | + the check-in comment from the web interface. This is the easiest | |
| 542 | + way to edit a check-in comment. | |
| 543 | 543 | <p> |
| 544 | - See [Fossil checkin b63d654041](/info/b63d65404) for an | |
| 544 | + See [Fossil check-in b63d654041](/info/b63d65404) for an | |
| 545 | 545 | example. The original comment is shown in the "Overview" |
| 546 | - section of the checkin details, but the revised comment is show | |
| 546 | + section of the check-in details, but the revised comment is shown | |
| 547 | 547 | in the timeline. |
| 548 | 548 | |
| 549 | - 1. **Fossil allows you to revise a checkin timestamp without | |
| 549 | + 1. **Fossil allows you to revise a check-in timestamp without | |
| 550 | 550 | rewriting history.**<p> |
| 551 | - When generating a new checkin, Fossil uses the current time on the | |
| 551 | + When generating a new check-in, Fossil uses the current time on the | |
| 552 | 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 | |
| 553 | + that system is incorrect, that can lead to a check-in with an | |
| 554 | + inaccurate timestamp. It can be the case that prior check-ins | |
| 555 | + have later timestamps or that subsequent check-ins can have | |
| 556 | 556 | earlier timestamps, resulting in goofy-looking "time-warps" in the |
| 557 | 557 | timeline. This can be fixed by add a timestamp correction tag |
| 558 | - to the faulty checkin to fix the timestamp. | |
| 558 | + to the faulty check-in to fix the timestamp. | |
| 559 | 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 | |
| 560 | + If you are using the web interface and if you have check-in privilege | |
| 561 | + on the repository, then on the /info page for the check-in, under | |
| 562 | 562 | the "Overview" section, to the right of "Other Links:", there is |
| 563 | 563 | an "edit" link that will take you to a page that lets you change |
| 564 | - the timestamp for a checkin from the web interface. This is the | |
| 564 | + the timestamp for a check-in from the web interface. This is the | |
| 565 | 565 | easiest way to make the change. |
| 566 | 566 | |
| 567 | - 1. **Fossil allows you to move a checkin to a new branch without | |
| 567 | + 1. **Fossil allows you to move a check-in to a new branch without | |
| 568 | 568 | rewriting history.**<p> |
| 569 | 569 | If you mistakenly commit to the wrong branch, you can move that |
| 570 | - checkin to a new branch by attaching a special tag. | |
| 571 | - Note, however, that this will also move all subsequent checkins | |
| 570 | + check-in to a new branch by attaching a special tag. | |
| 571 | + Note, however, that this will also move all subsequent check-ins | |
| 572 | 572 | to that same new branch. |
| 573 | 573 | <p> |
| 574 | 574 | In the SQLite and Fossil projects, when developers mistakenly commit |
| 575 | 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 | |
| 576 | + mistaken check-in to a branch named "mistake". Sometimes we also | |
| 577 | + set the "hidden" tag on that check-in as well, so that it does not | |
| 578 | 578 | show up on ordinary timelines (though it is still part of the |
| 579 | 579 | immutable audit history and is visible with special options). |
| 580 | - Then we just cherrypick the checkin onto the correct branch. | |
| 580 | + Then we just cherrypick the check-in onto the correct branch. | |
| 581 | 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 | |
| 582 | + If you are using the web interface and if you have check-in privilege | |
| 583 | + on the repository, then on the /info page for the check-in, under | |
| 584 | 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 | |
| 585 | + an "edit" link that will take you to a page that lets move the check-in | |
| 586 | 586 | to a new branch from the web interface. You can also do this |
| 587 | - from the Fossil commit-line, but the web interface is easier and less | |
| 587 | + from the Fossil command-line, but the web interface is easier and less | |
| 588 | 588 | error prone. |
| 589 | 589 | |
| 590 | 590 | 1. **Fossil supports unversioned files**.<p> |
| 591 | 591 | [Unversioned Files](/doc/trunk/www/unvers.wiki) are files held |
| 592 | 592 | in the repository but which are not versioned and which are not |
| 593 | 593 | synced by default. Unversioned files are used by Fossil itself |
| 594 | 594 | to store [Precompiled Binaries of Fossil](/uv/download.html). |
| 595 | 595 | <p> |
| 596 | - Unversioned contain is not synced *by default*. But unversioned | |
| 596 | + Unversioned content is not synced *by default*. But unversioned | |
| 597 | 597 | files will sync if you add the -u option to the |
| 598 | 598 | [fossil sync command](/help/sync). |
| 599 | - There are also the [fossil uv sync](/help/uv) command. | |
| 599 | + There is also the [fossil uv sync](/help/uv) command. | |
| 600 | 600 | |
| 601 | - 1. **Fossil automatically selects checkin background colors according to | |
| 602 | - the branch that each checkin occurs on.**<p> | |
| 601 | + 1. **Fossil automatically selects check-in background colors according to | |
| 602 | + the branch that each check-in occurs on.**<p> | |
| 603 | 603 | This helps to make the timeline easier to read at a glance, by |
| 604 | - clearly showing which checkins are on which branches. Developers | |
| 604 | + clearly showing which check-ins are on which branches. Developers | |
| 605 | 605 | can assign specific colors to branches either when the branch is |
| 606 | 606 | first created, or after the branch has been running for a while. |
| 607 | 607 | But experience teaches us that it is better to just let the web |
| 608 | 608 | interface pick the branch colors automatically. The color is |
| 609 | 609 | derived from a hash of the branch name. |
| @@ -613,15 +613,15 @@ | ||
| 613 | 613 | On the [/hash-color-test page](/hash-color-test), one can enter |
| 614 | 614 | candidate branch names and see in advance what colors Fossil will |
| 615 | 615 | pick for that branch name. This seems like cheating, but I will |
| 616 | 616 | admit that I do this myself, sometimes... |
| 617 | 617 | |
| 618 | - 1. **The Fossil web interface timeline can be asked to pick checkin | |
| 618 | + 1. **The Fossil web interface timeline can be asked to pick check-in | |
| 619 | 619 | colors using the name of the committer, rather than the branch |
| 620 | 620 | name.**<p> |
| 621 | 621 | Simply add the "ubg" query parameter (mnemonic: User BackGround) and |
| 622 | - the checkin colors will be determined by the committer login name | |
| 622 | + the check-in colors will be determined by the committer login name | |
| 623 | 623 | rather than the branch name or any preselected color name. This |
| 624 | 624 | results in a timeline that gives the reader a clearer view of who is |
| 625 | 625 | making changes. |
| 626 | 626 | [Example](/timeline?n=200&y=ci&ubg). |
| 627 | 627 | |
| @@ -630,11 +630,11 @@ | ||
| 630 | 630 | [Fossil file format](/doc/trunk/www/fileformat.wiki). |
| 631 | 631 | Cherrypicks appear on the timeline as thin dashed lines. |
| 632 | 632 | |
| 633 | 633 | 1. **Fossil draws arrows pointing forwards in time.**<p> |
| 634 | 634 | Forward-pointing arrows are more intuitive than arrows |
| 635 | - that point backwards in times, like Git uses. Yes, I am aware | |
| 635 | + that point backwards in time, like Git uses. Yes, I am aware | |
| 636 | 636 | that the underlying implementation of Git has pointers going from child |
| 637 | 637 | to parent, and thus must necessarily go backwards in time. Fossil |
| 638 | 638 | has the same pointers. But just because the *implementation* |
| 639 | 639 | points backwards in time does not mean that the *user interface* |
| 640 | 640 | needs to do the same. Fossil flips those pointers around so that |
| @@ -651,11 +651,11 @@ | ||
| 651 | 651 | more will be added as needs arise. Having ready access to these |
| 652 | 652 | commands built into the standalone Fossil binary makes working on |
| 653 | 653 | non-Linux platforms more comfortable for unix geeks, and saves having |
| 654 | 654 | to hunt around and install system-specific alternatives. |
| 655 | 655 | |
| 656 | - 1. **Fossil can copy all uncommited changes from a checkout on a | |
| 656 | + 1. **Fossil can copy all uncommitted changes from a checkout on a | |
| 657 | 657 | remote system over to a checkout on the local machine.**<p> |
| 658 | 658 | The command is [fossil patch pull](/help/patch). It contacts the |
| 659 | 659 | remote system via SSH, updates its local checkout to the same baseline |
| 660 | 660 | as is found on the remote, then pulls over a minimal set of diffs and |
| 661 | 661 | applies them.<p> |
| @@ -677,11 +677,11 @@ | ||
| 677 | 677 | 1. **Fossil lets you set up aliases for remote checkouts with which |
| 678 | 678 | you commonly push or pull.**<p> |
| 679 | 679 | My desktop is named "r21" and I normally do SQLite development |
| 680 | 680 | work in the directory ~/sqlite/sqlite. If I have uncommitted |
| 681 | 681 | changes that I want to test on Windows, I SSH over to the Win11 |
| 682 | - machine then run a commands like:<pre> | |
| 682 | + machine then run commands like:<pre> | |
| 683 | 683 | fossil patch pull r21:sqlite/sqlite -f |
| 684 | 684 | make clean test</pre> |
| 685 | 685 | But typing in "r21:sqlite/sqlite" can be tedious and error-prone, |
| 686 | 686 | maybe not so much in this particular examples but definitely the |
| 687 | 687 | case for longer hostnames and subdirectory paths. Fortunately, |
| @@ -702,11 +702,11 @@ | ||
| 702 | 702 | fossil ui remote:path/to/checkout</pre> |
| 703 | 703 | Substitute the name of your remote and the path to the checkout |
| 704 | 704 | on the remote, of course.<p> |
| 705 | 705 | The way this works is that Fossil opens an SSH connection to the |
| 706 | 706 | remote machine that runs [fossil server](/help/server) on the |
| 707 | - remote and that tunnels the HTTP content back through SSH connection | |
| 707 | + remote and that tunnels the HTTP content back through the SSH connection | |
| 708 | 708 | to your desktop. At the same time, Fossil brings up your default |
| 709 | 709 | web browser and points it to the local end of your SSH tunnel. |
| 710 | 710 | That's a lot of network plumbing, but Fossil handles it all |
| 711 | 711 | automatically, so that you the developer don't need to think about it. |
| 712 | 712 | |
| @@ -729,11 +729,11 @@ | ||
| 729 | 729 | all those repositories. Links on that initial page let you explore |
| 730 | 730 | deeper into the details of each repository. |
| 731 | 731 | |
| 732 | 732 | 1. **The Fossil web interface supports multiple timeline formats, to |
| 733 | 733 | accommodate personal tastes.**<p> |
| 734 | - The different formats are called "Views". The current repertiore | |
| 734 | + The different formats are called "Views". The current repertoire | |
| 735 | 735 | includes "Modern", "Columnar", "Compact", "Simple", "Verbose", and |
| 736 | 736 | "Classic". Users can select whichever format they want and their |
| 737 | 737 | preference is remembered in a cookie. |
| 738 | 738 | |
| 739 | 739 | 1. **A Fossil web server admin can set the default timeline format.**<p> |
| @@ -746,11 +746,11 @@ | ||
| 746 | 746 | the robot cookie indicating that you have previously passed a captcha |
| 747 | 747 | if you are not logged in, and the display preferences cookie. |
| 748 | 748 | If you visit the |
| 749 | 749 | [/cookies page](/cookies), Fossil will |
| 750 | 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, | |
| 751 | + show you exactly what they mean and what information they are holding, | |
| 752 | 752 | and Fossil will give you an opportunity to delete each cookie |
| 753 | 753 | individually. |
| 754 | 754 | |
| 755 | 755 | 1. **The Fossil web interface comes with a variety of "skins" built in.**<p> |
| 756 | 756 | A skin determines the coloration and layout of Fossil web pages. |
| @@ -760,11 +760,11 @@ | ||
| 760 | 760 | 1. **Individual users get to choose their favorite Fossil skin.**<p> |
| 761 | 761 | The repository administrator sets the default skin, but if |
| 762 | 762 | individual users do not like that choice, they can select a different |
| 763 | 763 | skin and their choice is recorded in the display preferences cookie. |
| 764 | 764 | |
| 765 | - 1. **Repository administators can create new custom skins.**<p> | |
| 765 | + 1. **Repository administrators can create new custom skins.**<p> | |
| 766 | 766 | The current library of skins are mostly derived from custom skins that |
| 767 | 767 | users of Fossil have created over the years and generously donated |
| 768 | 768 | to the project. If none of the default skins work for you, you can |
| 769 | 769 | create your own, perhaps using one of the existing skins as a template. |
| 770 | 770 | |
| @@ -773,11 +773,11 @@ | ||
| 773 | 773 | page that lets you quickly navigate to the information you want. |
| 774 | 774 | (Note: The presence and operation of the hamburger menu is a |
| 775 | 775 | skin-specific feature and might not be available on every skin, but |
| 776 | 776 | it is used on the more popular skins.) Curiously, none of GitHub, |
| 777 | 777 | GitLab, Gitea, nor Forgejo have a hamburger menu, which in my |
| 778 | - experience, makes those sites harder to navigate. | |
| 778 | + experience makes those sites harder to navigate. | |
| 779 | 779 | |
| 780 | 780 | 1. **The Fossil web interface /sitemap page is responsive to |
| 781 | 781 | individual user permissions and capabilities.**<p> |
| 782 | 782 | Each user on the Fossil web interface, including the special |
| 783 | 783 | user "nobody" used if no login is attempted, has |
| @@ -813,15 +813,15 @@ | ||
| 813 | 813 | to real humans. This is an on-going battle. But Fossil is, at least, |
| 814 | 814 | in the fight. Everything is easily configurable, via the web interface, |
| 815 | 815 | by repository administrators. |
| 816 | 816 | |
| 817 | 817 | 1. **The Fossil web interface includes a "security audit" page accessible |
| 818 | - to repositoriy administrators.**<p> | |
| 818 | + to repository administrators.**<p> | |
| 819 | 819 | The security-audit pages give a succinct summary of how a repository |
| 820 | 820 | web interface is configured, with an eye toward operational security. |
| 821 | 821 | As with any full-featured web application, the Fossil web interface |
| 822 | - as a large number of settings. A common worry amoung system | |
| 822 | + has a large number of settings. A common worry among system | |
| 823 | 823 | administrators is overlooking or omitting or misconfiguring some |
| 824 | 824 | security-sensitive setting. The security-audit page is designed to |
| 825 | 825 | reduce that worry. |
| 826 | 826 | <p> |
| 827 | 827 | The security-audit page shows at a glance how a repository web interface |
| @@ -834,11 +834,11 @@ | ||
| 834 | 834 | |
| 835 | 835 | 1. **The Fossil web interface menu bar can be customized.**<p> |
| 836 | 836 | Repository administrators can customize the menu bar on the web |
| 837 | 837 | interface. Individual items can be added or omitted from the |
| 838 | 838 | menu bar based on user capabilities and/or whether or not the |
| 839 | - client is a phone or other narrow-screen mobile devide, a standard | |
| 839 | + client is a phone or other narrow-screen mobile device, a standard | |
| 840 | 840 | desktop browser, or a wide-screen desktop browser. |
| 841 | 841 | |
| 842 | 842 | 1. **The Fossil web interface sitemap can be customized.**<p> |
| 843 | 843 | Repository administrators can add new entries to the |
| 844 | 844 | [/sitemap](/sitemap) that are shown or omitted |
| @@ -868,11 +868,11 @@ | ||
| 868 | 868 | The "<tt>fossil sha1sum FILE ...</tt>" and |
| 869 | 869 | "<tt>fossil sha3sum FILE ...</tt>" commands will |
| 870 | 870 | compute SHA1 and SHA3-256 hashes on files. These commands are not |
| 871 | 871 | necessary to use Fossil, but they are still useful, and they are |
| 872 | 872 | not commonly installed on non-Linux platforms. Fossil ensures that |
| 873 | - those hash functions are available whereever Fossil is available. | |
| 873 | + those hash functions are available wherever Fossil is available. | |
| 874 | 874 | |
| 875 | 875 | 1. **Fossil exposes its 3-way-diff algorithm for external use.**<p> |
| 876 | 876 | The "<tt>fossil 3-way-merge ...</tt>" command works |
| 877 | 877 | like the classic unix "diff3" command in that it does a merge |
| 878 | 878 | of two variants of a file given a common ancestor. This is the |
| @@ -936,20 +936,20 @@ | ||
| 936 | 936 | This is something of a vanity page. It is difficult to describe a |
| 937 | 937 | real business need for this information. But the page does jog old |
| 938 | 938 | memories and helps developers keep perspective on how a project has |
| 939 | 939 | changed through the years. |
| 940 | 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. | |
| 941 | + The existence of this page illustrates how the | |
| 942 | + robust and modular design of the Fossil implementation | |
| 943 | + facilitates custom modifications that involve very little new code. | |
| 944 | 944 | |
| 945 | 945 | 1. **Fossil allows you to update your current checkout even if it |
| 946 | 946 | contains uncommitted changes.**<p> |
| 947 | 947 | This is a very common idiom in Fossil: You are working on changes |
| 948 | 948 | and somebody commits ahead of you. You run |
| 949 | 949 | "<tt>fossil up</tt>" ("up" is short for "update") and the new |
| 950 | - external changes are merge into your own uncommitted changes. You | |
| 950 | + external changes are merged into your own uncommitted changes. You | |
| 951 | 951 | continue working. |
| 952 | 952 | <p> |
| 953 | 953 | Doing this in Git appears to require multiple commands (or maybe |
| 954 | 954 | just one command with multiple verbose options) to interact with |
| 955 | 955 | the stash and to rebase your changes. |
| @@ -1021,31 +1021,31 @@ | ||
| 1021 | 1021 | the users default web browser. Git does not have any such |
| 1022 | 1022 | capability, even with the aid of external programs, as far as |
| 1023 | 1023 | I am aware. |
| 1024 | 1024 | |
| 1025 | 1025 | 1. **The Fossil web interface provides a captcha-gated method to download |
| 1026 | - tarballs and ZIP archives for any checkin.**<p> | |
| 1026 | + tarballs and ZIP archives for any check-in.**<p> | |
| 1027 | 1027 | See, for example, <https://sqlite.org/src/rchvdwnld/20260704>. |
| 1028 | - That link provides access to the last checkin for the day 2026-07-04. | |
| 1028 | + That link provides access to the last check-in for the day 2026-07-04. | |
| 1029 | 1029 | The last element of the patch can be any hash prefix, timestamp prefix, |
| 1030 | - or tag that references a checkin.<p> | |
| 1031 | - Tarballs and ZIP archive are expensive to compute, not because Fossil | |
| 1032 | - has any difficulty assembly the content, | |
| 1030 | + or tag that references a check-in.<p> | |
| 1031 | + Tarballs and ZIP archives are expensive to compute, not because Fossil | |
| 1032 | + has any difficulty to assembly the content, | |
| 1033 | 1033 | but rather because the result must be run through zlib compression. |
| 1034 | 1034 | When computing a new archive, almost all of the CPU time is spent |
| 1035 | 1035 | inside of the zlib compression library. |
| 1036 | 1036 | For an SQLite-size tarball, the zlib compression alone can take as |
| 1037 | 1037 | much as 10 seconds of CPU time. If the tarball/ZIP-archive download |
| 1038 | 1038 | link is not protected by a captcha, multiple spiders will attempt to |
| 1039 | 1039 | download every possible tarball and ZIP archive, multiple times per |
| 1040 | 1040 | day, bringing your server to its knees. |
| 1041 | 1041 | |
| 1042 | - 1. **Repository adminstrators can create a cache of recently downloaded | |
| 1042 | + 1. **Repository administrators can create a cache of recently downloaded | |
| 1043 | 1043 | tarballs and ZIP archives**<p> |
| 1044 | 1044 | That way, if there are common downloads (like the most recent release) |
| 1045 | 1045 | the archive does not get recomputed from scratch with each download. |
| 1046 | - A download of cached archive file fast. | |
| 1046 | + A download of a cached archive file is fast. | |
| 1047 | 1047 | The size of the cache is configurable by the repository administrator. |
| 1048 | 1048 | |
| 1049 | 1049 | 1. **The Fossil web interface has a "Repository Status" page that shows |
| 1050 | 1050 | interesting and useful facts about the repository being served.**<p> |
| 1051 | 1051 | See the [stat page for Fossil](/stat) for example. |
| @@ -1054,25 +1054,25 @@ | ||
| 1054 | 1054 | a project, and the number of changes they have committed.**<p> |
| 1055 | 1055 | See <https://fossil-scm.org/home/reports> for that report about |
| 1056 | 1056 | Fossil itself. |
| 1057 | 1057 | Many other reports can be generated from the same page by selecting |
| 1058 | 1058 | different options from the pull-down menus at the top. |
| 1059 | - <p>The page is capcha-gated since it is a magnet for for spiders. | |
| 1059 | + <p>The page is captcha-gated since it is a magnet for spiders. | |
| 1060 | 1060 | |
| 1061 | 1061 | 1. **The Fossil source code is easy to enhance with new web pages and |
| 1062 | 1062 | commands.**<p> |
| 1063 | - The design of the Fossil implementation makes it eash to extend with | |
| 1063 | + The design of the Fossil implementation makes it easy to extend with | |
| 1064 | 1064 | new capabilities as needs arise. |
| 1065 | 1065 | <ul type="disk"> |
| 1066 | - <li> The code is C-89 | |
| 1066 | + <li> The code is C89. | |
| 1067 | 1067 | <li> Each command and each web page runs as a separate process which |
| 1068 | 1068 | exits when the action completes, so minor memory leaks are not |
| 1069 | 1069 | a concern. |
| 1070 | 1070 | <li> Preprocessors that run over the Fossil source code before the |
| 1071 | 1071 | code reaches the C compiler help |
| 1072 | 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 | |
| 1073 | + <li> New commands and new web pages can be added simply by adding a new | |
| 1074 | 1074 | procedure to do the necessary computation. The name, properties, |
| 1075 | 1075 | and documentation for the command or webpage are extracted from |
| 1076 | 1076 | specially formatted comments just prior to the procedure. |
| 1077 | 1077 | </ul><p> |
| 1078 | 1078 | The ease with which Fossil can be enhanced is part of the reason why |
| @@ -1080,6 +1080,6 @@ | ||
| 1080 | 1080 | and powerful over its 19-year history. |
| 1081 | 1081 | |
| 1082 | 1082 | ## Conclusion |
| 1083 | 1083 | |
| 1084 | 1084 | There are more reasons to prefer Fossil over Git, but |
| 1085 | -I think 101 is sufficient to prove my point. | |
| 1085 | +I think 101 are sufficient to prove my point. | |
| 1086 | 1086 |
| --- www/hundredandone.md | |
| +++ www/hundredandone.md | |
| @@ -2,11 +2,11 @@ | |
| 2 | |
| 3 | 1. **Fossil comes as a single self-contained executable file**.<p> |
| 4 | Install Fossil by copying "fossil" (or "fossil.exe") to someplace |
| 5 | on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting |
| 6 | that one file. Uninstall by deleting that one file.<p> |
| 7 | A Git installation requires hundreds of files. You want to use |
| 8 | package manager to install, upgrade, or uninstall Git. If you |
| 9 | tinker with individual files of a Git installation, you run a high |
| 10 | risk of messing things up. |
| 11 | |
| 12 | 1. **Fossil comes with a built-in full-featured web interface**.<p> |
| @@ -38,19 +38,19 @@ | |
| 38 | timeline is available via a web interface, as far as I know.<p> |
| 39 | Using the web interface, one can easily check on the status |
| 40 | of a project when away from the office and without access to a clone |
| 41 | of the repository. |
| 42 | |
| 43 | 1. **The Fossil web interface view of a single checkin shows a |
| 44 | context graph of all other directly connected checkins.**<p> |
| 45 | See the page for [checkin 59985724d71229bf](/info/59985724d71229bf) |
| 46 | for example. The context graph shows four other checkins: |
| 47 | two direct descendants, one merge descendant, and one ancestor. |
| 48 | This context graph is useful in understanding how a particular |
| 49 | checkin fits into the history of the project. The context graph |
| 50 | can also be used to step forwards or backwards in time, by |
| 51 | clicking on the "check-in:" hash links for nearby checkins. |
| 52 | |
| 53 | 1. **The graphical timeline dynamically adjusts its layout as you resize |
| 54 | your browser window.**<p> |
| 55 | The server sends down an HTML page that contains (among other things) |
| 56 | a JSON object that gives the basic structure of the |
| @@ -60,11 +60,11 @@ | |
| 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 | |
| @@ -77,40 +77,40 @@ | |
| 77 | of recent check-ins without any indication of the branching |
| 78 | structure, whereas Fossil gives you an easy-to-read color-coded |
| 79 | graph. |
| 80 | |
| 81 | 1. **The Fossil web interface makes it easy to see a diff between |
| 82 | any two checkins with just a couple of clicks.**<p> |
| 83 | On the timeline display, click on one node of the graph to |
| 84 | select it (a red dot will appear in the center of the node) and |
| 85 | then click on any other graph node, and Fossil will compute and |
| 86 | display a diff between those two check-ins. (Usage hint: |
| 87 | click the selected node a second time to deselect it.) |
| 88 | |
| 89 | 1. **The Fossil web-based diff page shows the context of the two |
| 90 | checkins being diffed.**<p> |
| 91 | At the top of the web-based diff is a graph that shows |
| 92 | specifically the two checkins being diffed and the context |
| 93 | around them. |
| 94 | [Example](/vdiff?from=052390edaf04a5f5&to=9b686daeeda7b4ca). |
| 95 | This helps to reduce any confusion about what you are looking at. |
| 96 | |
| 97 | 1. **In Fossil, a repository is distinct from a working checkout.**<p> |
| 98 | A Fossil repository can be colocated with the working checkout, as |
| 99 | they are required to be in Git. But most people keep the repository |
| 100 | separate. One common pattern is to put all Fossil repositories in |
| 101 | a single directory named $HOME/Fossils or $HOME/Museum and then open |
| 102 | working checkouts against each repository whereever they are needed. |
| 103 | |
| 104 | 1. **A single Fossil repository can support multiple working checkouts.** |
| 105 | <p> |
| 106 | Git has worktrees, but all worktrees checkouts must be on separate |
| 107 | branches. Fossil allows multiple working checkouts on the same branch |
| 108 | or even on the same checkin. One common pattern is to have one |
| 109 | checkout that is being edited, and another than is a pristine, unedited |
| 110 | version of the same checkin. This allows both to be compiled |
| 111 | simultanteously for performance comparison, or to step through both |
| 112 | binaries in two separate "gdb" sessions to hunt down a bug. |
| 113 | |
| 114 | 1. **A Fossil repository is a single disk file, not a directory |
| 115 | hierarchy.**<p> |
| 116 | You can "mv" a Fossil repository to a new place. You can "scp" |
| @@ -134,20 +134,20 @@ | |
| 134 | checkouts are located.**<p> |
| 135 | This and other information (such as all your global settings) |
| 136 | is stored in a per-user database file |
| 137 | at $HOME/.config/fossil.db on unix or in %LOCALAPPDATA%/_fossil on |
| 138 | Windows. Fossil creates and manages that file automatically. |
| 139 | The user never has know the file even exists. If you |
| 140 | move or rename repositories or checkouts, the database will get |
| 141 | temporarily out of sync with reality, but Fossil will automatically |
| 142 | fix the database the next time you do anything with the file or |
| 143 | checkout that was moved or renamed.<p> |
| 144 | You can get a list of repositories using the |
| 145 | "<tt>fossil all ls</tt>" command, or a list of open |
| 146 | checkouts using "<tt>fossil all ls --ckout</tt>". |
| 147 | |
| 148 | 1. **Fossil lets you to bring up a web-based UI that shows all of |
| 149 | your repositories at once.**<p> |
| 150 | Run the command "<tt>fossil ui /</tt>" and your |
| 151 | default web browser will pop up a new tab that lists all of your |
| 152 | repositories together with the |
| 153 | associated project name and how recently that repository was modified. |
| @@ -174,45 +174,45 @@ | |
| 174 | While off-network, you might commit changes to one or |
| 175 | more of those repositories. Once you reconnect, you simply |
| 176 | run "<tt>fossil all sync</tt>" again to push out your edits |
| 177 | back to the community. |
| 178 | |
| 179 | 1. **Fossil allows multiple checkins to have the same tag.**<p> |
| 180 | For example, on the SQLite project, every release is tagged with |
| 181 | "release". |
| 182 | |
| 183 | 1. **The Fossil timeline can show all checkins with a specific tag.**<p> |
| 184 | For example, to see all SQLite releases visit |
| 185 | <https://sqlite.org/src/timeline?t=release> or to see all |
| 186 | Fossil releases go to |
| 187 | <https://fossil-scm.org/home/timeline?t=release>. |
| 188 | |
| 189 | 1. **Fossil has a built-in wiki**.<p> |
| 190 | Wiki pages are stored in the same repository file as your code, so that |
| 191 | they push, pull, sync, and clone together with your code. |
| 192 | |
| 193 | 1. **Fossil can associate a wiki page with a particular checkin.**<p> |
| 194 | Rather than including an oversized checkin comment on an |
| 195 | important checkin (such as the merge of a big new feature), Fossil |
| 196 | allows you to assign a wiki page to that checkin. That wiki page |
| 197 | is shown as part of the checkin information in the web interface. |
| 198 | See, for example, the "About" section of |
| 199 | [SQLite checkin 2019-11-21T18:28:44.463Z](https://sqlite.org/src/info/2019-11-21T18:28:44.463Z). |
| 200 | The wiki page associated with a checkin can be created and revised |
| 201 | after the checkin is committed and pushed. This feature can be used |
| 202 | to add notes or bug reports that occur long after the |
| 203 | checkin itself has been inserted into the DAG. |
| 204 | |
| 205 | 1. **Fossil can associate a wiki page with a particular branch.**<p> |
| 206 | You can create a wiki page for a branch that documents the purpose |
| 207 | of that branch. The wiki page can be displayed separately (like any |
| 208 | other wiki page) but is also displayed automatically at the top of |
| 209 | every timeline for that branch. See, for example, |
| 210 | <https://sqlite.org/src/timeline?r=autosetup>. |
| 211 | |
| 212 | 1. **Fossil keeps track of historical branch names.**<p> |
| 213 | Git does not track of branches. Git only names each leaf |
| 214 | of the DAG and infers branches based on the names of leaves. |
| 215 | Fossil actually remembers the name of branches. |
| 216 | For example, suppose a customer asks |
| 217 | "Whatever became of that setlk-snapshot-fix branch you |
| 218 | started last year?" That branch still exists and you can |
| @@ -224,11 +224,11 @@ | |
| 224 | GitHub just shows us all ancestors of the leaf node labeled |
| 225 | "setlk-snapshot-fix", including ancestors that were in other branches |
| 226 | that got merged in, and ancestors that predate the founding of the |
| 227 | setlk-snapshot-fix branch. |
| 228 | <p> |
| 229 | GitHub is unable to show you the checkins of branch setlk-snapshot-fix |
| 230 | only. There are other third-party tools that will show you that, I am |
| 231 | told, but they all require a local clone of the repository. Apparently |
| 232 | there is no way to see this information in a web browser using Git, |
| 233 | with or without third-party tools. |
| 234 | |
| @@ -257,38 +257,38 @@ | |
| 257 | [SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) |
| 258 | against SHA1 was published on 2017-02-23, the need to migrate to a |
| 259 | stronger hash algorithm was recognized. Fossil added the ability |
| 260 | to use SHA3-256 as an alternative on 2017-03-01 (six days after the |
| 261 | SHAttered attack was first published). |
| 262 | SHA3-256 is now the default for all new repositories and checkins |
| 263 | in Fossil, though older checkins that occurred |
| 264 | prior to ShAttered can still use their original SHA1 hash. Hence, |
| 265 | no repositories had to be rebuilt and no hyperlinks were broken.<p> |
| 266 | In contrast, after nine years, a Git repository can still only |
| 267 | support only one hash algorithm at a time. |
| 268 | Newer Git repositories are able to use SHA2, though the default |
| 269 | is still SHA1. |
| 270 | |
| 271 | 1. **Fossil allows checkins to be identified by timestamp**<p> |
| 272 | The canonical name for a checkin is its hash. Both Git and Fossil |
| 273 | allow a checkin to be identified by any unique prefix of its hash. |
| 274 | But only Fossil allows a checkin to also be identified by its |
| 275 | timestamp. The names "2026-02-02T16:03:24.852Z" and "fdebbedbd9a99165" |
| 276 | both refer to [the same checkin](https://sqlite.org/src/fdebbedbd9a99165), |
| 277 | but the first one has the advantage of giving some time |
| 278 | context rather than just being a seemingly random sequence of hexadecimal |
| 279 | digits. It is possible that two or more checkins can have the same |
| 280 | timestamp, in which case the timestamp would be ambiguous. And a |
| 281 | checkin timestamp can be changed after it is committed, by using |
| 282 | a special tag. So timestamp identifiers do not have the uniqueness |
| 283 | and stability guarantees as hash identifiers, but they are available |
| 284 | as an option and are often useful. |
| 285 | |
| 286 | 1. **Fossil has a built-in forum.**<p> |
| 287 | The forum content is replicated via push, pull, sync, and clone just like |
| 288 | source code. Forum posts can be enabled per user or for all user or |
| 289 | for all users and anonymous passers-by. Some user can be appointed |
| 290 | as moderators and posts from untrusted users can be held for |
| 291 | moderation. |
| 292 | <p> |
| 293 | The [Fossil Forum](https://fossil-scm.org/forum), the |
| 294 | [SQLite User Forum](https://sqlite.org/forum), and the |
| @@ -363,11 +363,11 @@ | |
| 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, |
| @@ -395,11 +395,11 @@ | |
| 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 |
| @@ -435,11 +435,11 @@ | |
| 435 | Core Git does not have any kind of markup language. Check-in comments |
| 436 | in Git are always displayed verbatim. But wrappers such as GitHub, |
| 437 | GitLab, Gitea, Forgejo, and similar generally support some variant |
| 438 | of Markdown. However, none of these system support links (apart from |
| 439 | full URLs) to other wiki systems. Fossil does support interwiki links |
| 440 | using the syntax "<tt>remote:path</tt>". So, for example, a checkin |
| 441 | in the SQLite source repository (<https://sqlite.org/src>) that wants |
| 442 | to reference a bug report (perhaps because it fixes the bug) can |
| 443 | include a link of the form "<tt>bugs:/info/</tt><i>HASH</i>" to |
| 444 | reference that bug. The source repository knows that "bugs:" refers |
| 445 | to the [SQLite Bug Forum](https://sqlite.org/bugs) and completes the |
| @@ -479,131 +479,131 @@ | |
| 479 | 1. **Fossil chat is able to send attachments.**<p> |
| 480 | When the SQLite developers are working collaboratively on a problem |
| 481 | (while working, literally, on three different continents) we easily |
| 482 | send patches or diffs to one another over Chat. |
| 483 | |
| 484 | 1. **Fossil supports hyperlinks in checkin comments.**<p> |
| 485 | Check-in comments need not be just verbatim text (though they can |
| 486 | be depending on repository settings). By default, checkin |
| 487 | comments can contain hyperlinks, including hyperlinks to |
| 488 | wiki pages, prior checkins, forum posts, and interwiki hyperlinks. |
| 489 | |
| 490 | 1. **Fossil supports hyperlink back references**<p> |
| 491 | If the checkin comment for a newer commits contains a hyperlink |
| 492 | back to an older commit, then when the web interface show the |
| 493 | details of the older commit, it also provides are forward |
| 494 | reference to the newer commit. |
| 495 | |
| 496 | 1. **Fossil supports a graphical timeline display of a bisect.**<p> |
| 497 | [For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). |
| 498 | This is not strictly necessary to make effective use of bisect, but |
| 499 | the graphical display does seem to help with situational awareness. |
| 500 | |
| 501 | 1. **Fossil can show you the first release in which a particular |
| 502 | checkin appears, in a single mouse click.**<p> |
| 503 | You have to configure the repository by giving it the name of the |
| 504 | tag that you use to mark releases, using the |
| 505 | [path-to-tag setting](/help/path-to-tag). Suppose you use the tag |
| 506 | name "release". Once you do that, then |
| 507 | when your are looking at the "info" page for a checkin, a link |
| 508 | named "path-to-release" appears in the overview section, and if |
| 509 | you click on that link, it brings up a new graph showing the |
| 510 | shortest path from that checkin to the next descendant checkin |
| 511 | tagged with "release". |
| 512 | <p> |
| 513 | Example: On the info page at |
| 514 | <https://sqlite.org/src/info/b1d7123bc619e3cb>, in the Overview |
| 515 | section at the top, to the right of the "Timelines:" label, you |
| 516 | will see the "path-to-release" link. Click that link to take you |
| 517 | to a page showing an abbreviated path from the original checkin |
| 518 | to the first "release" checkin that contains the change. To |
| 519 | See the full path, uncheck the "Brief" checkbox near the top of the page. |
| 520 | <p> |
| 521 | This feature is useful for when you bisect to find a bug, or a bug |
| 522 | fix, and you want to know the first release in which that bug or bug fix |
| 523 | appeared. |
| 524 | |
| 525 | 1. **Fossil allows you to revise a checkin comment without |
| 526 | rewriting history.**<p> |
| 527 | If you find a typo or other error in an historical checkin comment, |
| 528 | you can fix the problem in Fossil without having to rewrite all |
| 529 | subsequent history. The Fossil file format allows you to set |
| 530 | a special tag on the checkin that provides revised comment text. |
| 531 | The new tag causes both the command-line display |
| 532 | and the web interface to show the revised checkin comment rather |
| 533 | that the original. Note that the original checkin comment is |
| 534 | preserved, so there is still an immutable audit trail. But for |
| 535 | common use cases, only the newer revised comment is shown. |
| 536 | <p> |
| 537 | If you are using the web interface and if you have checkin privilege |
| 538 | on the repository, then on the /info page for the checkin, under |
| 539 | the "Overview" section, to the right of "Other Links:", there is |
| 540 | an "edit" link that will take you to a page that lets you change |
| 541 | the checkin comment from the web interface. This is the easiest |
| 542 | way to edit a checkin comment. |
| 543 | <p> |
| 544 | See [Fossil checkin b63d654041](/info/b63d65404) for an |
| 545 | example. The original comment is shown in the "Overview" |
| 546 | section of the checkin details, but the revised comment is show |
| 547 | in the timeline. |
| 548 | |
| 549 | 1. **Fossil allows you to revise a checkin timestamp without |
| 550 | rewriting history.**<p> |
| 551 | When generating a new checkin, Fossil uses the current time on the |
| 552 | system where the commit is occurring. But if the system clock on |
| 553 | that system is incorrect, that can lead to a checkin with an |
| 554 | inaccurate timestamp. It can be the case that prior checkins |
| 555 | have later timestamps or that subsequent checkins can have |
| 556 | earlier timestamps, resulting in goofy-looking "time-warps" in the |
| 557 | timeline. This can be fixed by add a timestamp correction tag |
| 558 | to the faulty checkin to fix the timestamp. |
| 559 | <p> |
| 560 | If you are using the web interface and if you have checkin privilege |
| 561 | on the repository, then on the /info page for the checkin, under |
| 562 | the "Overview" section, to the right of "Other Links:", there is |
| 563 | an "edit" link that will take you to a page that lets you change |
| 564 | the timestamp for a checkin from the web interface. This is the |
| 565 | easiest way to make the change. |
| 566 | |
| 567 | 1. **Fossil allows you to move a checkin to a new branch without |
| 568 | rewriting history.**<p> |
| 569 | If you mistakenly commit to the wrong branch, you can move that |
| 570 | checkin to a new branch by attaching a special tag. |
| 571 | Note, however, that this will also move all subsequent checkins |
| 572 | to that same new branch. |
| 573 | <p> |
| 574 | In the SQLite and Fossil projects, when developers mistakenly commit |
| 575 | on the wrong branch, the usual way we fix that is to move the |
| 576 | mistaken checkin to a branch named "mistake". Sometimes we also |
| 577 | set the "hidden" tag on that checkin as well, so that it does not |
| 578 | show up on ordinary timelines (though it is still part of the |
| 579 | immutable audit history and is visible with special options). |
| 580 | Then we just cherrypick the checkin onto the correct branch. |
| 581 | <p> |
| 582 | If you are using the web interface and if you have checkin privilege |
| 583 | on the repository, then on the /info page for the checkin, under |
| 584 | the "Overview" section, to the right of "Other Links:", there is |
| 585 | an "edit" link that will take you to a page that lets move the checkin |
| 586 | to a new branch from the web interface. You can also do this |
| 587 | from the Fossil commit-line, but the web interface is easier and less |
| 588 | error prone. |
| 589 | |
| 590 | 1. **Fossil supports unversioned files**.<p> |
| 591 | [Unversioned Files](/doc/trunk/www/unvers.wiki) are files held |
| 592 | in the repository but which are not versioned and which are not |
| 593 | synced by default. Unversioned files are used by Fossil itself |
| 594 | to store [Precompiled Binaries of Fossil](/uv/download.html). |
| 595 | <p> |
| 596 | Unversioned contain is not synced *by default*. But unversioned |
| 597 | files will sync if you add the -u option to the |
| 598 | [fossil sync command](/help/sync). |
| 599 | There are also the [fossil uv sync](/help/uv) command. |
| 600 | |
| 601 | 1. **Fossil automatically selects checkin background colors according to |
| 602 | the branch that each checkin occurs on.**<p> |
| 603 | This helps to make the timeline easier to read at a glance, by |
| 604 | clearly showing which checkins are on which branches. Developers |
| 605 | can assign specific colors to branches either when the branch is |
| 606 | first created, or after the branch has been running for a while. |
| 607 | But experience teaches us that it is better to just let the web |
| 608 | interface pick the branch colors automatically. The color is |
| 609 | derived from a hash of the branch name. |
| @@ -613,15 +613,15 @@ | |
| 613 | On the [/hash-color-test page](/hash-color-test), one can enter |
| 614 | candidate branch names and see in advance what colors Fossil will |
| 615 | pick for that branch name. This seems like cheating, but I will |
| 616 | admit that I do this myself, sometimes... |
| 617 | |
| 618 | 1. **The Fossil web interface timeline can be asked to pick checkin |
| 619 | colors using the name of the committer, rather than the branch |
| 620 | name.**<p> |
| 621 | Simply add the "ubg" query parameter (mnemonic: User BackGround) and |
| 622 | the checkin colors will be determined by the committer login name |
| 623 | rather than the branch name or any preselected color name. This |
| 624 | results in a timeline that gives the reader a clearer view of who is |
| 625 | making changes. |
| 626 | [Example](/timeline?n=200&y=ci&ubg). |
| 627 | |
| @@ -630,11 +630,11 @@ | |
| 630 | [Fossil file format](/doc/trunk/www/fileformat.wiki). |
| 631 | Cherrypicks appear on the timeline as thin dashed lines. |
| 632 | |
| 633 | 1. **Fossil draws arrows pointing forwards in time.**<p> |
| 634 | Forward-pointing arrows are more intuitive than arrows |
| 635 | that point backwards in times, like Git uses. Yes, I am aware |
| 636 | that the underlying implementation of Git has pointers going from child |
| 637 | to parent, and thus must necessarily go backwards in time. Fossil |
| 638 | has the same pointers. But just because the *implementation* |
| 639 | points backwards in time does not mean that the *user interface* |
| 640 | needs to do the same. Fossil flips those pointers around so that |
| @@ -651,11 +651,11 @@ | |
| 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> |
| @@ -677,11 +677,11 @@ | |
| 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, |
| @@ -702,11 +702,11 @@ | |
| 702 | fossil ui remote:path/to/checkout</pre> |
| 703 | Substitute the name of your remote and the path to the checkout |
| 704 | on the remote, of course.<p> |
| 705 | The way this works is that Fossil opens an SSH connection to the |
| 706 | remote machine that runs [fossil server](/help/server) on the |
| 707 | remote and that tunnels the HTTP content back through SSH connection |
| 708 | to your desktop. At the same time, Fossil brings up your default |
| 709 | web browser and points it to the local end of your SSH tunnel. |
| 710 | That's a lot of network plumbing, but Fossil handles it all |
| 711 | automatically, so that you the developer don't need to think about it. |
| 712 | |
| @@ -729,11 +729,11 @@ | |
| 729 | all those repositories. Links on that initial page let you explore |
| 730 | deeper into the details of each repository. |
| 731 | |
| 732 | 1. **The Fossil web interface supports multiple timeline formats, to |
| 733 | accommodate personal tastes.**<p> |
| 734 | The different formats are called "Views". The current repertiore |
| 735 | includes "Modern", "Columnar", "Compact", "Simple", "Verbose", and |
| 736 | "Classic". Users can select whichever format they want and their |
| 737 | preference is remembered in a cookie. |
| 738 | |
| 739 | 1. **A Fossil web server admin can set the default timeline format.**<p> |
| @@ -746,11 +746,11 @@ | |
| 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. |
| @@ -760,11 +760,11 @@ | |
| 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 | |
| @@ -773,11 +773,11 @@ | |
| 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 |
| @@ -813,15 +813,15 @@ | |
| 813 | to real humans. This is an on-going battle. But Fossil is, at least, |
| 814 | in the fight. Everything is easily configurable, via the web interface, |
| 815 | by repository administrators. |
| 816 | |
| 817 | 1. **The Fossil web interface includes a "security audit" page accessible |
| 818 | to repositoriy administrators.**<p> |
| 819 | The security-audit pages give a succinct summary of how a repository |
| 820 | web interface is configured, with an eye toward operational security. |
| 821 | As with any full-featured web application, the Fossil web interface |
| 822 | as a large number of settings. A common worry amoung system |
| 823 | administrators is overlooking or omitting or misconfiguring some |
| 824 | security-sensitive setting. The security-audit page is designed to |
| 825 | reduce that worry. |
| 826 | <p> |
| 827 | The security-audit page shows at a glance how a repository web interface |
| @@ -834,11 +834,11 @@ | |
| 834 | |
| 835 | 1. **The Fossil web interface menu bar can be customized.**<p> |
| 836 | Repository administrators can customize the menu bar on the web |
| 837 | interface. Individual items can be added or omitted from the |
| 838 | menu bar based on user capabilities and/or whether or not the |
| 839 | client is a phone or other narrow-screen mobile devide, a standard |
| 840 | desktop browser, or a wide-screen desktop browser. |
| 841 | |
| 842 | 1. **The Fossil web interface sitemap can be customized.**<p> |
| 843 | Repository administrators can add new entries to the |
| 844 | [/sitemap](/sitemap) that are shown or omitted |
| @@ -868,11 +868,11 @@ | |
| 868 | The "<tt>fossil sha1sum FILE ...</tt>" and |
| 869 | "<tt>fossil sha3sum FILE ...</tt>" commands will |
| 870 | compute SHA1 and SHA3-256 hashes on files. These commands are not |
| 871 | necessary to use Fossil, but they are still useful, and they are |
| 872 | not commonly installed on non-Linux platforms. Fossil ensures that |
| 873 | those hash functions are available whereever Fossil is available. |
| 874 | |
| 875 | 1. **Fossil exposes its 3-way-diff algorithm for external use.**<p> |
| 876 | The "<tt>fossil 3-way-merge ...</tt>" command works |
| 877 | like the classic unix "diff3" command in that it does a merge |
| 878 | of two variants of a file given a common ancestor. This is the |
| @@ -936,20 +936,20 @@ | |
| 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. |
| @@ -1021,31 +1021,31 @@ | |
| 1021 | the users default web browser. Git does not have any such |
| 1022 | capability, even with the aid of external programs, as far as |
| 1023 | I am aware. |
| 1024 | |
| 1025 | 1. **The Fossil web interface provides a captcha-gated method to download |
| 1026 | tarballs and ZIP archives for any checkin.**<p> |
| 1027 | See, for example, <https://sqlite.org/src/rchvdwnld/20260704>. |
| 1028 | That link provides access to the last checkin for the day 2026-07-04. |
| 1029 | The last element of the patch can be any hash prefix, timestamp prefix, |
| 1030 | or tag that references a checkin.<p> |
| 1031 | Tarballs and ZIP archive are expensive to compute, not because Fossil |
| 1032 | has any difficulty assembly the content, |
| 1033 | but rather because the result must be run through zlib compression. |
| 1034 | When computing a new archive, almost all of the CPU time is spent |
| 1035 | inside of the zlib compression library. |
| 1036 | For an SQLite-size tarball, the zlib compression alone can take as |
| 1037 | much as 10 seconds of CPU time. If the tarball/ZIP-archive download |
| 1038 | link is not protected by a captcha, multiple spiders will attempt to |
| 1039 | download every possible tarball and ZIP archive, multiple times per |
| 1040 | day, bringing your server to its knees. |
| 1041 | |
| 1042 | 1. **Repository adminstrators can create a cache of recently downloaded |
| 1043 | tarballs and ZIP archives**<p> |
| 1044 | That way, if there are common downloads (like the most recent release) |
| 1045 | the archive does not get recomputed from scratch with each download. |
| 1046 | A download of cached archive file fast. |
| 1047 | The size of the cache is configurable by the repository administrator. |
| 1048 | |
| 1049 | 1. **The Fossil web interface has a "Repository Status" page that shows |
| 1050 | interesting and useful facts about the repository being served.**<p> |
| 1051 | See the [stat page for Fossil](/stat) for example. |
| @@ -1054,25 +1054,25 @@ | |
| 1054 | a project, and the number of changes they have committed.**<p> |
| 1055 | See <https://fossil-scm.org/home/reports> for that report about |
| 1056 | Fossil itself. |
| 1057 | Many other reports can be generated from the same page by selecting |
| 1058 | different options from the pull-down menus at the top. |
| 1059 | <p>The page is capcha-gated since it is a magnet for for spiders. |
| 1060 | |
| 1061 | 1. **The Fossil source code is easy to enhance with new web pages and |
| 1062 | commands.**<p> |
| 1063 | The design of the Fossil implementation makes it eash to extend with |
| 1064 | new capabilities as needs arise. |
| 1065 | <ul type="disk"> |
| 1066 | <li> The code is C-89 |
| 1067 | <li> Each command and each web page runs as a separate process which |
| 1068 | exits when the action completes, so minor memory leaks are not |
| 1069 | a concern. |
| 1070 | <li> Preprocessors that run over the Fossil source code before the |
| 1071 | code reaches the C compiler help |
| 1072 | to ensure that there are no SQL injections nor XSS vulnerabilities. |
| 1073 | <li> New commands and new web pages can be added simply adding a new |
| 1074 | procedure to do the necessary computation. The name, properties, |
| 1075 | and documentation for the command or webpage are extracted from |
| 1076 | specially formatted comments just prior to the procedure. |
| 1077 | </ul><p> |
| 1078 | The ease with which Fossil can be enhanced is part of the reason why |
| @@ -1080,6 +1080,6 @@ | |
| 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 |
| --- www/hundredandone.md | |
| +++ www/hundredandone.md | |
| @@ -2,11 +2,11 @@ | |
| 2 | |
| 3 | 1. **Fossil comes as a single self-contained executable file**.<p> |
| 4 | Install Fossil by copying "fossil" (or "fossil.exe") to someplace |
| 5 | on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting |
| 6 | that one file. Uninstall by deleting that one file.<p> |
| 7 | A Git installation requires hundreds of files. You want to use a |
| 8 | package manager to install, upgrade, or uninstall Git. If you |
| 9 | tinker with individual files of a Git installation, you run a high |
| 10 | risk of messing things up. |
| 11 | |
| 12 | 1. **Fossil comes with a built-in full-featured web interface**.<p> |
| @@ -38,19 +38,19 @@ | |
| 38 | timeline is available via a web interface, as far as I know.<p> |
| 39 | Using the web interface, one can easily check on the status |
| 40 | of a project when away from the office and without access to a clone |
| 41 | of the repository. |
| 42 | |
| 43 | 1. **The Fossil web interface view of a single check-in shows a |
| 44 | context graph of all other directly connected check-ins.**<p> |
| 45 | See the page for [check-in 59985724d71229bf](/info/59985724d71229bf) |
| 46 | for example. The context graph shows four other check-ins: |
| 47 | two direct descendants, one merge descendant, and one ancestor. |
| 48 | This context graph is useful in understanding how a particular |
| 49 | check-in fits into the history of the project. The context graph |
| 50 | can also be used to step forwards or backwards in time, by |
| 51 | clicking on the "check-in:" hash links for nearby check-ins. |
| 52 | |
| 53 | 1. **The graphical timeline dynamically adjusts its layout as you resize |
| 54 | your browser window.**<p> |
| 55 | The server sends down an HTML page that contains (among other things) |
| 56 | a JSON object that gives the basic structure of the |
| @@ -60,11 +60,11 @@ | |
| 60 | is completely stand-alone. The local |
| 61 | web browser isn't required to go gather lots of separate resources. |
| 62 | |
| 63 | 1. **The graphical timeline works on a phone.**<p> |
| 64 | The graph layout automatically compresses on a small display, and |
| 65 | can seem a little cramped for a complex project. The timeline |
| 66 | does look better on a desktop. Even so, the timeline display is |
| 67 | functional on a phone and it is very convenient |
| 68 | to be able to see what is happening on a project |
| 69 | while away from the office and without access to a laptop. |
| 70 | |
| @@ -77,40 +77,40 @@ | |
| 77 | of recent check-ins without any indication of the branching |
| 78 | structure, whereas Fossil gives you an easy-to-read color-coded |
| 79 | graph. |
| 80 | |
| 81 | 1. **The Fossil web interface makes it easy to see a diff between |
| 82 | any two check-ins with just a couple of clicks.**<p> |
| 83 | On the timeline display, click on one node of the graph to |
| 84 | select it (a red dot will appear in the center of the node) and |
| 85 | then click on any other graph node, and Fossil will compute and |
| 86 | display a diff between those two check-ins. (Usage hint: |
| 87 | click the selected node a second time to deselect it.) |
| 88 | |
| 89 | 1. **The Fossil web-based diff page shows the context of the two |
| 90 | check-ins being diffed.**<p> |
| 91 | At the top of the web-based diff is a graph that shows |
| 92 | specifically the two check-ins being diffed and the context |
| 93 | around them. |
| 94 | [Example](/vdiff?from=052390edaf04a5f5&to=9b686daeeda7b4ca). |
| 95 | This helps to reduce any confusion about what you are looking at. |
| 96 | |
| 97 | 1. **In Fossil, a repository is distinct from a working checkout.**<p> |
| 98 | A Fossil repository can be colocated with the working checkout, as |
| 99 | they are required to be in Git. But most people keep the repository |
| 100 | separate. One common pattern is to put all Fossil repositories in |
| 101 | a single directory named $HOME/Fossils or $HOME/Museum and then open |
| 102 | working checkouts against each repository wherever they are needed. |
| 103 | |
| 104 | 1. **A single Fossil repository can support multiple working checkouts.** |
| 105 | <p> |
| 106 | Git has worktrees, but all worktrees checkouts must be on separate |
| 107 | branches. Fossil allows multiple working checkouts on the same branch |
| 108 | or even on the same check-in. One common pattern is to have one |
| 109 | checkout that is being edited, and another that is a pristine, unedited |
| 110 | version of the same check-in. This allows both to be compiled |
| 111 | simultaneously for performance comparison, or to step through both |
| 112 | binaries in two separate "gdb" sessions to hunt down a bug. |
| 113 | |
| 114 | 1. **A Fossil repository is a single disk file, not a directory |
| 115 | hierarchy.**<p> |
| 116 | You can "mv" a Fossil repository to a new place. You can "scp" |
| @@ -134,20 +134,20 @@ | |
| 134 | checkouts are located.**<p> |
| 135 | This and other information (such as all your global settings) |
| 136 | is stored in a per-user database file |
| 137 | at $HOME/.config/fossil.db on unix or in %LOCALAPPDATA%/_fossil on |
| 138 | Windows. Fossil creates and manages that file automatically. |
| 139 | The user never has to know the file even exists. If you |
| 140 | move or rename repositories or checkouts, the database will get |
| 141 | temporarily out of sync with reality, but Fossil will automatically |
| 142 | fix the database the next time you do anything with the file or |
| 143 | checkout that was moved or renamed.<p> |
| 144 | You can get a list of repositories using the |
| 145 | "<tt>fossil all ls</tt>" command, or a list of open |
| 146 | checkouts using "<tt>fossil all ls --ckout</tt>". |
| 147 | |
| 148 | 1. **Fossil lets you bring up a web-based UI that shows all of |
| 149 | your repositories at once.**<p> |
| 150 | Run the command "<tt>fossil ui /</tt>" and your |
| 151 | default web browser will pop up a new tab that lists all of your |
| 152 | repositories together with the |
| 153 | associated project name and how recently that repository was modified. |
| @@ -174,45 +174,45 @@ | |
| 174 | While off-network, you might commit changes to one or |
| 175 | more of those repositories. Once you reconnect, you simply |
| 176 | run "<tt>fossil all sync</tt>" again to push out your edits |
| 177 | back to the community. |
| 178 | |
| 179 | 1. **Fossil allows multiple check-ins to have the same tag.**<p> |
| 180 | For example, on the SQLite project, every release is tagged with |
| 181 | "release". |
| 182 | |
| 183 | 1. **The Fossil timeline can show all check-ins with a specific tag.**<p> |
| 184 | For example, to see all SQLite releases visit |
| 185 | <https://sqlite.org/src/timeline?t=release> or to see all |
| 186 | Fossil releases go to |
| 187 | <https://fossil-scm.org/home/timeline?t=release>. |
| 188 | |
| 189 | 1. **Fossil has a built-in wiki**.<p> |
| 190 | Wiki pages are stored in the same repository file as your code, so that |
| 191 | they push, pull, sync, and clone together with your code. |
| 192 | |
| 193 | 1. **Fossil can associate a wiki page with a particular check-in.**<p> |
| 194 | Rather than including an oversized check-in comment on an |
| 195 | important check-in (such as the merge of a big new feature), Fossil |
| 196 | allows you to assign a wiki page to that check-in. That wiki page |
| 197 | is shown as part of the check-in information in the web interface. |
| 198 | See, for example, the "About" section of |
| 199 | [SQLite check-in 2019-11-21T18:28:44.463Z](https://sqlite.org/src/info/2019-11-21T18:28:44.463Z). |
| 200 | The wiki page associated with a check-in can be created and revised |
| 201 | after the check-in is committed and pushed. This feature can be used |
| 202 | to add notes or bug reports that occur long after the |
| 203 | check-in 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 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 |
| @@ -224,11 +224,11 @@ | |
| 224 | GitHub just shows us all ancestors of the leaf node labeled |
| 225 | "setlk-snapshot-fix", including ancestors that were in other branches |
| 226 | that got merged in, and ancestors that predate the founding of the |
| 227 | setlk-snapshot-fix branch. |
| 228 | <p> |
| 229 | GitHub is unable to show you the check-ins 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 | |
| @@ -257,38 +257,38 @@ | |
| 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 check-ins |
| 263 | in Fossil, though older check-ins 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 one hash algorithm at a time. |
| 268 | Newer Git repositories are able to use SHA2, though the default |
| 269 | is still SHA1. |
| 270 | |
| 271 | 1. **Fossil allows check-ins to be identified by timestamp**<p> |
| 272 | The canonical name for a check-in is its hash. Both Git and Fossil |
| 273 | allow a check-in to be identified by any unique prefix of its hash. |
| 274 | But only Fossil allows a check-in to also be identified by its |
| 275 | timestamp. The names "2026-02-02T16:03:24.852Z" and "fdebbedbd9a99165" |
| 276 | both refer to [the same check-in](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 check-ins can have the same |
| 280 | timestamp, in which case the timestamp would be ambiguous. And a |
| 281 | check-in timestamp can be changed after it is committed, by using |
| 282 | a special tag. So timestamp identifiers do not have the uniqueness |
| 283 | and stability guarantees as hash identifiers, but they are available |
| 284 | as an option and are often useful. |
| 285 | |
| 286 | 1. **Fossil has a built-in forum.**<p> |
| 287 | The forum content is replicated via push, pull, sync, and clone just like |
| 288 | source code. Forum posts can be enabled per user or for all users or |
| 289 | for all users and anonymous passers-by. Some users can be appointed |
| 290 | as moderators and posts from untrusted users can be held for |
| 291 | moderation. |
| 292 | <p> |
| 293 | The [Fossil Forum](https://fossil-scm.org/forum), the |
| 294 | [SQLite User Forum](https://sqlite.org/forum), and the |
| @@ -363,11 +363,11 @@ | |
| 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 worst 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, |
| @@ -395,11 +395,11 @@ | |
| 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 off |
| 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 |
| @@ -435,11 +435,11 @@ | |
| 435 | Core Git does not have any kind of markup language. Check-in comments |
| 436 | in Git are always displayed verbatim. But wrappers such as GitHub, |
| 437 | GitLab, Gitea, Forgejo, and similar generally support some variant |
| 438 | of Markdown. However, none of these system support links (apart from |
| 439 | full URLs) to other wiki systems. Fossil does support interwiki links |
| 440 | using the syntax "<tt>remote:path</tt>". So, for example, a check-in |
| 441 | in the SQLite source repository (<https://sqlite.org/src>) that wants |
| 442 | to reference a bug report (perhaps because it fixes the bug) can |
| 443 | include a link of the form "<tt>bugs:/info/</tt><i>HASH</i>" to |
| 444 | reference that bug. The source repository knows that "bugs:" refers |
| 445 | to the [SQLite Bug Forum](https://sqlite.org/bugs) and completes the |
| @@ -479,131 +479,131 @@ | |
| 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 check-in comments.**<p> |
| 485 | Check-in comments need not be just verbatim text (though they can |
| 486 | be, depending on repository settings). By default, check-in |
| 487 | comments can contain hyperlinks, including hyperlinks to |
| 488 | wiki pages, prior check-ins, forum posts, and interwiki hyperlinks. |
| 489 | |
| 490 | 1. **Fossil supports hyperlink back references**<p> |
| 491 | If the check-in comment for a newer commits contains a hyperlink |
| 492 | back to an older commit, then when the web interface shows the |
| 493 | details of the older commit, it also provides a forward |
| 494 | reference to the newer commit. |
| 495 | |
| 496 | 1. **Fossil supports a graphical timeline display of a bisect.**<p> |
| 497 | [For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). |
| 498 | This is not strictly necessary to make effective use of bisect, but |
| 499 | the graphical display does seem to help with situational awareness. |
| 500 | |
| 501 | 1. **Fossil can show you the first release in which a particular |
| 502 | check-in appears, with a single mouse click.**<p> |
| 503 | You have to configure the repository by giving it the name of the |
| 504 | tag that you use to mark releases, using the |
| 505 | [path-to-tag setting](/help/path-to-tag). Suppose you use the tag |
| 506 | name "release". Once you do that, then |
| 507 | when your are looking at the "info" page for a check-in, a link |
| 508 | named "path-to-release" appears in the overview section, and if |
| 509 | you click on that link, it brings up a new graph showing the |
| 510 | shortest path from that check-in to the next descendant check-in |
| 511 | tagged with "release". |
| 512 | <p> |
| 513 | Example: On the info page at |
| 514 | <https://sqlite.org/src/info/b1d7123bc619e3cb>, in the Overview |
| 515 | section at the top, to the right of the "Timelines:" label, you |
| 516 | will see the "path-to-release" link. Click that link to take you |
| 517 | to a page showing an abbreviated path from the original check-in |
| 518 | to the first "release" check-in 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 check-in comment without |
| 526 | rewriting history.**<p> |
| 527 | If you find a typo or other error in an historical check-in 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 check-in that provides revised comment text. |
| 531 | The new tag causes both the command-line display |
| 532 | and the web interface to show the revised check-in comment rather |
| 533 | that the original. Note that the original check-in 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 check-in privilege |
| 538 | on the repository, then on the /info page for the check-in, 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 check-in comment from the web interface. This is the easiest |
| 542 | way to edit a check-in comment. |
| 543 | <p> |
| 544 | See [Fossil check-in b63d654041](/info/b63d65404) for an |
| 545 | example. The original comment is shown in the "Overview" |
| 546 | section of the check-in details, but the revised comment is shown |
| 547 | in the timeline. |
| 548 | |
| 549 | 1. **Fossil allows you to revise a check-in timestamp without |
| 550 | rewriting history.**<p> |
| 551 | When generating a new check-in, Fossil uses the current time on the |
| 552 | system where the commit is occurring. But if the system clock on |
| 553 | that system is incorrect, that can lead to a check-in with an |
| 554 | inaccurate timestamp. It can be the case that prior check-ins |
| 555 | have later timestamps or that subsequent check-ins 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 check-in to fix the timestamp. |
| 559 | <p> |
| 560 | If you are using the web interface and if you have check-in privilege |
| 561 | on the repository, then on the /info page for the check-in, under |
| 562 | the "Overview" section, to the right of "Other Links:", there is |
| 563 | an "edit" link that will take you to a page that lets you change |
| 564 | the timestamp for a check-in from the web interface. This is the |
| 565 | easiest way to make the change. |
| 566 | |
| 567 | 1. **Fossil allows you to move a check-in to a new branch without |
| 568 | rewriting history.**<p> |
| 569 | If you mistakenly commit to the wrong branch, you can move that |
| 570 | check-in to a new branch by attaching a special tag. |
| 571 | Note, however, that this will also move all subsequent check-ins |
| 572 | to that same new branch. |
| 573 | <p> |
| 574 | In the SQLite and Fossil projects, when developers mistakenly commit |
| 575 | on the wrong branch, the usual way we fix that is to move the |
| 576 | mistaken check-in to a branch named "mistake". Sometimes we also |
| 577 | set the "hidden" tag on that check-in 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 check-in onto the correct branch. |
| 581 | <p> |
| 582 | If you are using the web interface and if you have check-in privilege |
| 583 | on the repository, then on the /info page for the check-in, 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 check-in |
| 586 | to a new branch from the web interface. You can also do this |
| 587 | from the Fossil command-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 content 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 is also the [fossil uv sync](/help/uv) command. |
| 600 | |
| 601 | 1. **Fossil automatically selects check-in background colors according to |
| 602 | the branch that each check-in occurs on.**<p> |
| 603 | This helps to make the timeline easier to read at a glance, by |
| 604 | clearly showing which check-ins are on which branches. Developers |
| 605 | can assign specific colors to branches either when the branch is |
| 606 | first created, or after the branch has been running for a while. |
| 607 | But experience teaches us that it is better to just let the web |
| 608 | interface pick the branch colors automatically. The color is |
| 609 | derived from a hash of the branch name. |
| @@ -613,15 +613,15 @@ | |
| 613 | On the [/hash-color-test page](/hash-color-test), one can enter |
| 614 | candidate branch names and see in advance what colors Fossil will |
| 615 | pick for that branch name. This seems like cheating, but I will |
| 616 | admit that I do this myself, sometimes... |
| 617 | |
| 618 | 1. **The Fossil web interface timeline can be asked to pick check-in |
| 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 check-in 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 | |
| @@ -630,11 +630,11 @@ | |
| 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 time, like Git uses. Yes, I am aware |
| 636 | that the underlying implementation of Git has pointers going from child |
| 637 | to parent, and thus must necessarily go backwards in time. Fossil |
| 638 | has the same pointers. But just because the *implementation* |
| 639 | points backwards in time does not mean that the *user interface* |
| 640 | needs to do the same. Fossil flips those pointers around so that |
| @@ -651,11 +651,11 @@ | |
| 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 uncommitted 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> |
| @@ -677,11 +677,11 @@ | |
| 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 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, |
| @@ -702,11 +702,11 @@ | |
| 702 | fossil ui remote:path/to/checkout</pre> |
| 703 | Substitute the name of your remote and the path to the checkout |
| 704 | on the remote, of course.<p> |
| 705 | The way this works is that Fossil opens an SSH connection to the |
| 706 | remote machine that runs [fossil server](/help/server) on the |
| 707 | remote and that tunnels the HTTP content back through the 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 | |
| @@ -729,11 +729,11 @@ | |
| 729 | all those repositories. Links on that initial page let you explore |
| 730 | deeper into the details of each repository. |
| 731 | |
| 732 | 1. **The Fossil web interface supports multiple timeline formats, to |
| 733 | accommodate personal tastes.**<p> |
| 734 | The different formats are called "Views". The current repertoire |
| 735 | includes "Modern", "Columnar", "Compact", "Simple", "Verbose", and |
| 736 | "Classic". Users can select whichever format they want and their |
| 737 | preference is remembered in a cookie. |
| 738 | |
| 739 | 1. **A Fossil web server admin can set the default timeline format.**<p> |
| @@ -746,11 +746,11 @@ | |
| 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 | show 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. |
| @@ -760,11 +760,11 @@ | |
| 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 administrators 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 | |
| @@ -773,11 +773,11 @@ | |
| 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 |
| @@ -813,15 +813,15 @@ | |
| 813 | to real humans. This is an on-going battle. But Fossil is, at least, |
| 814 | in the fight. Everything is easily configurable, via the web interface, |
| 815 | by repository administrators. |
| 816 | |
| 817 | 1. **The Fossil web interface includes a "security audit" page accessible |
| 818 | to repository administrators.**<p> |
| 819 | The security-audit pages give a succinct summary of how a repository |
| 820 | web interface is configured, with an eye toward operational security. |
| 821 | As with any full-featured web application, the Fossil web interface |
| 822 | has a large number of settings. A common worry among 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 |
| @@ -834,11 +834,11 @@ | |
| 834 | |
| 835 | 1. **The Fossil web interface menu bar can be customized.**<p> |
| 836 | Repository administrators can customize the menu bar on the web |
| 837 | interface. Individual items can be added or omitted from the |
| 838 | menu bar based on user capabilities and/or whether or not the |
| 839 | client is a phone or other narrow-screen mobile device, a standard |
| 840 | desktop browser, or a wide-screen desktop browser. |
| 841 | |
| 842 | 1. **The Fossil web interface sitemap can be customized.**<p> |
| 843 | Repository administrators can add new entries to the |
| 844 | [/sitemap](/sitemap) that are shown or omitted |
| @@ -868,11 +868,11 @@ | |
| 868 | The "<tt>fossil sha1sum FILE ...</tt>" and |
| 869 | "<tt>fossil sha3sum FILE ...</tt>" commands will |
| 870 | compute SHA1 and SHA3-256 hashes on files. These commands are not |
| 871 | necessary to use Fossil, but they are still useful, and they are |
| 872 | not commonly installed on non-Linux platforms. Fossil ensures that |
| 873 | those hash functions are available wherever Fossil is available. |
| 874 | |
| 875 | 1. **Fossil exposes its 3-way-diff algorithm for external use.**<p> |
| 876 | The "<tt>fossil 3-way-merge ...</tt>" command works |
| 877 | like the classic unix "diff3" command in that it does a merge |
| 878 | of two variants of a file given a common ancestor. This is the |
| @@ -936,20 +936,20 @@ | |
| 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 existence of this page illustrates how the |
| 942 | robust and modular design of the Fossil implementation |
| 943 | facilitates custom modifications that 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 merged 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. |
| @@ -1021,31 +1021,31 @@ | |
| 1021 | the users default web browser. Git does not have any such |
| 1022 | capability, even with the aid of external programs, as far as |
| 1023 | I am aware. |
| 1024 | |
| 1025 | 1. **The Fossil web interface provides a captcha-gated method to download |
| 1026 | tarballs and ZIP archives for any check-in.**<p> |
| 1027 | See, for example, <https://sqlite.org/src/rchvdwnld/20260704>. |
| 1028 | That link provides access to the last check-in for the day 2026-07-04. |
| 1029 | The last element of the patch can be any hash prefix, timestamp prefix, |
| 1030 | or tag that references a check-in.<p> |
| 1031 | Tarballs and ZIP archives are expensive to compute, not because Fossil |
| 1032 | has any difficulty to assembly the content, |
| 1033 | but rather because the result must be run through zlib compression. |
| 1034 | When computing a new archive, almost all of the CPU time is spent |
| 1035 | inside of the zlib compression library. |
| 1036 | For an SQLite-size tarball, the zlib compression alone can take as |
| 1037 | much as 10 seconds of CPU time. If the tarball/ZIP-archive download |
| 1038 | link is not protected by a captcha, multiple spiders will attempt to |
| 1039 | download every possible tarball and ZIP archive, multiple times per |
| 1040 | day, bringing your server to its knees. |
| 1041 | |
| 1042 | 1. **Repository administrators 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 a cached archive file is 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. |
| @@ -1054,25 +1054,25 @@ | |
| 1054 | a project, and the number of changes they have committed.**<p> |
| 1055 | See <https://fossil-scm.org/home/reports> for that report about |
| 1056 | Fossil itself. |
| 1057 | Many other reports can be generated from the same page by selecting |
| 1058 | different options from the pull-down menus at the top. |
| 1059 | <p>The page is captcha-gated since it is a magnet for spiders. |
| 1060 | |
| 1061 | 1. **The Fossil source code is easy to enhance with new web pages and |
| 1062 | commands.**<p> |
| 1063 | The design of the Fossil implementation makes it easy to extend with |
| 1064 | new capabilities as needs arise. |
| 1065 | <ul type="disk"> |
| 1066 | <li> The code is C89. |
| 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 by 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 |
| @@ -1080,6 +1080,6 @@ | |
| 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 are sufficient to prove my point. |
| 1086 |