Fossil SCM
A new round of updates to the document.
Commit
f023bca98209d0bc38e2ea0abfe8a0a09bbc85b259fa4770b40e9fb31ac4e0c7
Parent
3b1097f6f08d8ee…
1 file changed
+177
-23
+177
-23
| --- www/hundredandone.md | ||
| +++ www/hundredandone.md | ||
| @@ -1,11 +1,13 @@ | ||
| 1 | 1 | # 101 Reasons Why Fossil Is Better Than Git |
| 2 | 2 | |
| 3 | -*This is a work in progress. I only have 38 reasons typed in so far, | |
| 3 | +*This is a work in progress. Only 60 reasons have been typed in so far, | |
| 4 | 4 | but I have a separate text file of notes that lists 104 candidate reasons. |
| 5 | 5 | It's just taking me a while to compose and edit the rationale for each |
| 6 | -one, so it seems expedient to checkin this draft.* | |
| 6 | +one, and to arrange the reasons in a sensible order. I will merge this | |
| 7 | +document from its current branch onto trunk when it gets closer to being | |
| 8 | +ready to publish.* | |
| 7 | 9 | |
| 8 | 10 | 1. **Fossil comes as a single self-contained executable file**.<p> |
| 9 | 11 | Install Fossil by copying "fossil" (or "fossil.exe") to someplace |
| 10 | 12 | on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting |
| 11 | 13 | that one file. Uninstall by deleting that one file.<p> |
| @@ -33,17 +35,57 @@ | ||
| 33 | 35 | |
| 34 | 36 | 1. **The Fossil web interface shows a graphical timeline of changes.**<p> |
| 35 | 37 | See, for example <https://sqlite.org/src/timeline> or |
| 36 | 38 | <https://fossil-scm.org/home/timeline>. Similar timeline features |
| 37 | 39 | for Git are available from the command-line for a local clone |
| 38 | - (for example using "gitk" or other third-party extensions), but | |
| 40 | + (for example using "gitk" or other third-party programs), but | |
| 39 | 41 | nothing with anything close to the capabilities of the Fossil |
| 40 | 42 | timeline is available via a web interface, as far as I know.<p> |
| 41 | 43 | Using the web interface, one can easily check on the status |
| 42 | 44 | of a project when away from the office and without access to a clone |
| 43 | 45 | of the repository, just by visiting a link using |
| 44 | 46 | any web browser, even from a phone. |
| 47 | + | |
| 48 | + 1. **The graphical timeline dynamically adjusts its layout as you resize | |
| 49 | + your browser window.**<p> | |
| 50 | + The server sends down JSON that gives the basic structure of the | |
| 51 | + timeline graph, then Javascript renders the graph. The JS code is | |
| 52 | + small, does not use any third-party frameworks, and is (by default) | |
| 53 | + appended to the HTML page. There is a separate CSS file, but apart | |
| 54 | + from that, the HTML page is completely stand-alone. The local | |
| 55 | + web browser isn't required to go gather lots of separate resources. | |
| 56 | + | |
| 57 | + 1. **The graphical timeline works on a phone.**<p> | |
| 58 | + The layout can get a little cramped on a small display. The | |
| 59 | + timeline does look better on a desktop. | |
| 60 | + Even so, it is functional on a phone and it is very convenient | |
| 61 | + to be able to see what is happening on a project | |
| 62 | + while away from the office and without access to a laptop. | |
| 63 | + | |
| 64 | + 1. **The graphical timeline is bandwidth efficient.**<p> | |
| 65 | + To display a timeline of recent activity on Fossil uses less | |
| 66 | + than 5% of the bandwidth as does GitHub. In a typical example, | |
| 67 | + GitHub requires about 3.5MB of transfer compared to 150KB for | |
| 68 | + Fossil. And for all that 3.5MB, GitHub just gives you a list | |
| 69 | + of recent check-ins without any indication of the branching | |
| 70 | + structure, whereas Fossil gives you an easy-to-read color-coded | |
| 71 | + graph. | |
| 72 | + | |
| 73 | + 1. **The Fossil web interface makes it easy to see a diff between | |
| 74 | + any two checkins with just a couple of clicks.**<p> | |
| 75 | + On the timeline display, click on one node of the graph to | |
| 76 | + select it (a red dot will appear in the center of the node) and | |
| 77 | + then click on any other graph node, and Fossil will compute and | |
| 78 | + display a diff between those two check-ins. | |
| 79 | + | |
| 80 | + 1. **The Fossil web-based diff page shows the context of the two | |
| 81 | + checkins being diffed.**<p> | |
| 82 | + At the top of the web-based diff is a graph that shows | |
| 83 | + specifically the two checkins being diffed and the context | |
| 84 | + around them. | |
| 85 | + [Example](/vdiff?from=052390edaf04a5f5&to=9b686daeeda7b4ca). | |
| 86 | + This helps to relieve any confusion about what you are looking at. | |
| 45 | 87 | |
| 46 | 88 | 1. **In Fossil, a repository is distinct from a working check-out.**<p> |
| 47 | 89 | A Fossil repository can be colocated with the working check-out, as |
| 48 | 90 | they are required to be in Git. But most people keep the repository |
| 49 | 91 | separate. One common pattern is to put all Fossil repositories in |
| @@ -79,16 +121,16 @@ | ||
| 79 | 121 | 1. **Fossil remembers where all your repositories and working |
| 80 | 122 | check-outs are located.**<p> |
| 81 | 123 | This and other information (such as all your global settings) |
| 82 | 124 | is stored in a per-user database file |
| 83 | 125 | at $HOME/.config/fossil.db on unix or in %LOCALAPPDATA%/_fossil on |
| 84 | - Windows. Fossil creates and manages that file automatically; you | |
| 85 | - the user never have to touch it or even know it exists. If you | |
| 126 | + Windows. Fossil creates and manages that file automatically. | |
| 127 | + The user never has know the file even exists. If you | |
| 86 | 128 | move or rename repositories or check-outs, the database will get |
| 87 | 129 | temporarily out of sync with reality, but Fossil will automatically |
| 88 | - resynchornize the next time you do anything with the file or check-out | |
| 89 | - that was moved or renamed.<p> | |
| 130 | + fix the database the next time you do anything with the file or | |
| 131 | + check-out that was moved or renamed.<p> | |
| 90 | 132 | You can get a list of repositories using the "fossil all ls" command, |
| 91 | 133 | or a list of open check-outs using "fossil all ls --ckout". |
| 92 | 134 | |
| 93 | 135 | 1. **Fossil enables you to bring up a web-based UI that shows all of |
| 94 | 136 | your repositories at once.**<p> |
| @@ -139,14 +181,14 @@ | ||
| 139 | 181 | Git does not actually keep track of branches. Git gives a name |
| 140 | 182 | to each leaf of the DAG and infers branches based on the name |
| 141 | 183 | assigned to the leaf. Fossil actually remembers the name of |
| 142 | 184 | the branch. For example, suppose a customer asks |
| 143 | 185 | "Whatever became of that setlk-snapshot-fix branch you |
| 144 | - started last year?" That branch still exists and you | |
| 145 | - can [see it on GitHub](https://github.com/sqlite/sqlite/commits/setlk-snapshot-fix) | |
| 186 | + started last year?" That branch still exists and you can | |
| 187 | + [see it on GitHub](https://github.com/sqlite/sqlite/commits/setlk-snapshot-fix) | |
| 146 | 188 | and [in Fossil](https://sqlite.org/src/timeline?r=setlk-snapshot-fix). |
| 147 | - Notice, thought, that GitHub does not show how the branch was resolved. | |
| 189 | + Notice, though, that GitHub does not show how the branch was resolved. | |
| 148 | 190 | (Aside: Also notice how much faster Fossil renders!) |
| 149 | 191 | Fossil clearly shows that the branch ended up being merged into trunk. |
| 150 | 192 | GitHub just shows us all ancestors of the leaf node labeled |
| 151 | 193 | "setlk-snapshot-fix", including ancestors that were in other branches |
| 152 | 194 | that got merged in, and ancestors that predate the founding of the |
| @@ -153,19 +195,19 @@ | ||
| 153 | 195 | setlk-snapshot-fix branch. |
| 154 | 196 | <p> |
| 155 | 197 | GitHub just cannot shows you the checkins of branch setlk-snapshot-fix |
| 156 | 198 | only. There are other third-party tools that will show you that, I am |
| 157 | 199 | told, but they all require a local clone of the repository. Apparently |
| 158 | - there is no way to see this information in a web browser runnig on | |
| 200 | + there is no way to see this information in a web browser running on | |
| 159 | 201 | your phone. |
| 160 | 202 | |
| 161 | 203 | 1. **Fossil allows multiple branches with the same name.**<p> |
| 162 | 204 | This is used, for example, to name a lot for branches "experimental" |
| 163 | - and mistake". See | |
| 205 | + or "mistake". See | |
| 164 | 206 | <https://sqlite.org/src/timeline?r=experimental> and |
| 165 | 207 | <https://sqlite.org/src/timeline?r=mistake>. Or see |
| 166 | - [the empty-table-optimizations branch(es)](https://sqlite.org/src/timeline?r=empty-table-optimizations) which was initially mergde to trunk and closed | |
| 208 | + [the empty-table-optimizations branch(es)](https://sqlite.org/src/timeline?r=empty-table-optimizations) which was initially merged to trunk and closed | |
| 167 | 209 | on 2025-07-02, but then reopened and continued with more enhancements |
| 168 | 210 | until it was merged again on 2025-07-08. |
| 169 | 211 | |
| 170 | 212 | 1. **Fossil allows legacy SHA1 hashes and newer SHA3-256 hashes in the |
| 171 | 213 | same repository.**<p> |
| @@ -172,11 +214,11 @@ | ||
| 172 | 214 | Both Fossil and Git started out using SHA1 hashes. But when the |
| 173 | 215 | [SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) |
| 174 | 216 | against SHA1 was published on 2017-02-23, the need to migrate to a |
| 175 | 217 | stronger hash algorithm was recognized. Fossil added the ability |
| 176 | 218 | to use SHA3-256 as an alternative on 2017-03-01 (six days after the |
| 177 | - attack was first published), and to this day | |
| 219 | + SHAttered attack was first published), and to this day | |
| 178 | 220 | it continues to support both. SHA3-256 is now the default for all |
| 179 | 221 | new repositories and checkins, though older checkins that occurred |
| 180 | 222 | prior to ShAttered can still use their original SHA1 hash and so no |
| 181 | 223 | repositories had to be rebuilt and no hyperlinks were broken.<p> |
| 182 | 224 | In contrast, after nine years, a Git repository can still only |
| @@ -198,23 +240,23 @@ | ||
| 198 | 240 | a special tag. So timestamp identifiers do not have the uniqueness |
| 199 | 241 | and stability guarantees as hash identifiers, but they are available |
| 200 | 242 | as an option and are often useful. |
| 201 | 243 | |
| 202 | 244 | 1. **Fossil has a built-in forum.**<p> |
| 203 | - The forum content replicated via push, pull, sync, and clone just like | |
| 245 | + The forum content is replicated via push, pull, sync, and clone just like | |
| 204 | 246 | source code. Forum posts can be enabled per user or for all user or |
| 205 | 247 | for all users and anonymous passers-by. Some user can be appointed |
| 206 | 248 | as moderators and posts from untrusted users can be held for |
| 207 | 249 | moderation. |
| 208 | 250 | <p> |
| 209 | 251 | The [Fossil Forum](https://fossil-scm.org/forum), the |
| 210 | 252 | [SQLite User Forum](https://sqlite.org/forum), and the |
| 211 | 253 | [SQLite Bugs Forum](https://sqlite.org/bugs) are all forums |
| 212 | 254 | set up for specific purposes and deliberately kept separate |
| 213 | - from source code. But for other projects such as | |
| 214 | - [Pikchr](https://pikchr.org/) the Forum and the source code | |
| 215 | - are colocated in the same repository. Thus when you clone the | |
| 255 | + from source code. But other projects such as | |
| 256 | + [Pikchr](https://pikchr.org/) comingle their forum and the source code | |
| 257 | + in the same repository. Thus when you clone the | |
| 216 | 258 | Pikchr source repository, you also get all the Forum history. |
| 217 | 259 | |
| 218 | 260 | 1. **Fossil makes it easy to set up a project website using CGI.**<p> |
| 219 | 261 | If you have an internet-facing server running a CGI-capable web |
| 220 | 262 | server, you can set up a set up a complete self-hosting project |
| @@ -227,15 +269,45 @@ | ||
| 227 | 269 | The CGI script used to run the Fossil website looks like this: |
| 228 | 270 | <pre> |
| 229 | 271 | #!/usr/bin/fossil |
| 230 | 272 | repository: /Fossils/fossil.fossil</pre> |
| 231 | 273 | You can, of course, also create a self-hosting website using |
| 232 | - GitLab or similar, but the setup and maintenance is somewhat more | |
| 233 | - involved. You'll also probably need a bigger machine if you are | |
| 234 | - using GitLab, whereas a Fossil website | |
| 274 | + GitLab or Forgejo or similar, but the setup and maintenance is | |
| 275 | + somewhat more involved. You'll also probably need a bigger machine | |
| 276 | + if you are using GitLab, whereas a Fossil website | |
| 235 | 277 | works fine on a 2GiB Raspberry PI or a $6/month VPS. In fairness, |
| 236 | 278 | I am told that Gitea and Forgejo also work well on a small machine. |
| 279 | + | |
| 280 | + 1. **Fossil makes it easy to set up a project website using SCGI.**<p> | |
| 281 | + CGI is easier, but some web servers (ex: Nginx) do not support CGI. | |
| 282 | + If you are using such a web server, you can also run a Fossil | |
| 283 | + server using SCGI. See the | |
| 284 | + [on-line Fossil SCGI documentation](/doc/trunk/www/scgi.wiki) | |
| 285 | + for details. | |
| 286 | + | |
| 287 | + 1. **Fossil makes it easy to set up a project website behind a | |
| 288 | + reverse proxy.**<p> | |
| 289 | + Simply run a [Fossil HTTP server](/doc/trunk/www/server/any/none.md) | |
| 290 | + and have your reverse proxy redirect requests to the local server. | |
| 291 | + | |
| 292 | + 1. **Fossil makes it easy to set up a project website without | |
| 293 | + using any web server at all.**<p> | |
| 294 | + The [fossil server command](/help/server) includes a --cert | |
| 295 | + option with which you can specify a TLS cert for encrypted | |
| 296 | + communication, and with the option, Fossil will except ordinary | |
| 297 | + HTTPS requests from the open internet. There is no need to | |
| 298 | + install and configure a separate web server. | |
| 299 | + | |
| 300 | + 1. **A single Fossil server is able to host multiple projects.**<p> | |
| 301 | + By default, each Fossil server provides content for a single | |
| 302 | + repository. But you can launch a Fossil server that hosts | |
| 303 | + multiple repositories by putting all those repositories in a | |
| 304 | + directory and giving the directory name as the object to serve | |
| 305 | + instead of the repository name. For this mode of operation, | |
| 306 | + the repositories must be named with the "<tt>.fossil</tt>" file | |
| 307 | + suffix. Individual projects have URLs that begin with the | |
| 308 | + repository base name, omitting the "<tt>.fossil</tt>" suffix. | |
| 237 | 309 | |
| 238 | 310 | 1. **Fossil automatically pushes after each commit, by default**.<p> |
| 239 | 311 | The [autosync setting](/help/autosync), which defaults to "on", causes |
| 240 | 312 | every commit to automatically push to the default remote. This helps |
| 241 | 313 | to keep the remote up-to-date and helps all the developers working on |
| @@ -341,10 +413,34 @@ | ||
| 341 | 413 | |
| 342 | 414 | 1. **Fossil supports a graphical timeline display of a bisect.**<p> |
| 343 | 415 | [For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). |
| 344 | 416 | This is not strictly necessary to make effective use of bisect, but |
| 345 | 417 | the graphical display does seem to help with situational awareness. |
| 418 | + | |
| 419 | + 1. **Fossil can show you the first release in which a particular | |
| 420 | + checkin appears, in a single mouse click.**<p> | |
| 421 | + You have to configure the repository by giving it the name of the | |
| 422 | + tag that you use to mark releases, using the | |
| 423 | + [path-to-tag setting](/help/path-to-tag). Suppose you use the tag | |
| 424 | + name "release". Once you do that, then | |
| 425 | + when your are looking at the "info" page for a checkin, a link | |
| 426 | + named "path-to-release" appears in the overview section, and if | |
| 427 | + you click on that link, it brings up a new graph showing the | |
| 428 | + shortest path from that checkin to the next descendant checkin | |
| 429 | + tagged with "release". | |
| 430 | + <p> | |
| 431 | + Example: On the info page at | |
| 432 | + <https://sqlite.org/src/info/b1d7123bc619e3cb>, in the Overview | |
| 433 | + section at the top, to the right of the "Timelines:" label, you | |
| 434 | + will see the "path-to-release" link. Click that link to take you | |
| 435 | + to a page showing an abbreviated path from the original checkin | |
| 436 | + to the first "release" checkin that contains the change. To | |
| 437 | + See the full path, uncheck the "Brief" box near the top of the page. | |
| 438 | + <p> | |
| 439 | + This feature is useful for when you bisect to find a bug, or a bug | |
| 440 | + fix, and want to know the first release in which that bug or bug fix | |
| 441 | + appeared. | |
| 346 | 442 | |
| 347 | 443 | 1. **Fossil allows you to revise a checkin comment without |
| 348 | 444 | rewriting history.**<p> |
| 349 | 445 | If you find a typo or other error in an historical checkin comment, |
| 350 | 446 | you can fix the problem in Fossil without having to rewrite all |
| @@ -413,10 +509,14 @@ | ||
| 413 | 509 | 1. **Fossil supports unversioned files**.<p> |
| 414 | 510 | [Unversioned Files](/doc/trunk/www/unvers.wiki) are files held |
| 415 | 511 | in the repository but which are not versioned are which are not |
| 416 | 512 | synced by default. Unversioned files are used by Fossil itself |
| 417 | 513 | to store [Precompiled Binaries of Fossil](/uv/download.html). |
| 514 | + <p> | |
| 515 | + Unversioned contain is not synced *by default*. But it will | |
| 516 | + sync if you add the -u option to the [fossil sync command](/help/sync). | |
| 517 | + There are also the [fossil uv sync](/help/uv) command. | |
| 418 | 518 | |
| 419 | 519 | 1. **Fossil automatically selects checkin background colors according to |
| 420 | 520 | the branch that each checkin occurs on.**<p> |
| 421 | 521 | This helps to make the timeline easier to read at a glance, by |
| 422 | 522 | clearly showing which checkins are on which branches. Developers |
| @@ -471,11 +571,11 @@ | ||
| 471 | 571 | non-Linux platforms more comfortable for unix geeks, and saves having |
| 472 | 572 | to hunt around and install system-specific alternatives. |
| 473 | 573 | |
| 474 | 574 | 1. **Fossil can transfer all uncommited changes from a check-out on a |
| 475 | 575 | remote system over to a check-out on the local machine.**<p> |
| 476 | - The command is [fossil patch pull](/help?patch). It contacts the | |
| 576 | + The command is [fossil patch pull](/help/patch). It contacts the | |
| 477 | 577 | remote system via SSH, updates its local check-out to the same baseline |
| 478 | 578 | as is found on the remote, then pulls over a minimal set of diffs and |
| 479 | 579 | applies them.<p> |
| 480 | 580 | This is very useful in pre-commit testing. For example, if you have |
| 481 | 581 | a big change on your desktop, and you want to test it before |
| @@ -483,11 +583,65 @@ | ||
| 483 | 583 | platforms and run "fossil patch pull ... && make test". When working |
| 484 | 584 | on SQLite, I will typically do that on a remote Mac, and remote |
| 485 | 585 | Win11 machine, and on a 32-core remote Linux machine that runs |
| 486 | 586 | faster than my desktop. |
| 487 | 587 | |
| 488 | - 1. **Fossil can push uncommitted chagnes to a remote check-out for the | |
| 588 | + 1. **Fossil can push uncommitted changes to a remote check-out for the | |
| 489 | 589 | same project.**<p> |
| 490 | 590 | This is the same as the previous but in reverse. It is used, for |
| 491 | 591 | example, to push proposed changes up to a secure sandbox to be |
| 492 | 592 | reviewed by Claude/Codex/Copilot prior to commit. The sandbox is |
| 493 | 593 | not able to pull, for security reasons, but it can accept a push. |
| 594 | + | |
| 595 | + 1. **Fossil lets you set up aliases for remote checkouts with which | |
| 596 | + you commonly push or pull.**<p> | |
| 597 | + My desktop is named "r21" and I normally do SQLite development | |
| 598 | + work in the direcctory ~/sqlite/sqlite. If I have uncommitted | |
| 599 | + changes that I want to test on Windows, I SSH over to the Win11 | |
| 600 | + machine then run a commands like:<pre> | |
| 601 | + fossil patch pull r21:sqlite/sqlite -f | |
| 602 | + make clean test</pre> | |
| 603 | + But typing in "r21:sqlite/sqlite" can be tedious and error-prone, | |
| 604 | + maybe not so much in this particular examples, but definitely the | |
| 605 | + case for longer hostnames and subdirectory paths. Fortunately, | |
| 606 | + Fossil allows us to define patch alias. On my Win11 machine, | |
| 607 | + the alias named "@" is defined as "r21:sqlite/sqlite" and so I | |
| 608 | + can get by with typing just:<pre> | |
| 609 | + fossil patch pull @ -f</pre> | |
| 610 | + (Aside: the -f option tells the command to first "revert" any | |
| 611 | + uncommitted changes prior currently in the checkout prior to pulling | |
| 612 | + over the new ones from r21:sqlite/sqlite. Without that option, the | |
| 613 | + changes would be merged.) | |
| 614 | + | |
| 615 | + | |
| 616 | + 1. **Fossil allows you view uncommitted changes on a remote machine | |
| 617 | + in a web browser over SSH.**<p> | |
| 618 | + Suppose you have some edits on a remote, headless machine and you | |
| 619 | + would like to review those changes. Fossil lets you see those | |
| 620 | + changes using a command like:<pre> | |
| 621 | + fossil ui remote:path/to/checkout</pre> | |
| 622 | + Substitute the name of your remote and the path to the checkout | |
| 623 | + on the remote, of course.<p> | |
| 624 | + The way this works is that Fossil opens an SSH connection to the | |
| 625 | + remote machine that runs [fossil server](/help/server) on the | |
| 626 | + remote and that tunnels the HTTP content back through SSH connection | |
| 627 | + to your desktop. At the same time, Fossil brings up your default | |
| 628 | + web browser and points it to the local end of your SSH tunnel. | |
| 629 | + | |
| 630 | + 1. **Fossil lets you browse a repository on a remote, headless machine | |
| 631 | + over an SSH connection.**<p> | |
| 632 | + Just run "<tt>fossil ui remote:path/to/repository</tt>" (substituting | |
| 633 | + in the name of the remote machine and the path to the repository you | |
| 634 | + want to browse, of course) and Fossil will pop up a new page on your | |
| 635 | + default web browser (on your desktop!) that is connected over an | |
| 636 | + SSH tunnel to that remote repository. | |
| 637 | + | |
| 638 | + 1. **Fossil lets you see all repositories on a remote, headless machine | |
| 639 | + all at once, over SSH.**<p> | |
| 640 | + The command is "<tt>fossil ui remote:/</tt>". Substitute the name of | |
| 641 | + the remote machine, of course. The special pathname "/" indicates to | |
| 642 | + Fossil that you want to view all of the repositories on that machine. | |
| 643 | + It causes Fossil to consult the $HOME/.config/fossil.db file | |
| 644 | + (or %LOCALAPPDATA%/_fossil on Windows) to find the locations of all | |
| 645 | + repositories on the remote machine, then bring up a web page listing | |
| 646 | + all those repositories. Links on that initial page let you explore | |
| 647 | + deeper into the details of each repository. | |
| 494 | 648 |
| --- www/hundredandone.md | |
| +++ www/hundredandone.md | |
| @@ -1,11 +1,13 @@ | |
| 1 | # 101 Reasons Why Fossil Is Better Than Git |
| 2 | |
| 3 | *This is a work in progress. I only have 38 reasons typed in so far, |
| 4 | but I have a separate text file of notes that lists 104 candidate reasons. |
| 5 | It's just taking me a while to compose and edit the rationale for each |
| 6 | one, so it seems expedient to checkin this draft.* |
| 7 | |
| 8 | 1. **Fossil comes as a single self-contained executable file**.<p> |
| 9 | Install Fossil by copying "fossil" (or "fossil.exe") to someplace |
| 10 | on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting |
| 11 | that one file. Uninstall by deleting that one file.<p> |
| @@ -33,17 +35,57 @@ | |
| 33 | |
| 34 | 1. **The Fossil web interface shows a graphical timeline of changes.**<p> |
| 35 | See, for example <https://sqlite.org/src/timeline> or |
| 36 | <https://fossil-scm.org/home/timeline>. Similar timeline features |
| 37 | for Git are available from the command-line for a local clone |
| 38 | (for example using "gitk" or other third-party extensions), but |
| 39 | nothing with anything close to the capabilities of the Fossil |
| 40 | timeline is available via a web interface, as far as I know.<p> |
| 41 | Using the web interface, one can easily check on the status |
| 42 | of a project when away from the office and without access to a clone |
| 43 | of the repository, just by visiting a link using |
| 44 | any web browser, even from a phone. |
| 45 | |
| 46 | 1. **In Fossil, a repository is distinct from a working check-out.**<p> |
| 47 | A Fossil repository can be colocated with the working check-out, as |
| 48 | they are required to be in Git. But most people keep the repository |
| 49 | separate. One common pattern is to put all Fossil repositories in |
| @@ -79,16 +121,16 @@ | |
| 79 | 1. **Fossil remembers where all your repositories and working |
| 80 | check-outs are located.**<p> |
| 81 | This and other information (such as all your global settings) |
| 82 | is stored in a per-user database file |
| 83 | at $HOME/.config/fossil.db on unix or in %LOCALAPPDATA%/_fossil on |
| 84 | Windows. Fossil creates and manages that file automatically; you |
| 85 | the user never have to touch it or even know it exists. If you |
| 86 | move or rename repositories or check-outs, the database will get |
| 87 | temporarily out of sync with reality, but Fossil will automatically |
| 88 | resynchornize the next time you do anything with the file or check-out |
| 89 | that was moved or renamed.<p> |
| 90 | You can get a list of repositories using the "fossil all ls" command, |
| 91 | or a list of open check-outs using "fossil all ls --ckout". |
| 92 | |
| 93 | 1. **Fossil enables you to bring up a web-based UI that shows all of |
| 94 | your repositories at once.**<p> |
| @@ -139,14 +181,14 @@ | |
| 139 | Git does not actually keep track of branches. Git gives a name |
| 140 | to each leaf of the DAG and infers branches based on the name |
| 141 | assigned to the leaf. Fossil actually remembers the name of |
| 142 | the branch. For example, suppose a customer asks |
| 143 | "Whatever became of that setlk-snapshot-fix branch you |
| 144 | started last year?" That branch still exists and you |
| 145 | can [see it on GitHub](https://github.com/sqlite/sqlite/commits/setlk-snapshot-fix) |
| 146 | and [in Fossil](https://sqlite.org/src/timeline?r=setlk-snapshot-fix). |
| 147 | Notice, thought, that GitHub does not show how the branch was resolved. |
| 148 | (Aside: Also notice how much faster Fossil renders!) |
| 149 | Fossil clearly shows that the branch ended up being merged into trunk. |
| 150 | GitHub just shows us all ancestors of the leaf node labeled |
| 151 | "setlk-snapshot-fix", including ancestors that were in other branches |
| 152 | that got merged in, and ancestors that predate the founding of the |
| @@ -153,19 +195,19 @@ | |
| 153 | setlk-snapshot-fix branch. |
| 154 | <p> |
| 155 | GitHub just cannot shows you the checkins of branch setlk-snapshot-fix |
| 156 | only. There are other third-party tools that will show you that, I am |
| 157 | told, but they all require a local clone of the repository. Apparently |
| 158 | there is no way to see this information in a web browser runnig on |
| 159 | your phone. |
| 160 | |
| 161 | 1. **Fossil allows multiple branches with the same name.**<p> |
| 162 | This is used, for example, to name a lot for branches "experimental" |
| 163 | and mistake". See |
| 164 | <https://sqlite.org/src/timeline?r=experimental> and |
| 165 | <https://sqlite.org/src/timeline?r=mistake>. Or see |
| 166 | [the empty-table-optimizations branch(es)](https://sqlite.org/src/timeline?r=empty-table-optimizations) which was initially mergde to trunk and closed |
| 167 | on 2025-07-02, but then reopened and continued with more enhancements |
| 168 | until it was merged again on 2025-07-08. |
| 169 | |
| 170 | 1. **Fossil allows legacy SHA1 hashes and newer SHA3-256 hashes in the |
| 171 | same repository.**<p> |
| @@ -172,11 +214,11 @@ | |
| 172 | Both Fossil and Git started out using SHA1 hashes. But when the |
| 173 | [SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) |
| 174 | against SHA1 was published on 2017-02-23, the need to migrate to a |
| 175 | stronger hash algorithm was recognized. Fossil added the ability |
| 176 | to use SHA3-256 as an alternative on 2017-03-01 (six days after the |
| 177 | attack was first published), and to this day |
| 178 | it continues to support both. SHA3-256 is now the default for all |
| 179 | new repositories and checkins, though older checkins that occurred |
| 180 | prior to ShAttered can still use their original SHA1 hash and so no |
| 181 | repositories had to be rebuilt and no hyperlinks were broken.<p> |
| 182 | In contrast, after nine years, a Git repository can still only |
| @@ -198,23 +240,23 @@ | |
| 198 | a special tag. So timestamp identifiers do not have the uniqueness |
| 199 | and stability guarantees as hash identifiers, but they are available |
| 200 | as an option and are often useful. |
| 201 | |
| 202 | 1. **Fossil has a built-in forum.**<p> |
| 203 | The forum content replicated via push, pull, sync, and clone just like |
| 204 | source code. Forum posts can be enabled per user or for all user or |
| 205 | for all users and anonymous passers-by. Some user can be appointed |
| 206 | as moderators and posts from untrusted users can be held for |
| 207 | moderation. |
| 208 | <p> |
| 209 | The [Fossil Forum](https://fossil-scm.org/forum), the |
| 210 | [SQLite User Forum](https://sqlite.org/forum), and the |
| 211 | [SQLite Bugs Forum](https://sqlite.org/bugs) are all forums |
| 212 | set up for specific purposes and deliberately kept separate |
| 213 | from source code. But for other projects such as |
| 214 | [Pikchr](https://pikchr.org/) the Forum and the source code |
| 215 | are colocated in the same repository. Thus when you clone the |
| 216 | Pikchr source repository, you also get all the Forum history. |
| 217 | |
| 218 | 1. **Fossil makes it easy to set up a project website using CGI.**<p> |
| 219 | If you have an internet-facing server running a CGI-capable web |
| 220 | server, you can set up a set up a complete self-hosting project |
| @@ -227,15 +269,45 @@ | |
| 227 | The CGI script used to run the Fossil website looks like this: |
| 228 | <pre> |
| 229 | #!/usr/bin/fossil |
| 230 | repository: /Fossils/fossil.fossil</pre> |
| 231 | You can, of course, also create a self-hosting website using |
| 232 | GitLab or similar, but the setup and maintenance is somewhat more |
| 233 | involved. You'll also probably need a bigger machine if you are |
| 234 | using GitLab, whereas a Fossil website |
| 235 | works fine on a 2GiB Raspberry PI or a $6/month VPS. In fairness, |
| 236 | I am told that Gitea and Forgejo also work well on a small machine. |
| 237 | |
| 238 | 1. **Fossil automatically pushes after each commit, by default**.<p> |
| 239 | The [autosync setting](/help/autosync), which defaults to "on", causes |
| 240 | every commit to automatically push to the default remote. This helps |
| 241 | to keep the remote up-to-date and helps all the developers working on |
| @@ -341,10 +413,34 @@ | |
| 341 | |
| 342 | 1. **Fossil supports a graphical timeline display of a bisect.**<p> |
| 343 | [For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). |
| 344 | This is not strictly necessary to make effective use of bisect, but |
| 345 | the graphical display does seem to help with situational awareness. |
| 346 | |
| 347 | 1. **Fossil allows you to revise a checkin comment without |
| 348 | rewriting history.**<p> |
| 349 | If you find a typo or other error in an historical checkin comment, |
| 350 | you can fix the problem in Fossil without having to rewrite all |
| @@ -413,10 +509,14 @@ | |
| 413 | 1. **Fossil supports unversioned files**.<p> |
| 414 | [Unversioned Files](/doc/trunk/www/unvers.wiki) are files held |
| 415 | in the repository but which are not versioned are which are not |
| 416 | synced by default. Unversioned files are used by Fossil itself |
| 417 | to store [Precompiled Binaries of Fossil](/uv/download.html). |
| 418 | |
| 419 | 1. **Fossil automatically selects checkin background colors according to |
| 420 | the branch that each checkin occurs on.**<p> |
| 421 | This helps to make the timeline easier to read at a glance, by |
| 422 | clearly showing which checkins are on which branches. Developers |
| @@ -471,11 +571,11 @@ | |
| 471 | non-Linux platforms more comfortable for unix geeks, and saves having |
| 472 | to hunt around and install system-specific alternatives. |
| 473 | |
| 474 | 1. **Fossil can transfer all uncommited changes from a check-out on a |
| 475 | remote system over to a check-out on the local machine.**<p> |
| 476 | The command is [fossil patch pull](/help?patch). It contacts the |
| 477 | remote system via SSH, updates its local check-out to the same baseline |
| 478 | as is found on the remote, then pulls over a minimal set of diffs and |
| 479 | applies them.<p> |
| 480 | This is very useful in pre-commit testing. For example, if you have |
| 481 | a big change on your desktop, and you want to test it before |
| @@ -483,11 +583,65 @@ | |
| 483 | platforms and run "fossil patch pull ... && make test". When working |
| 484 | on SQLite, I will typically do that on a remote Mac, and remote |
| 485 | Win11 machine, and on a 32-core remote Linux machine that runs |
| 486 | faster than my desktop. |
| 487 | |
| 488 | 1. **Fossil can push uncommitted chagnes to a remote check-out for the |
| 489 | same project.**<p> |
| 490 | This is the same as the previous but in reverse. It is used, for |
| 491 | example, to push proposed changes up to a secure sandbox to be |
| 492 | reviewed by Claude/Codex/Copilot prior to commit. The sandbox is |
| 493 | not able to pull, for security reasons, but it can accept a push. |
| 494 |
| --- www/hundredandone.md | |
| +++ www/hundredandone.md | |
| @@ -1,11 +1,13 @@ | |
| 1 | # 101 Reasons Why Fossil Is Better Than Git |
| 2 | |
| 3 | *This is a work in progress. Only 60 reasons have been typed in so far, |
| 4 | but I have a separate text file of notes that lists 104 candidate reasons. |
| 5 | It's just taking me a while to compose and edit the rationale for each |
| 6 | one, and to arrange the reasons in a sensible order. I will merge this |
| 7 | document from its current branch onto trunk when it gets closer to being |
| 8 | ready to publish.* |
| 9 | |
| 10 | 1. **Fossil comes as a single self-contained executable file**.<p> |
| 11 | Install Fossil by copying "fossil" (or "fossil.exe") to someplace |
| 12 | on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting |
| 13 | that one file. Uninstall by deleting that one file.<p> |
| @@ -33,17 +35,57 @@ | |
| 35 | |
| 36 | 1. **The Fossil web interface shows a graphical timeline of changes.**<p> |
| 37 | See, for example <https://sqlite.org/src/timeline> or |
| 38 | <https://fossil-scm.org/home/timeline>. Similar timeline features |
| 39 | for Git are available from the command-line for a local clone |
| 40 | (for example using "gitk" or other third-party programs), but |
| 41 | nothing with anything close to the capabilities of the Fossil |
| 42 | timeline is available via a web interface, as far as I know.<p> |
| 43 | Using the web interface, one can easily check on the status |
| 44 | of a project when away from the office and without access to a clone |
| 45 | of the repository, just by visiting a link using |
| 46 | any web browser, even from a phone. |
| 47 | |
| 48 | 1. **The graphical timeline dynamically adjusts its layout as you resize |
| 49 | your browser window.**<p> |
| 50 | The server sends down JSON that gives the basic structure of the |
| 51 | timeline graph, then Javascript renders the graph. The JS code is |
| 52 | small, does not use any third-party frameworks, and is (by default) |
| 53 | appended to the HTML page. There is a separate CSS file, but apart |
| 54 | from that, the HTML page is completely stand-alone. The local |
| 55 | web browser isn't required to go gather lots of separate resources. |
| 56 | |
| 57 | 1. **The graphical timeline works on a phone.**<p> |
| 58 | The layout can get a little cramped on a small display. The |
| 59 | timeline does look better on a desktop. |
| 60 | Even so, it is functional on a phone and it is very convenient |
| 61 | to be able to see what is happening on a project |
| 62 | while away from the office and without access to a laptop. |
| 63 | |
| 64 | 1. **The graphical timeline is bandwidth efficient.**<p> |
| 65 | To display a timeline of recent activity on Fossil uses less |
| 66 | than 5% of the bandwidth as does GitHub. In a typical example, |
| 67 | GitHub requires about 3.5MB of transfer compared to 150KB for |
| 68 | Fossil. And for all that 3.5MB, GitHub just gives you a list |
| 69 | of recent check-ins without any indication of the branching |
| 70 | structure, whereas Fossil gives you an easy-to-read color-coded |
| 71 | graph. |
| 72 | |
| 73 | 1. **The Fossil web interface makes it easy to see a diff between |
| 74 | any two checkins with just a couple of clicks.**<p> |
| 75 | On the timeline display, click on one node of the graph to |
| 76 | select it (a red dot will appear in the center of the node) and |
| 77 | then click on any other graph node, and Fossil will compute and |
| 78 | display a diff between those two check-ins. |
| 79 | |
| 80 | 1. **The Fossil web-based diff page shows the context of the two |
| 81 | checkins being diffed.**<p> |
| 82 | At the top of the web-based diff is a graph that shows |
| 83 | specifically the two checkins being diffed and the context |
| 84 | around them. |
| 85 | [Example](/vdiff?from=052390edaf04a5f5&to=9b686daeeda7b4ca). |
| 86 | This helps to relieve any confusion about what you are looking at. |
| 87 | |
| 88 | 1. **In Fossil, a repository is distinct from a working check-out.**<p> |
| 89 | A Fossil repository can be colocated with the working check-out, as |
| 90 | they are required to be in Git. But most people keep the repository |
| 91 | separate. One common pattern is to put all Fossil repositories in |
| @@ -79,16 +121,16 @@ | |
| 121 | 1. **Fossil remembers where all your repositories and working |
| 122 | check-outs are located.**<p> |
| 123 | This and other information (such as all your global settings) |
| 124 | is stored in a per-user database file |
| 125 | at $HOME/.config/fossil.db on unix or in %LOCALAPPDATA%/_fossil on |
| 126 | Windows. Fossil creates and manages that file automatically. |
| 127 | The user never has know the file even exists. If you |
| 128 | move or rename repositories or check-outs, the database will get |
| 129 | temporarily out of sync with reality, but Fossil will automatically |
| 130 | fix the database the next time you do anything with the file or |
| 131 | check-out that was moved or renamed.<p> |
| 132 | You can get a list of repositories using the "fossil all ls" command, |
| 133 | or a list of open check-outs using "fossil all ls --ckout". |
| 134 | |
| 135 | 1. **Fossil enables you to bring up a web-based UI that shows all of |
| 136 | your repositories at once.**<p> |
| @@ -139,14 +181,14 @@ | |
| 181 | Git does not actually keep track of branches. Git gives a name |
| 182 | to each leaf of the DAG and infers branches based on the name |
| 183 | assigned to the leaf. Fossil actually remembers the name of |
| 184 | the branch. For example, suppose a customer asks |
| 185 | "Whatever became of that setlk-snapshot-fix branch you |
| 186 | started last year?" That branch still exists and you can |
| 187 | [see it on GitHub](https://github.com/sqlite/sqlite/commits/setlk-snapshot-fix) |
| 188 | and [in Fossil](https://sqlite.org/src/timeline?r=setlk-snapshot-fix). |
| 189 | Notice, though, that GitHub does not show how the branch was resolved. |
| 190 | (Aside: Also notice how much faster Fossil renders!) |
| 191 | Fossil clearly shows that the branch ended up being merged into trunk. |
| 192 | GitHub just shows us all ancestors of the leaf node labeled |
| 193 | "setlk-snapshot-fix", including ancestors that were in other branches |
| 194 | that got merged in, and ancestors that predate the founding of the |
| @@ -153,19 +195,19 @@ | |
| 195 | setlk-snapshot-fix branch. |
| 196 | <p> |
| 197 | GitHub just cannot shows you the checkins of branch setlk-snapshot-fix |
| 198 | only. There are other third-party tools that will show you that, I am |
| 199 | told, but they all require a local clone of the repository. Apparently |
| 200 | there is no way to see this information in a web browser running on |
| 201 | your phone. |
| 202 | |
| 203 | 1. **Fossil allows multiple branches with the same name.**<p> |
| 204 | This is used, for example, to name a lot for branches "experimental" |
| 205 | or "mistake". See |
| 206 | <https://sqlite.org/src/timeline?r=experimental> and |
| 207 | <https://sqlite.org/src/timeline?r=mistake>. Or see |
| 208 | [the empty-table-optimizations branch(es)](https://sqlite.org/src/timeline?r=empty-table-optimizations) which was initially merged to trunk and closed |
| 209 | on 2025-07-02, but then reopened and continued with more enhancements |
| 210 | until it was merged again on 2025-07-08. |
| 211 | |
| 212 | 1. **Fossil allows legacy SHA1 hashes and newer SHA3-256 hashes in the |
| 213 | same repository.**<p> |
| @@ -172,11 +214,11 @@ | |
| 214 | Both Fossil and Git started out using SHA1 hashes. But when the |
| 215 | [SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) |
| 216 | against SHA1 was published on 2017-02-23, the need to migrate to a |
| 217 | stronger hash algorithm was recognized. Fossil added the ability |
| 218 | to use SHA3-256 as an alternative on 2017-03-01 (six days after the |
| 219 | SHAttered attack was first published), and to this day |
| 220 | it continues to support both. SHA3-256 is now the default for all |
| 221 | new repositories and checkins, though older checkins that occurred |
| 222 | prior to ShAttered can still use their original SHA1 hash and so no |
| 223 | repositories had to be rebuilt and no hyperlinks were broken.<p> |
| 224 | In contrast, after nine years, a Git repository can still only |
| @@ -198,23 +240,23 @@ | |
| 240 | a special tag. So timestamp identifiers do not have the uniqueness |
| 241 | and stability guarantees as hash identifiers, but they are available |
| 242 | as an option and are often useful. |
| 243 | |
| 244 | 1. **Fossil has a built-in forum.**<p> |
| 245 | The forum content is replicated via push, pull, sync, and clone just like |
| 246 | source code. Forum posts can be enabled per user or for all user or |
| 247 | for all users and anonymous passers-by. Some user can be appointed |
| 248 | as moderators and posts from untrusted users can be held for |
| 249 | moderation. |
| 250 | <p> |
| 251 | The [Fossil Forum](https://fossil-scm.org/forum), the |
| 252 | [SQLite User Forum](https://sqlite.org/forum), and the |
| 253 | [SQLite Bugs Forum](https://sqlite.org/bugs) are all forums |
| 254 | set up for specific purposes and deliberately kept separate |
| 255 | from source code. But other projects such as |
| 256 | [Pikchr](https://pikchr.org/) comingle their forum and the source code |
| 257 | in the same repository. Thus when you clone the |
| 258 | Pikchr source repository, you also get all the Forum history. |
| 259 | |
| 260 | 1. **Fossil makes it easy to set up a project website using CGI.**<p> |
| 261 | If you have an internet-facing server running a CGI-capable web |
| 262 | server, you can set up a set up a complete self-hosting project |
| @@ -227,15 +269,45 @@ | |
| 269 | The CGI script used to run the Fossil website looks like this: |
| 270 | <pre> |
| 271 | #!/usr/bin/fossil |
| 272 | repository: /Fossils/fossil.fossil</pre> |
| 273 | You can, of course, also create a self-hosting website using |
| 274 | GitLab or Forgejo or similar, but the setup and maintenance is |
| 275 | somewhat more involved. You'll also probably need a bigger machine |
| 276 | if you are using GitLab, whereas a Fossil website |
| 277 | works fine on a 2GiB Raspberry PI or a $6/month VPS. In fairness, |
| 278 | I am told that Gitea and Forgejo also work well on a small machine. |
| 279 | |
| 280 | 1. **Fossil makes it easy to set up a project website using SCGI.**<p> |
| 281 | CGI is easier, but some web servers (ex: Nginx) do not support CGI. |
| 282 | If you are using such a web server, you can also run a Fossil |
| 283 | server using SCGI. See the |
| 284 | [on-line Fossil SCGI documentation](/doc/trunk/www/scgi.wiki) |
| 285 | for details. |
| 286 | |
| 287 | 1. **Fossil makes it easy to set up a project website behind a |
| 288 | reverse proxy.**<p> |
| 289 | Simply run a [Fossil HTTP server](/doc/trunk/www/server/any/none.md) |
| 290 | and have your reverse proxy redirect requests to the local server. |
| 291 | |
| 292 | 1. **Fossil makes it easy to set up a project website without |
| 293 | using any web server at all.**<p> |
| 294 | The [fossil server command](/help/server) includes a --cert |
| 295 | option with which you can specify a TLS cert for encrypted |
| 296 | communication, and with the option, Fossil will except ordinary |
| 297 | HTTPS requests from the open internet. There is no need to |
| 298 | install and configure a separate web server. |
| 299 | |
| 300 | 1. **A single Fossil server is able to host multiple projects.**<p> |
| 301 | By default, each Fossil server provides content for a single |
| 302 | repository. But you can launch a Fossil server that hosts |
| 303 | multiple repositories by putting all those repositories in a |
| 304 | directory and giving the directory name as the object to serve |
| 305 | instead of the repository name. For this mode of operation, |
| 306 | the repositories must be named with the "<tt>.fossil</tt>" file |
| 307 | suffix. Individual projects have URLs that begin with the |
| 308 | repository base name, omitting the "<tt>.fossil</tt>" suffix. |
| 309 | |
| 310 | 1. **Fossil automatically pushes after each commit, by default**.<p> |
| 311 | The [autosync setting](/help/autosync), which defaults to "on", causes |
| 312 | every commit to automatically push to the default remote. This helps |
| 313 | to keep the remote up-to-date and helps all the developers working on |
| @@ -341,10 +413,34 @@ | |
| 413 | |
| 414 | 1. **Fossil supports a graphical timeline display of a bisect.**<p> |
| 415 | [For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). |
| 416 | This is not strictly necessary to make effective use of bisect, but |
| 417 | the graphical display does seem to help with situational awareness. |
| 418 | |
| 419 | 1. **Fossil can show you the first release in which a particular |
| 420 | checkin appears, in a single mouse click.**<p> |
| 421 | You have to configure the repository by giving it the name of the |
| 422 | tag that you use to mark releases, using the |
| 423 | [path-to-tag setting](/help/path-to-tag). Suppose you use the tag |
| 424 | name "release". Once you do that, then |
| 425 | when your are looking at the "info" page for a checkin, a link |
| 426 | named "path-to-release" appears in the overview section, and if |
| 427 | you click on that link, it brings up a new graph showing the |
| 428 | shortest path from that checkin to the next descendant checkin |
| 429 | tagged with "release". |
| 430 | <p> |
| 431 | Example: On the info page at |
| 432 | <https://sqlite.org/src/info/b1d7123bc619e3cb>, in the Overview |
| 433 | section at the top, to the right of the "Timelines:" label, you |
| 434 | will see the "path-to-release" link. Click that link to take you |
| 435 | to a page showing an abbreviated path from the original checkin |
| 436 | to the first "release" checkin that contains the change. To |
| 437 | See the full path, uncheck the "Brief" box near the top of the page. |
| 438 | <p> |
| 439 | This feature is useful for when you bisect to find a bug, or a bug |
| 440 | fix, and want to know the first release in which that bug or bug fix |
| 441 | appeared. |
| 442 | |
| 443 | 1. **Fossil allows you to revise a checkin comment without |
| 444 | rewriting history.**<p> |
| 445 | If you find a typo or other error in an historical checkin comment, |
| 446 | you can fix the problem in Fossil without having to rewrite all |
| @@ -413,10 +509,14 @@ | |
| 509 | 1. **Fossil supports unversioned files**.<p> |
| 510 | [Unversioned Files](/doc/trunk/www/unvers.wiki) are files held |
| 511 | in the repository but which are not versioned are which are not |
| 512 | synced by default. Unversioned files are used by Fossil itself |
| 513 | to store [Precompiled Binaries of Fossil](/uv/download.html). |
| 514 | <p> |
| 515 | Unversioned contain is not synced *by default*. But it will |
| 516 | sync if you add the -u option to the [fossil sync command](/help/sync). |
| 517 | There are also the [fossil uv sync](/help/uv) command. |
| 518 | |
| 519 | 1. **Fossil automatically selects checkin background colors according to |
| 520 | the branch that each checkin occurs on.**<p> |
| 521 | This helps to make the timeline easier to read at a glance, by |
| 522 | clearly showing which checkins are on which branches. Developers |
| @@ -471,11 +571,11 @@ | |
| 571 | non-Linux platforms more comfortable for unix geeks, and saves having |
| 572 | to hunt around and install system-specific alternatives. |
| 573 | |
| 574 | 1. **Fossil can transfer all uncommited changes from a check-out on a |
| 575 | remote system over to a check-out on the local machine.**<p> |
| 576 | The command is [fossil patch pull](/help/patch). It contacts the |
| 577 | remote system via SSH, updates its local check-out to the same baseline |
| 578 | as is found on the remote, then pulls over a minimal set of diffs and |
| 579 | applies them.<p> |
| 580 | This is very useful in pre-commit testing. For example, if you have |
| 581 | a big change on your desktop, and you want to test it before |
| @@ -483,11 +583,65 @@ | |
| 583 | platforms and run "fossil patch pull ... && make test". When working |
| 584 | on SQLite, I will typically do that on a remote Mac, and remote |
| 585 | Win11 machine, and on a 32-core remote Linux machine that runs |
| 586 | faster than my desktop. |
| 587 | |
| 588 | 1. **Fossil can push uncommitted changes to a remote check-out for the |
| 589 | same project.**<p> |
| 590 | This is the same as the previous but in reverse. It is used, for |
| 591 | example, to push proposed changes up to a secure sandbox to be |
| 592 | reviewed by Claude/Codex/Copilot prior to commit. The sandbox is |
| 593 | not able to pull, for security reasons, but it can accept a push. |
| 594 | |
| 595 | 1. **Fossil lets you set up aliases for remote checkouts with which |
| 596 | you commonly push or pull.**<p> |
| 597 | My desktop is named "r21" and I normally do SQLite development |
| 598 | work in the direcctory ~/sqlite/sqlite. If I have uncommitted |
| 599 | changes that I want to test on Windows, I SSH over to the Win11 |
| 600 | machine then run a commands like:<pre> |
| 601 | fossil patch pull r21:sqlite/sqlite -f |
| 602 | make clean test</pre> |
| 603 | But typing in "r21:sqlite/sqlite" can be tedious and error-prone, |
| 604 | maybe not so much in this particular examples, but definitely the |
| 605 | case for longer hostnames and subdirectory paths. Fortunately, |
| 606 | Fossil allows us to define patch alias. On my Win11 machine, |
| 607 | the alias named "@" is defined as "r21:sqlite/sqlite" and so I |
| 608 | can get by with typing just:<pre> |
| 609 | fossil patch pull @ -f</pre> |
| 610 | (Aside: the -f option tells the command to first "revert" any |
| 611 | uncommitted changes prior currently in the checkout prior to pulling |
| 612 | over the new ones from r21:sqlite/sqlite. Without that option, the |
| 613 | changes would be merged.) |
| 614 | |
| 615 | |
| 616 | 1. **Fossil allows you view uncommitted changes on a remote machine |
| 617 | in a web browser over SSH.**<p> |
| 618 | Suppose you have some edits on a remote, headless machine and you |
| 619 | would like to review those changes. Fossil lets you see those |
| 620 | changes using a command like:<pre> |
| 621 | fossil ui remote:path/to/checkout</pre> |
| 622 | Substitute the name of your remote and the path to the checkout |
| 623 | on the remote, of course.<p> |
| 624 | The way this works is that Fossil opens an SSH connection to the |
| 625 | remote machine that runs [fossil server](/help/server) on the |
| 626 | remote and that tunnels the HTTP content back through SSH connection |
| 627 | to your desktop. At the same time, Fossil brings up your default |
| 628 | web browser and points it to the local end of your SSH tunnel. |
| 629 | |
| 630 | 1. **Fossil lets you browse a repository on a remote, headless machine |
| 631 | over an SSH connection.**<p> |
| 632 | Just run "<tt>fossil ui remote:path/to/repository</tt>" (substituting |
| 633 | in the name of the remote machine and the path to the repository you |
| 634 | want to browse, of course) and Fossil will pop up a new page on your |
| 635 | default web browser (on your desktop!) that is connected over an |
| 636 | SSH tunnel to that remote repository. |
| 637 | |
| 638 | 1. **Fossil lets you see all repositories on a remote, headless machine |
| 639 | all at once, over SSH.**<p> |
| 640 | The command is "<tt>fossil ui remote:/</tt>". Substitute the name of |
| 641 | the remote machine, of course. The special pathname "/" indicates to |
| 642 | Fossil that you want to view all of the repositories on that machine. |
| 643 | It causes Fossil to consult the $HOME/.config/fossil.db file |
| 644 | (or %LOCALAPPDATA%/_fossil on Windows) to find the locations of all |
| 645 | repositories on the remote machine, then bring up a web page listing |
| 646 | all those repositories. Links on that initial page let you explore |
| 647 | deeper into the details of each repository. |
| 648 |