Fossil SCM
First incomplete draft of the "101 reasons why Fossil is better than Git" document. Incremental check-in for a work-in-progress.
Commit
92693e3e8a5dcee83c2284dbf250746509c768b8076777afd4992c4b30620171
Parent
63826bf8a4ce730…
1 file changed
+426
+426
| --- a/www/hundredandone.md | ||
| +++ b/www/hundredandone.md | ||
| @@ -0,0 +1,426 @@ | ||
| 1 | +# 101 Reasons Why Fossil Is Better Than Git | |
| 2 | + | |
| 3 | +*This is a work in progress. I only have 38 reasons typed in so far, | |
| 4 | +but I have a separate text file of notes that lists 104 candidate reasons. | |
| 5 | +It's just taking me a while to compose and edit the rationale for each | |
| 6 | +one, so it seems expedient to check-in this draft.* | |
| 7 | + | |
| 8 | + 1. **Fossil comes as a single executable file**.<p> | |
| 9 | + Install Fossil by copying "fossil" (or "fossil.exe") to someplace | |
| 10 | + on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting | |
| 11 | + that one file. Uninstall by deleting that one file.<p> | |
| 12 | + A Git installation requires hundreds of files. You want to use | |
| 13 | + package manager to install, upgrade, or uninstall Git. If you | |
| 14 | + tinker with individual files of a Git installation, you run a high | |
| 15 | + risk of messing things up. | |
| 16 | + | |
| 17 | + 1. **Fossil comes with a built-in full-featured web interface**.<p> | |
| 18 | + The Fossil web interface is on par with GitHub, GitLab, | |
| 19 | + Gitea, and similar. Some people think of Fossil as | |
| 20 | + "Github-in-a-box". Git has "gitweb", but that CGI program | |
| 21 | + is so limited and difficult to set up and use that few people | |
| 22 | + even know it exists, so I do not count it as a built-in web | |
| 23 | + interface for the purposes of this point. | |
| 24 | + | |
| 25 | + 1. **You can run the Fossil web interface locally | |
| 26 | + using the "fossil ui" command.**<p> | |
| 27 | + Just type the command "fossil ui" from any Fossil checkout, | |
| 28 | + or add the name of a Fossil repository file as an argument, | |
| 29 | + and Fossil automatically brings up the full web-based UI | |
| 30 | + in your preferred web browser. This works seamlessly on all | |
| 31 | + platforms. There is nothing extra to install. There is | |
| 32 | + no configuration or setup. It just works. | |
| 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 | |
| 50 | + a single directory name $HOME/Fossils or $HOME/Museum, and then open | |
| 51 | + working check-outs against each repository whereever they are needed. | |
| 52 | + | |
| 53 | + 1. **A single Fossil repository can support multiple working check-outs.** | |
| 54 | + <p> | |
| 55 | + Git has worktrees, but all worktrees checkouts must be on separate | |
| 56 | + branches. Fossil allows multiple working check-outs on the same branch | |
| 57 | + or even on the same checkin. One common pattern is to have one | |
| 58 | + check-out that is being edited, and another than is a pristine, unedited | |
| 59 | + version of the same checkin. This allows both to be compiled | |
| 60 | + simultanteously for performance comparison, or to step through both | |
| 61 | + binaries in two separate "gdb" sessions to hunt down a bug. | |
| 62 | + | |
| 63 | + 1. **A Fossil repository is a single disk file, not a directory | |
| 64 | + hierarchy.**<p> | |
| 65 | + You can "mv" a Fossil repository to a new place. You can "scp" | |
| 66 | + a Fossil repository to another machine. It is just a file, | |
| 67 | + specifically an SQLite database file. | |
| 68 | + | |
| 69 | + 1. **Fossil does not have a staging area**.</p> | |
| 70 | + A user-visible staging area adds no capabilities. (Partial commits | |
| 71 | + are accomplished in Fossil simply by listing the subset of files to | |
| 72 | + be committed on the "fossil commit" command line.) But the staging | |
| 73 | + area does complicate the mental model of the project that Git users | |
| 74 | + need to keep up with, forcing the developer to spend more time thinking | |
| 75 | + about the version control system and hence less time thinking about | |
| 76 | + the project they are working on. | |
| 77 | + | |
| 78 | + 1. **Fossil remembers where all your repositories and working | |
| 79 | + check-outs are located.**<p> | |
| 80 | + This and other information (such as all your global settings) | |
| 81 | + is stored in a per-user database file | |
| 82 | + at $HOME/.config/fossil.db on unix or in %LOCALAPPDATA%/_fossil on | |
| 83 | + Windows. Fossil creates and manages that file automatically; you | |
| 84 | + the user never have to touch it or even know it exists. If you | |
| 85 | + move or rename repositories or check-outs, the database will get | |
| 86 | + temporarily out of sync with reality, but Fossil will automatically | |
| 87 | + resynchornize the next time you do anything with the file or check-out | |
| 88 | + that was moved or renamed.<p> | |
| 89 | + You can get a list of repositories using the "fossil all ls" command, | |
| 90 | + or a list of open check-outs using "fossil all ls --ckout". | |
| 91 | + | |
| 92 | + 1. **Fossil enables you to bring up a web-based UI that shows all of | |
| 93 | + your repositories at once.**<p> | |
| 94 | + Run the command "fossil ui /" and your default web browser will pop | |
| 95 | + of a screen that lists all of your repositories together with the | |
| 96 | + associated project name and how recently that repository was modified. | |
| 97 | + Click on links to bring up repository-specific web-pages. Or click | |
| 98 | + on column headers to sort by that column.<p> | |
| 99 | + If you are like me and have hundreds of repositories on your desktop | |
| 100 | + system, this feature makes it easier to keep track of them all. | |
| 101 | + Are you on an infrequently used travel laptop and forgot where you | |
| 102 | + put a particular repository, this feature helps you find it. | |
| 103 | + | |
| 104 | + 1. **Fossil allows multiple check-ins to have the same tag.**<p> | |
| 105 | + For example, on the SQLite project, every release is tagged with | |
| 106 | + "release". | |
| 107 | + | |
| 108 | + 1. **The Fossil timeline can show all check-ins with a specific tag.**<p> | |
| 109 | + For example, to see all SQLite releases visit | |
| 110 | + <https://sqlite.org/src/timeline?t=release> or to see all | |
| 111 | + Fossil releases go to | |
| 112 | + <https://fossil-scm.org/home/timeline?t=release>. | |
| 113 | + | |
| 114 | + 1. **Fossil has a built-in wiki**.<p> | |
| 115 | + Wiki pages are colocated in the same repository as your code, so that | |
| 116 | + they push, pull, sync, and clone together with your code. | |
| 117 | + | |
| 118 | + 1. **Fossil can associated a wiki page with a particular check-in.**<p> | |
| 119 | + Rather than including a massive and verbose check-in comment on an | |
| 120 | + important check-in (such as the merge of a big new feature), Fossil | |
| 121 | + allows you to assign a wiki page to that check-in. That wiki page | |
| 122 | + is show as part of the check-in information in the web interface. | |
| 123 | + See, for example, the "About" section of | |
| 124 | + [SQLite check-in 2019-11-21T18:28:44.463Z](https://sqlite.org/src/info/2019-11-21T18:28:44.463Z). | |
| 125 | + The wiki page associated with a check-in can be created and revised | |
| 126 | + after the check-in is comimtted and pushed. So it can be used, for | |
| 127 | + example, to add notes or bug reports that occur long after the | |
| 128 | + check-in itself has been inserted into the DAG. | |
| 129 | + | |
| 130 | + 1. **Fossil can associate a wiki page with a particular branch.**<p> | |
| 131 | + You can create a wiki page for a branch that documents the purpose | |
| 132 | + of the branch. The wiki page can be displayed separately (like any | |
| 133 | + other wiki page) but is also displayed automatically at the top of | |
| 134 | + every timeline for that branch. See, for example, | |
| 135 | + <https://sqlite.org/src/timeline?r=autosetup>. | |
| 136 | + | |
| 137 | + 1. **Fossil keeps track of historical branch names.**<p> | |
| 138 | + Git does not actually keep track of branches. Git gives a name | |
| 139 | + to each leaf of the DAG and infers branches based on the name | |
| 140 | + assigned to the leaf. Fossil actually remembers the name of | |
| 141 | + the branch. For example, suppose a customer asks | |
| 142 | + "Whatever became of that setlk-snapshot-fix branch you | |
| 143 | + started last year?" That branch still exists and you | |
| 144 | + can [see it on GitHub](https://github.com/sqlite/sqlite/commits/setlk-snapshot-fix) | |
| 145 | + and [in Fossil](https://sqlite.org/src/timeline?r=setlk-snapshot-fix). | |
| 146 | + Notice, thought, that GitHub does not show how the branch was resolved. | |
| 147 | + Fossil clearly shows that the branch ended up being merged into trunk. | |
| 148 | + GitHub just shows us all ancestors of the leaf node labeled | |
| 149 | + "setlk-snapshot-fix", including ancestors that were in other branches | |
| 150 | + that got merged in, and ancestors that predate the founding of the | |
| 151 | + setlk-snapshot-fix branch. | |
| 152 | + <p> | |
| 153 | + GitHub just cannot shows you the check-ins of branch setlk-snapshot-fix | |
| 154 | + only. There are other third-party tools that will show you that, I am | |
| 155 | + told, but they all require a local clone of the repository. Apparently | |
| 156 | + there is no way to see this information in a web browser runnig on | |
| 157 | + your phone. | |
| 158 | + | |
| 159 | + 1. **Fossil allows multiple branches with the same name.**<p> | |
| 160 | + This feature is used a lot for branches named "experimental" and | |
| 161 | + "mistake". See | |
| 162 | + <https://sqlite.org/src/timeline?r=experimental> and | |
| 163 | + <https://sqlite.org/src/timeline?r=mistake>. Or see | |
| 164 | + [the empty-table-optimizations branch(es)](https://sqlite.org/src/timeline?r=empty-table-optimizations) which was initially merge to trunk and closed | |
| 165 | + on 2025-07-02, but then reopened and continued with more enhancements | |
| 166 | + until it was merged again on 2025-07-08. | |
| 167 | + | |
| 168 | + 1. **Fossil allows legacy SHA1 hashes and newer SHA3-256 hashes in the | |
| 169 | + same repository.**<p> | |
| 170 | + Both Fossil and Git started out using SHA1 hashes. But when the | |
| 171 | + SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) | |
| 172 | + against SHA1 was published on 2017-02-23, the need to migrate to a | |
| 173 | + stronger hash algorithm was recognized. Fossil added the ability | |
| 174 | + to use SHA3-256 as an alternative on 2017-03-01, and to this day | |
| 175 | + it continues to support both, though SHA3-256 is the default for all | |
| 176 | + new repositories and check-ins. But older check-ins that occurred | |
| 177 | + prior to ShAttered still use their original SHA1 hash and so no | |
| 178 | + repositories had to be rebuilt and no hyperlinks were broken.<p> | |
| 179 | + In contrast, a Git repository supports only one hash algorithm. | |
| 180 | + Newer repos can use SHA2, though the default is still SHA1. | |
| 181 | + | |
| 182 | + 1. **Fossil allows check-ins to be identified by timestamp**<p> | |
| 183 | + The canonical name for a check-in is its hash. Both Git and Fossil | |
| 184 | + allow a check-in to be identified by any unique prefix of its hash. | |
| 185 | + But only Fossil allows a check-in to also be identified by its | |
| 186 | + timestamp. The names "2026-02-02T16:03:24.852Z" and "fdebbedbd9a99165" | |
| 187 | + both refer to [the same check-in](https://sqlite.org/src/fdebbedbd9a99165) | |
| 188 | + in SQLite, but the first one has the advantage of giving some time | |
| 189 | + context rather than just being a seemingly random sequence of hexadecimal | |
| 190 | + digits. It is possible that two or more check-ins can have the same | |
| 191 | + timestamp, in which case the timestamp would be ambiguous. And a | |
| 192 | + check-in timestamp can be changed after it is committed, by using | |
| 193 | + a special tag. So timestamp identifiers do not have the uniqueness | |
| 194 | + and stability guarantees as hash identifiers, but they are available | |
| 195 | + as an option and are often useful. | |
| 196 | + | |
| 197 | + 1. **Fossil has a built-in forum.**<p> | |
| 198 | + The forum content replicated via push, pull, sync, and clone just like | |
| 199 | + source code. Forum posts can be enabled per user or for all user or | |
| 200 | + for all users and anonymous passers-by. Some user can be appointed | |
| 201 | + as moderators and posts from untrusted users can be held for | |
| 202 | + moderation. | |
| 203 | + <p> | |
| 204 | + The [Fossil Forum](https://fossil-scm.org/forum), the | |
| 205 | + [SQLite User Forum](https://sqlite.org/forum), and the | |
| 206 | + [SQLite Bugs Forum](https://sqlite.org/bugs) are all forums | |
| 207 | + set up for specific purposes and deliberately kept separate | |
| 208 | + from source code. But for other projects such as | |
| 209 | + [Pikchr](https://pikchr.org/) the Forum and the source code | |
| 210 | + are colocated in the same repository. Thus when you clone the | |
| 211 | + Pikchr source repository, you also get all the Forum history. | |
| 212 | + | |
| 213 | + 1. **Fossil makes it easy to set up a project website using CGI.**<p> | |
| 214 | + If you have an internet-facing server running a CGI-capable web | |
| 215 | + server, you can set up a set up a complete self-hosting project | |
| 216 | + website with a simple CGI script. The canonical | |
| 217 | + [Fossil website](https://fossil-scm.org/home) is really just a | |
| 218 | + CGI script for the Fossil source repository. When you clone the | |
| 219 | + Fossil source code, you don't just get the code, you get the entire | |
| 220 | + website. | |
| 221 | + <p> | |
| 222 | + The CGI script used to run the Fossil website looks like this: | |
| 223 | + <pre> | |
| 224 | + #!/usr/bin/fossil | |
| 225 | + repository: /Fossils/fossil.fossil</pre> | |
| 226 | + You can, of course, also create a self-hosting website using | |
| 227 | + GitLab or similar, but the setup and maintenance is somewhat more | |
| 228 | + involved. You'll also probably need a bigger machine if you are | |
| 229 | + using GitLab, whereas a Fossil website | |
| 230 | + works fine on a 2GiB Raspberry PI or a $6/month VPS. In fairness, | |
| 231 | + I am told that Gitea and Forgejo also work well on a small machine. | |
| 232 | + | |
| 233 | + 1. **Fossil automatically pushes after each commit, by default**.<p> | |
| 234 | + The [autosync setting](/help/autosync), which defaults to "on", causes | |
| 235 | + every commit to automatically push to the default remote. This helps | |
| 236 | + to keep the remote up-to-date and helps all the developers working on | |
| 237 | + the software keep up with what other developers are doing. | |
| 238 | + <p> | |
| 239 | + Users whose prior experience is only with Git might object to | |
| 240 | + autosync, saying that this could cause all kinds of problems for Git | |
| 241 | + if another developer commits ahead of you. True enough, that would | |
| 242 | + cause headaches for Git, but it does not cause any problems for Fossil. | |
| 243 | + The worse that could happen is that the branch will fork. Fossil | |
| 244 | + will usually detect that a fork is about to happen and warn you. | |
| 245 | + But even if you don't get the warning (due to a race) or even if you | |
| 246 | + override the warning and force the commit anyhow, a fork on a branch | |
| 247 | + in Fossil is quite harmless. It shows cleanly on the timeline and | |
| 248 | + is easily resolved. So while autosync might case issues with Git, | |
| 249 | + it does not cause issues in Fossil and so the benefits far outweigh | |
| 250 | + the risks and autosync is the default behavior. | |
| 251 | + | |
| 252 | + 1. **Fossil supports embedded Pikchr in Wiki and in the Forum.**</p> | |
| 253 | + [Pikchr](https://pikchr.org/) is a | |
| 254 | + [PIC-like](https://en.wikipedia.org/wiki/Pic_language) markup language | |
| 255 | + for diagram. The diagrams that appear in the Fossil documentation are | |
| 256 | + all drawn using Pikchr. | |
| 257 | + | |
| 258 | + 1. **Fossil has a Pikchr sandbox for experimenting with Pikchr scripts.** | |
| 259 | + <p> | |
| 260 | + The [pikchrshow page](/pikchrshow) allows users to experiment with and | |
| 261 | + refine their Pikchr diagrams prior to copy/pasting them into their | |
| 262 | + documents. | |
| 263 | + | |
| 264 | + 1. **The Fossil web interface supports "embedded documentation"**</p> | |
| 265 | + See the [Project Documentation](/doc/trunk/www/embeddeddoc.wiki) page | |
| 266 | + for details. Markdown, Wiki, plain-text, and HTML files in the | |
| 267 | + source tree can be rendered and used as documentation pages. This | |
| 268 | + is how all of the documentation files for Fossil itself are rendered. | |
| 269 | + | |
| 270 | + 1. **Fossil has a wiki sandbox for experimenting with markup.**</p> | |
| 271 | + The [wiki sandbox](/wikiedit?name=Sandbox) allows users to experiment | |
| 272 | + with Markdown or other text markup languages supported by Fossil, | |
| 273 | + without making permanent changes to the repository. | |
| 274 | + | |
| 275 | + 1. **Fossil supports interwiki hyperlinks.**<p> | |
| 276 | + Core Git does not have any kind of markup language. Check-in comments | |
| 277 | + in Git are always displayed verbatim. But wrappers such as GitHub, | |
| 278 | + GitLab, Gitea, Forgejo, and similar generally support some variant | |
| 279 | + of Markdown. However, none of these system support links (apart from | |
| 280 | + full URLs) to other wiki systems. Fossil does support interwiki links | |
| 281 | + using the syntax "<tt>remote:path</tt>". So, for example, a check-in | |
| 282 | + in the SQLite source repository (<https://sqlite.org/src>) that wants | |
| 283 | + to reference a bug report (perhaps because it fixes the bug) can | |
| 284 | + include a link of the form "<tt>bugs:/info/</tt><i>HASH</i>" to | |
| 285 | + reference that bug. The source repository knows that "bugs:" refers | |
| 286 | + to the [SQLite Bug Forum](https://sqlite.org/bugs) and completes the | |
| 287 | + link accordingly. | |
| 288 | + <p> | |
| 289 | + Interwiki links are important because (1) they help keep hyperlink | |
| 290 | + shorter, thus helping to avoid typos, and (2) if the target wiki | |
| 291 | + ever modes to a new domain, all the links can be automatically | |
| 292 | + adjusted using a server setting rather than causing all of the links | |
| 293 | + to go stale, and (3) clone can have different mappings for | |
| 294 | + interwiki links, so that (for example) a "bugs:" link in a clone | |
| 295 | + of the source repository can map to a clone of the Bugs Forum | |
| 296 | + repository. | |
| 297 | + | |
| 298 | + 1. **Fossil has a built-in chat server**<p> | |
| 299 | + Users with appropriate permissions (usually just known and registered | |
| 300 | + developers, not anonymous passers-by) can bring up a web-based chat | |
| 301 | + server on any Fossil web-server instance. This feature allow | |
| 302 | + geographically distributed developers to collaborate interactively, | |
| 303 | + without having to involve a third-party chat provider such as Slack. | |
| 304 | + Fossil can be configured to automatically report new check-ins and | |
| 305 | + other activities as chat messages, so that developers are alerted to | |
| 306 | + changes. This feature is built-in to every Fossil web interface | |
| 307 | + and it works with any modern web browser. No extra plugins or | |
| 308 | + JS frameworks are required. Nothing need to be configured, other | |
| 309 | + that enabling the Chat privilege on the permission bits of the | |
| 310 | + users whom you want to have access to Chat. | |
| 311 | + | |
| 312 | + 1. **Fossil supports hyperlinks in check-in comments.**<p> | |
| 313 | + Check-in comments need not be just verbatim text (though they can | |
| 314 | + be depending on repository settings). By default, check-in | |
| 315 | + comments can contain hyperlinks, including hyperlinks to | |
| 316 | + wiki pages, prior check-ins, forum posts, and interwiki hyperlinks. | |
| 317 | + | |
| 318 | + 1. **Fossil supports hyperlink back references**<p> | |
| 319 | + If the check-in comment for a newer commits contains a hyperlink | |
| 320 | + back to an older commit, then when the web interface show the | |
| 321 | + details of the older commit, it also provides are forward | |
| 322 | + reference to the newer commit. | |
| 323 | + | |
| 324 | + 1. **Fossil supports a graphical timeline display of a bisect.**<p> | |
| 325 | + [For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). | |
| 326 | + This is not strictly necessary to make effective use of bisect, but | |
| 327 | + the graphical display does seem to help with situational awareness. | |
| 328 | + | |
| 329 | + 1. **Fossil allows you to revise a check-in comment without | |
| 330 | + rewriting history.**<p> | |
| 331 | + If you find a typo or other error in an historical check-in comment, | |
| 332 | + you can fix the problem in Fossil without having to rewrite all | |
| 333 | + subsequent history. The Fossil file format allows you to set | |
| 334 | + a special tag on the checkin you want to revise (actually a | |
| 335 | + "property", not a "tag", since it also carries a value - the new | |
| 336 | + comment text). The new tag causes both the command-line display | |
| 337 | + and the web interface to show the revised checkin comment rather | |
| 338 | + that the original. Note that the original checkin comment is | |
| 339 | + preserved, so there is still an immutable audit trail. But for | |
| 340 | + common use cases, only the new revised comment is shown. | |
| 341 | + <p> | |
| 342 | + If you are using the web interface and if you have check-in privilege | |
| 343 | + on the repository, then on the /info page for the check-in, under | |
| 344 | + the "Overview" section, to the right of "Other Links:", there is | |
| 345 | + an "edit" link that will take you to a page that lets you change | |
| 346 | + the check-in comment from the web interface. This is the easiest | |
| 347 | + way to make the change. | |
| 348 | + <p> | |
| 349 | + See [Fossil check-in b63d654041](/info/b63d65404) for a | |
| 350 | + recent example. The original comment is shown in the "Overview" | |
| 351 | + section of the checkin details, but the revised comment is show | |
| 352 | + in the timeline. | |
| 353 | + | |
| 354 | + 1. **Fossil allows you to revise a check-in timestamp without | |
| 355 | + rewriting history.**<p> | |
| 356 | + When generating a new checkin, Fossil uses the current time on the | |
| 357 | + system where the commit is occurring. But if the system clock on | |
| 358 | + that system is incorrect, that can lead to a check-in with an | |
| 359 | + inaccurate timestamp. It can be the case that prior check-ins | |
| 360 | + have later timestamps or that subsequent check-ins can have | |
| 361 | + earlier timestamps, resulting in goofy-looking "time-warps" in the | |
| 362 | + timeline. This can be correct by add a timestamp correction tag | |
| 363 | + to the faulty check-in to fix the timestamp. | |
| 364 | + <p> | |
| 365 | + If you are using the web interface and if you have check-in privilege | |
| 366 | + on the repository, then on the /info page for the check-in, under | |
| 367 | + the "Overview" section, to the right of "Other Links:", there is | |
| 368 | + an "edit" link that will take you to a page that lets you change | |
| 369 | + the timestamp for a check-in from the web interface. This is the | |
| 370 | + easiest way to make the change. | |
| 371 | + | |
| 372 | + 1. **Fossil allows you to move a check-in to a new branch without | |
| 373 | + rewriting history.**<p> | |
| 374 | + If you mistakenly commit to the wrong branch, you can move that | |
| 375 | + check-in to a new branch by attaching a special tag. | |
| 376 | + Note, however, that this will also move all subsequent check-ins | |
| 377 | + to that same new branch. | |
| 378 | + <p> | |
| 379 | + In the SQLite and Fossil projects, when developers mistakenly commit | |
| 380 | + on the wrong branch, the usual way we fix that is to move the | |
| 381 | + mistaken check-in to a branch named "mistake". Sometimes we also | |
| 382 | + set the "hidden" tag on that check-in as well, so that it does not | |
| 383 | + show up on ordinary timelines (though it is still part of the | |
| 384 | + immutable audit history and is visible with special options). | |
| 385 | + Then we just redo the commit on the correct branch. | |
| 386 | + <p> | |
| 387 | + If you are using the web interface and if you have check-in privilege | |
| 388 | + on the repository, then on the /info page for the check-in, under | |
| 389 | + the "Overview" section, to the right of "Other Links:", there is | |
| 390 | + an "edit" link that will take you to a page that lets move the check-in | |
| 391 | + to a new branch from the web interface. You can also do this | |
| 392 | + from the Fossil commit-line, but the web interface is easier and less | |
| 393 | + error prone. | |
| 394 | + | |
| 395 | + 1. **Fossil supports unversioned files**.<p> | |
| 396 | + [Unversioned Files](/doc/trunk/www/unvers.wiki) are files held | |
| 397 | + in the repository but which are not versioned are which are not | |
| 398 | + synced by default. Unversioned files are used by Fossil itself | |
| 399 | + to store [Precompiled Binaries of Fossil](/uv/download.html). | |
| 400 | + | |
| 401 | + 1. **Fossil automatically select checkin background colors according to | |
| 402 | + the branch that each checkin occurs on.**<p> | |
| 403 | + This helps to make the timeline easier to read at a glance, by | |
| 404 | + clearly showing which checkins are on which branches. Developers | |
| 405 | + can assign specific colors to branches either when the branch is | |
| 406 | + first created, or after the branch has been running for a while. | |
| 407 | + But experience teaches us that it is better to just let the web | |
| 408 | + interface pick the branch colors automatically. The color is | |
| 409 | + derived from a hash of the branch name. | |
| 410 | + | |
| 411 | + 1. **The Fossil web interface contains a page that allows you to | |
| 412 | + preview what colors Fossil will choose for branch names.**<p> | |
| 413 | + On the [/hash-color-test page](/hash-color-test), one can enter | |
| 414 | + candidate branch names and see in advance what colors Fossil will | |
| 415 | + pick for that branch name. This seems like cheating, but I will | |
| 416 | + admit that I do this myself, sometimes... | |
| 417 | + | |
| 418 | + 1. **The Fossil web interface timeline can be asked to pick check-in | |
| 419 | + colors according to the name of the committer, rather than the branch | |
| 420 | + name.**<p> | |
| 421 | + Simply add the "ubg" query parameter (mnemonic: User BackGround) and | |
| 422 | + the checkin colors will be determined by the committer login name | |
| 423 | + rather than the branch name or any preselected color name. This | |
| 424 | + results in a timeline that gives reader a clearer view of who is | |
| 425 | + making changes. | |
| 426 | + [Example](/timeline?n=200&y=ci&ubg). |
| --- a/www/hundredandone.md | |
| +++ b/www/hundredandone.md | |
| @@ -0,0 +1,426 @@ | |
| --- a/www/hundredandone.md | |
| +++ b/www/hundredandone.md | |
| @@ -0,0 +1,426 @@ | |
| 1 | # 101 Reasons Why Fossil Is Better Than Git |
| 2 | |
| 3 | *This is a work in progress. I only have 38 reasons typed in so far, |
| 4 | but I have a separate text file of notes that lists 104 candidate reasons. |
| 5 | It's just taking me a while to compose and edit the rationale for each |
| 6 | one, so it seems expedient to check-in this draft.* |
| 7 | |
| 8 | 1. **Fossil comes as a single executable file**.<p> |
| 9 | Install Fossil by copying "fossil" (or "fossil.exe") to someplace |
| 10 | on your $PATH (or %PATH%). Upgrade (or downgrade) by overwriting |
| 11 | that one file. Uninstall by deleting that one file.<p> |
| 12 | A Git installation requires hundreds of files. You want to use |
| 13 | package manager to install, upgrade, or uninstall Git. If you |
| 14 | tinker with individual files of a Git installation, you run a high |
| 15 | risk of messing things up. |
| 16 | |
| 17 | 1. **Fossil comes with a built-in full-featured web interface**.<p> |
| 18 | The Fossil web interface is on par with GitHub, GitLab, |
| 19 | Gitea, and similar. Some people think of Fossil as |
| 20 | "Github-in-a-box". Git has "gitweb", but that CGI program |
| 21 | is so limited and difficult to set up and use that few people |
| 22 | even know it exists, so I do not count it as a built-in web |
| 23 | interface for the purposes of this point. |
| 24 | |
| 25 | 1. **You can run the Fossil web interface locally |
| 26 | using the "fossil ui" command.**<p> |
| 27 | Just type the command "fossil ui" from any Fossil checkout, |
| 28 | or add the name of a Fossil repository file as an argument, |
| 29 | and Fossil automatically brings up the full web-based UI |
| 30 | in your preferred web browser. This works seamlessly on all |
| 31 | platforms. There is nothing extra to install. There is |
| 32 | no configuration or setup. It just works. |
| 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 |
| 50 | a single directory name $HOME/Fossils or $HOME/Museum, and then open |
| 51 | working check-outs against each repository whereever they are needed. |
| 52 | |
| 53 | 1. **A single Fossil repository can support multiple working check-outs.** |
| 54 | <p> |
| 55 | Git has worktrees, but all worktrees checkouts must be on separate |
| 56 | branches. Fossil allows multiple working check-outs on the same branch |
| 57 | or even on the same checkin. One common pattern is to have one |
| 58 | check-out that is being edited, and another than is a pristine, unedited |
| 59 | version of the same checkin. This allows both to be compiled |
| 60 | simultanteously for performance comparison, or to step through both |
| 61 | binaries in two separate "gdb" sessions to hunt down a bug. |
| 62 | |
| 63 | 1. **A Fossil repository is a single disk file, not a directory |
| 64 | hierarchy.**<p> |
| 65 | You can "mv" a Fossil repository to a new place. You can "scp" |
| 66 | a Fossil repository to another machine. It is just a file, |
| 67 | specifically an SQLite database file. |
| 68 | |
| 69 | 1. **Fossil does not have a staging area**.</p> |
| 70 | A user-visible staging area adds no capabilities. (Partial commits |
| 71 | are accomplished in Fossil simply by listing the subset of files to |
| 72 | be committed on the "fossil commit" command line.) But the staging |
| 73 | area does complicate the mental model of the project that Git users |
| 74 | need to keep up with, forcing the developer to spend more time thinking |
| 75 | about the version control system and hence less time thinking about |
| 76 | the project they are working on. |
| 77 | |
| 78 | 1. **Fossil remembers where all your repositories and working |
| 79 | check-outs are located.**<p> |
| 80 | This and other information (such as all your global settings) |
| 81 | is stored in a per-user database file |
| 82 | at $HOME/.config/fossil.db on unix or in %LOCALAPPDATA%/_fossil on |
| 83 | Windows. Fossil creates and manages that file automatically; you |
| 84 | the user never have to touch it or even know it exists. If you |
| 85 | move or rename repositories or check-outs, the database will get |
| 86 | temporarily out of sync with reality, but Fossil will automatically |
| 87 | resynchornize the next time you do anything with the file or check-out |
| 88 | that was moved or renamed.<p> |
| 89 | You can get a list of repositories using the "fossil all ls" command, |
| 90 | or a list of open check-outs using "fossil all ls --ckout". |
| 91 | |
| 92 | 1. **Fossil enables you to bring up a web-based UI that shows all of |
| 93 | your repositories at once.**<p> |
| 94 | Run the command "fossil ui /" and your default web browser will pop |
| 95 | of a screen that lists all of your repositories together with the |
| 96 | associated project name and how recently that repository was modified. |
| 97 | Click on links to bring up repository-specific web-pages. Or click |
| 98 | on column headers to sort by that column.<p> |
| 99 | If you are like me and have hundreds of repositories on your desktop |
| 100 | system, this feature makes it easier to keep track of them all. |
| 101 | Are you on an infrequently used travel laptop and forgot where you |
| 102 | put a particular repository, this feature helps you find it. |
| 103 | |
| 104 | 1. **Fossil allows multiple check-ins to have the same tag.**<p> |
| 105 | For example, on the SQLite project, every release is tagged with |
| 106 | "release". |
| 107 | |
| 108 | 1. **The Fossil timeline can show all check-ins with a specific tag.**<p> |
| 109 | For example, to see all SQLite releases visit |
| 110 | <https://sqlite.org/src/timeline?t=release> or to see all |
| 111 | Fossil releases go to |
| 112 | <https://fossil-scm.org/home/timeline?t=release>. |
| 113 | |
| 114 | 1. **Fossil has a built-in wiki**.<p> |
| 115 | Wiki pages are colocated in the same repository as your code, so that |
| 116 | they push, pull, sync, and clone together with your code. |
| 117 | |
| 118 | 1. **Fossil can associated a wiki page with a particular check-in.**<p> |
| 119 | Rather than including a massive and verbose check-in comment on an |
| 120 | important check-in (such as the merge of a big new feature), Fossil |
| 121 | allows you to assign a wiki page to that check-in. That wiki page |
| 122 | is show as part of the check-in information in the web interface. |
| 123 | See, for example, the "About" section of |
| 124 | [SQLite check-in 2019-11-21T18:28:44.463Z](https://sqlite.org/src/info/2019-11-21T18:28:44.463Z). |
| 125 | The wiki page associated with a check-in can be created and revised |
| 126 | after the check-in is comimtted and pushed. So it can be used, for |
| 127 | example, to add notes or bug reports that occur long after the |
| 128 | check-in itself has been inserted into the DAG. |
| 129 | |
| 130 | 1. **Fossil can associate a wiki page with a particular branch.**<p> |
| 131 | You can create a wiki page for a branch that documents the purpose |
| 132 | of the branch. The wiki page can be displayed separately (like any |
| 133 | other wiki page) but is also displayed automatically at the top of |
| 134 | every timeline for that branch. See, for example, |
| 135 | <https://sqlite.org/src/timeline?r=autosetup>. |
| 136 | |
| 137 | 1. **Fossil keeps track of historical branch names.**<p> |
| 138 | Git does not actually keep track of branches. Git gives a name |
| 139 | to each leaf of the DAG and infers branches based on the name |
| 140 | assigned to the leaf. Fossil actually remembers the name of |
| 141 | the branch. For example, suppose a customer asks |
| 142 | "Whatever became of that setlk-snapshot-fix branch you |
| 143 | started last year?" That branch still exists and you |
| 144 | can [see it on GitHub](https://github.com/sqlite/sqlite/commits/setlk-snapshot-fix) |
| 145 | and [in Fossil](https://sqlite.org/src/timeline?r=setlk-snapshot-fix). |
| 146 | Notice, thought, that GitHub does not show how the branch was resolved. |
| 147 | Fossil clearly shows that the branch ended up being merged into trunk. |
| 148 | GitHub just shows us all ancestors of the leaf node labeled |
| 149 | "setlk-snapshot-fix", including ancestors that were in other branches |
| 150 | that got merged in, and ancestors that predate the founding of the |
| 151 | setlk-snapshot-fix branch. |
| 152 | <p> |
| 153 | GitHub just cannot shows you the check-ins of branch setlk-snapshot-fix |
| 154 | only. There are other third-party tools that will show you that, I am |
| 155 | told, but they all require a local clone of the repository. Apparently |
| 156 | there is no way to see this information in a web browser runnig on |
| 157 | your phone. |
| 158 | |
| 159 | 1. **Fossil allows multiple branches with the same name.**<p> |
| 160 | This feature is used a lot for branches named "experimental" and |
| 161 | "mistake". See |
| 162 | <https://sqlite.org/src/timeline?r=experimental> and |
| 163 | <https://sqlite.org/src/timeline?r=mistake>. Or see |
| 164 | [the empty-table-optimizations branch(es)](https://sqlite.org/src/timeline?r=empty-table-optimizations) which was initially merge to trunk and closed |
| 165 | on 2025-07-02, but then reopened and continued with more enhancements |
| 166 | until it was merged again on 2025-07-08. |
| 167 | |
| 168 | 1. **Fossil allows legacy SHA1 hashes and newer SHA3-256 hashes in the |
| 169 | same repository.**<p> |
| 170 | Both Fossil and Git started out using SHA1 hashes. But when the |
| 171 | SHAttered attack](https://www.marc-stevens.nl/research/shattered.io/) |
| 172 | against SHA1 was published on 2017-02-23, the need to migrate to a |
| 173 | stronger hash algorithm was recognized. Fossil added the ability |
| 174 | to use SHA3-256 as an alternative on 2017-03-01, and to this day |
| 175 | it continues to support both, though SHA3-256 is the default for all |
| 176 | new repositories and check-ins. But older check-ins that occurred |
| 177 | prior to ShAttered still use their original SHA1 hash and so no |
| 178 | repositories had to be rebuilt and no hyperlinks were broken.<p> |
| 179 | In contrast, a Git repository supports only one hash algorithm. |
| 180 | Newer repos can use SHA2, though the default is still SHA1. |
| 181 | |
| 182 | 1. **Fossil allows check-ins to be identified by timestamp**<p> |
| 183 | The canonical name for a check-in is its hash. Both Git and Fossil |
| 184 | allow a check-in to be identified by any unique prefix of its hash. |
| 185 | But only Fossil allows a check-in to also be identified by its |
| 186 | timestamp. The names "2026-02-02T16:03:24.852Z" and "fdebbedbd9a99165" |
| 187 | both refer to [the same check-in](https://sqlite.org/src/fdebbedbd9a99165) |
| 188 | in SQLite, but the first one has the advantage of giving some time |
| 189 | context rather than just being a seemingly random sequence of hexadecimal |
| 190 | digits. It is possible that two or more check-ins can have the same |
| 191 | timestamp, in which case the timestamp would be ambiguous. And a |
| 192 | check-in timestamp can be changed after it is committed, by using |
| 193 | a special tag. So timestamp identifiers do not have the uniqueness |
| 194 | and stability guarantees as hash identifiers, but they are available |
| 195 | as an option and are often useful. |
| 196 | |
| 197 | 1. **Fossil has a built-in forum.**<p> |
| 198 | The forum content replicated via push, pull, sync, and clone just like |
| 199 | source code. Forum posts can be enabled per user or for all user or |
| 200 | for all users and anonymous passers-by. Some user can be appointed |
| 201 | as moderators and posts from untrusted users can be held for |
| 202 | moderation. |
| 203 | <p> |
| 204 | The [Fossil Forum](https://fossil-scm.org/forum), the |
| 205 | [SQLite User Forum](https://sqlite.org/forum), and the |
| 206 | [SQLite Bugs Forum](https://sqlite.org/bugs) are all forums |
| 207 | set up for specific purposes and deliberately kept separate |
| 208 | from source code. But for other projects such as |
| 209 | [Pikchr](https://pikchr.org/) the Forum and the source code |
| 210 | are colocated in the same repository. Thus when you clone the |
| 211 | Pikchr source repository, you also get all the Forum history. |
| 212 | |
| 213 | 1. **Fossil makes it easy to set up a project website using CGI.**<p> |
| 214 | If you have an internet-facing server running a CGI-capable web |
| 215 | server, you can set up a set up a complete self-hosting project |
| 216 | website with a simple CGI script. The canonical |
| 217 | [Fossil website](https://fossil-scm.org/home) is really just a |
| 218 | CGI script for the Fossil source repository. When you clone the |
| 219 | Fossil source code, you don't just get the code, you get the entire |
| 220 | website. |
| 221 | <p> |
| 222 | The CGI script used to run the Fossil website looks like this: |
| 223 | <pre> |
| 224 | #!/usr/bin/fossil |
| 225 | repository: /Fossils/fossil.fossil</pre> |
| 226 | You can, of course, also create a self-hosting website using |
| 227 | GitLab or similar, but the setup and maintenance is somewhat more |
| 228 | involved. You'll also probably need a bigger machine if you are |
| 229 | using GitLab, whereas a Fossil website |
| 230 | works fine on a 2GiB Raspberry PI or a $6/month VPS. In fairness, |
| 231 | I am told that Gitea and Forgejo also work well on a small machine. |
| 232 | |
| 233 | 1. **Fossil automatically pushes after each commit, by default**.<p> |
| 234 | The [autosync setting](/help/autosync), which defaults to "on", causes |
| 235 | every commit to automatically push to the default remote. This helps |
| 236 | to keep the remote up-to-date and helps all the developers working on |
| 237 | the software keep up with what other developers are doing. |
| 238 | <p> |
| 239 | Users whose prior experience is only with Git might object to |
| 240 | autosync, saying that this could cause all kinds of problems for Git |
| 241 | if another developer commits ahead of you. True enough, that would |
| 242 | cause headaches for Git, but it does not cause any problems for Fossil. |
| 243 | The worse that could happen is that the branch will fork. Fossil |
| 244 | will usually detect that a fork is about to happen and warn you. |
| 245 | But even if you don't get the warning (due to a race) or even if you |
| 246 | override the warning and force the commit anyhow, a fork on a branch |
| 247 | in Fossil is quite harmless. It shows cleanly on the timeline and |
| 248 | is easily resolved. So while autosync might case issues with Git, |
| 249 | it does not cause issues in Fossil and so the benefits far outweigh |
| 250 | the risks and autosync is the default behavior. |
| 251 | |
| 252 | 1. **Fossil supports embedded Pikchr in Wiki and in the Forum.**</p> |
| 253 | [Pikchr](https://pikchr.org/) is a |
| 254 | [PIC-like](https://en.wikipedia.org/wiki/Pic_language) markup language |
| 255 | for diagram. The diagrams that appear in the Fossil documentation are |
| 256 | all drawn using Pikchr. |
| 257 | |
| 258 | 1. **Fossil has a Pikchr sandbox for experimenting with Pikchr scripts.** |
| 259 | <p> |
| 260 | The [pikchrshow page](/pikchrshow) allows users to experiment with and |
| 261 | refine their Pikchr diagrams prior to copy/pasting them into their |
| 262 | documents. |
| 263 | |
| 264 | 1. **The Fossil web interface supports "embedded documentation"**</p> |
| 265 | See the [Project Documentation](/doc/trunk/www/embeddeddoc.wiki) page |
| 266 | for details. Markdown, Wiki, plain-text, and HTML files in the |
| 267 | source tree can be rendered and used as documentation pages. This |
| 268 | is how all of the documentation files for Fossil itself are rendered. |
| 269 | |
| 270 | 1. **Fossil has a wiki sandbox for experimenting with markup.**</p> |
| 271 | The [wiki sandbox](/wikiedit?name=Sandbox) allows users to experiment |
| 272 | with Markdown or other text markup languages supported by Fossil, |
| 273 | without making permanent changes to the repository. |
| 274 | |
| 275 | 1. **Fossil supports interwiki hyperlinks.**<p> |
| 276 | Core Git does not have any kind of markup language. Check-in comments |
| 277 | in Git are always displayed verbatim. But wrappers such as GitHub, |
| 278 | GitLab, Gitea, Forgejo, and similar generally support some variant |
| 279 | of Markdown. However, none of these system support links (apart from |
| 280 | full URLs) to other wiki systems. Fossil does support interwiki links |
| 281 | using the syntax "<tt>remote:path</tt>". So, for example, a check-in |
| 282 | in the SQLite source repository (<https://sqlite.org/src>) that wants |
| 283 | to reference a bug report (perhaps because it fixes the bug) can |
| 284 | include a link of the form "<tt>bugs:/info/</tt><i>HASH</i>" to |
| 285 | reference that bug. The source repository knows that "bugs:" refers |
| 286 | to the [SQLite Bug Forum](https://sqlite.org/bugs) and completes the |
| 287 | link accordingly. |
| 288 | <p> |
| 289 | Interwiki links are important because (1) they help keep hyperlink |
| 290 | shorter, thus helping to avoid typos, and (2) if the target wiki |
| 291 | ever modes to a new domain, all the links can be automatically |
| 292 | adjusted using a server setting rather than causing all of the links |
| 293 | to go stale, and (3) clone can have different mappings for |
| 294 | interwiki links, so that (for example) a "bugs:" link in a clone |
| 295 | of the source repository can map to a clone of the Bugs Forum |
| 296 | repository. |
| 297 | |
| 298 | 1. **Fossil has a built-in chat server**<p> |
| 299 | Users with appropriate permissions (usually just known and registered |
| 300 | developers, not anonymous passers-by) can bring up a web-based chat |
| 301 | server on any Fossil web-server instance. This feature allow |
| 302 | geographically distributed developers to collaborate interactively, |
| 303 | without having to involve a third-party chat provider such as Slack. |
| 304 | Fossil can be configured to automatically report new check-ins and |
| 305 | other activities as chat messages, so that developers are alerted to |
| 306 | changes. This feature is built-in to every Fossil web interface |
| 307 | and it works with any modern web browser. No extra plugins or |
| 308 | JS frameworks are required. Nothing need to be configured, other |
| 309 | that enabling the Chat privilege on the permission bits of the |
| 310 | users whom you want to have access to Chat. |
| 311 | |
| 312 | 1. **Fossil supports hyperlinks in check-in comments.**<p> |
| 313 | Check-in comments need not be just verbatim text (though they can |
| 314 | be depending on repository settings). By default, check-in |
| 315 | comments can contain hyperlinks, including hyperlinks to |
| 316 | wiki pages, prior check-ins, forum posts, and interwiki hyperlinks. |
| 317 | |
| 318 | 1. **Fossil supports hyperlink back references**<p> |
| 319 | If the check-in comment for a newer commits contains a hyperlink |
| 320 | back to an older commit, then when the web interface show the |
| 321 | details of the older commit, it also provides are forward |
| 322 | reference to the newer commit. |
| 323 | |
| 324 | 1. **Fossil supports a graphical timeline display of a bisect.**<p> |
| 325 | [For example](https://sqlite.org/src/timeline?bid=y2f0bde4bc8-ndfc790f998-ye2634e500c-yff205f2993-y6bb717acf7-nb48d951916-y8364d89c3b-n98a53fb276-y9d68971c58-y498ee8d514-n043ff54fb7-ye33da6d5dc). |
| 326 | This is not strictly necessary to make effective use of bisect, but |
| 327 | the graphical display does seem to help with situational awareness. |
| 328 | |
| 329 | 1. **Fossil allows you to revise a check-in comment without |
| 330 | rewriting history.**<p> |
| 331 | If you find a typo or other error in an historical check-in comment, |
| 332 | you can fix the problem in Fossil without having to rewrite all |
| 333 | subsequent history. The Fossil file format allows you to set |
| 334 | a special tag on the checkin you want to revise (actually a |
| 335 | "property", not a "tag", since it also carries a value - the new |
| 336 | comment text). The new tag causes both the command-line display |
| 337 | and the web interface to show the revised checkin comment rather |
| 338 | that the original. Note that the original checkin comment is |
| 339 | preserved, so there is still an immutable audit trail. But for |
| 340 | common use cases, only the new revised comment is shown. |
| 341 | <p> |
| 342 | If you are using the web interface and if you have check-in privilege |
| 343 | on the repository, then on the /info page for the check-in, under |
| 344 | the "Overview" section, to the right of "Other Links:", there is |
| 345 | an "edit" link that will take you to a page that lets you change |
| 346 | the check-in comment from the web interface. This is the easiest |
| 347 | way to make the change. |
| 348 | <p> |
| 349 | See [Fossil check-in b63d654041](/info/b63d65404) for a |
| 350 | recent example. The original comment is shown in the "Overview" |
| 351 | section of the checkin details, but the revised comment is show |
| 352 | in the timeline. |
| 353 | |
| 354 | 1. **Fossil allows you to revise a check-in timestamp without |
| 355 | rewriting history.**<p> |
| 356 | When generating a new checkin, Fossil uses the current time on the |
| 357 | system where the commit is occurring. But if the system clock on |
| 358 | that system is incorrect, that can lead to a check-in with an |
| 359 | inaccurate timestamp. It can be the case that prior check-ins |
| 360 | have later timestamps or that subsequent check-ins can have |
| 361 | earlier timestamps, resulting in goofy-looking "time-warps" in the |
| 362 | timeline. This can be correct by add a timestamp correction tag |
| 363 | to the faulty check-in to fix the timestamp. |
| 364 | <p> |
| 365 | If you are using the web interface and if you have check-in privilege |
| 366 | on the repository, then on the /info page for the check-in, under |
| 367 | the "Overview" section, to the right of "Other Links:", there is |
| 368 | an "edit" link that will take you to a page that lets you change |
| 369 | the timestamp for a check-in from the web interface. This is the |
| 370 | easiest way to make the change. |
| 371 | |
| 372 | 1. **Fossil allows you to move a check-in to a new branch without |
| 373 | rewriting history.**<p> |
| 374 | If you mistakenly commit to the wrong branch, you can move that |
| 375 | check-in to a new branch by attaching a special tag. |
| 376 | Note, however, that this will also move all subsequent check-ins |
| 377 | to that same new branch. |
| 378 | <p> |
| 379 | In the SQLite and Fossil projects, when developers mistakenly commit |
| 380 | on the wrong branch, the usual way we fix that is to move the |
| 381 | mistaken check-in to a branch named "mistake". Sometimes we also |
| 382 | set the "hidden" tag on that check-in as well, so that it does not |
| 383 | show up on ordinary timelines (though it is still part of the |
| 384 | immutable audit history and is visible with special options). |
| 385 | Then we just redo the commit on the correct branch. |
| 386 | <p> |
| 387 | If you are using the web interface and if you have check-in privilege |
| 388 | on the repository, then on the /info page for the check-in, under |
| 389 | the "Overview" section, to the right of "Other Links:", there is |
| 390 | an "edit" link that will take you to a page that lets move the check-in |
| 391 | to a new branch from the web interface. You can also do this |
| 392 | from the Fossil commit-line, but the web interface is easier and less |
| 393 | error prone. |
| 394 | |
| 395 | 1. **Fossil supports unversioned files**.<p> |
| 396 | [Unversioned Files](/doc/trunk/www/unvers.wiki) are files held |
| 397 | in the repository but which are not versioned are which are not |
| 398 | synced by default. Unversioned files are used by Fossil itself |
| 399 | to store [Precompiled Binaries of Fossil](/uv/download.html). |
| 400 | |
| 401 | 1. **Fossil automatically select checkin background colors according to |
| 402 | the branch that each checkin occurs on.**<p> |
| 403 | This helps to make the timeline easier to read at a glance, by |
| 404 | clearly showing which checkins are on which branches. Developers |
| 405 | can assign specific colors to branches either when the branch is |
| 406 | first created, or after the branch has been running for a while. |
| 407 | But experience teaches us that it is better to just let the web |
| 408 | interface pick the branch colors automatically. The color is |
| 409 | derived from a hash of the branch name. |
| 410 | |
| 411 | 1. **The Fossil web interface contains a page that allows you to |
| 412 | preview what colors Fossil will choose for branch names.**<p> |
| 413 | On the [/hash-color-test page](/hash-color-test), one can enter |
| 414 | candidate branch names and see in advance what colors Fossil will |
| 415 | pick for that branch name. This seems like cheating, but I will |
| 416 | admit that I do this myself, sometimes... |
| 417 | |
| 418 | 1. **The Fossil web interface timeline can be asked to pick check-in |
| 419 | colors according to the name of the committer, rather than the branch |
| 420 | name.**<p> |
| 421 | Simply add the "ubg" query parameter (mnemonic: User BackGround) and |
| 422 | the checkin colors will be determined by the committer login name |
| 423 | rather than the branch name or any preselected color name. This |
| 424 | results in a timeline that gives reader a clearer view of who is |
| 425 | making changes. |
| 426 | [Example](/timeline?n=200&y=ci&ubg). |