Fossil SCM

fossil-scm / www / fossil-v-git.wiki
Source Blame History 984 lines
ae0628a… drh 1 <title>Fossil Versus Git</title>
ae0628a… drh 2
ae0628a… drh 3 <h2>1.0 Don't Stress!</h2>
ae0628a… drh 4
3609ff7… wyoung 5 The feature sets of Fossil and [http://git-scm.com | Git] overlap in
3609ff7… wyoung 6 many ways. Both are
3609ff7… wyoung 7 [https://en.wikipedia.org/wiki/Distributed_version_control | distributed
e299892… wyoung 8 version control systems] which store a tree of check-in objects to a
e299892… wyoung 9 local repository clone. In both systems, the local clone starts out as a
e299892… wyoung 10 full copy of the remote parent. New content gets added to the local
e299892… wyoung 11 clone and then later optionally pushed up to the remote, and changes to
e299892… wyoung 12 the remote can be pulled down to the local clone at will. Both systems
0996347… wyoung 13 offer diffing, patching, branching, merging, cherry-picking, bisecting,
3609ff7… wyoung 14 private branches, a stash, etc.
a5284fa… drh 15
16cb9c0… wyoung 16 Fossil has inbound and outbound Git conversion features, so if you start
16cb9c0… wyoung 17 out using one DVCS and later decide you like the other better, you can
431245e… wyoung 18 easily [./inout.wiki | move your version-controlled file content].¹
16cb9c0… wyoung 19
e299892… wyoung 20 In this document, we set all of that similarity and interoperability
e299892… wyoung 21 aside and focus on the important differences between the two, especially
e299892… wyoung 22 those that impact the user experience.
a5284fa… drh 23
a5284fa… drh 24 Keep in mind that you are reading this on a Fossil website, and though
35fe8bf… wyoung 25 we try to be fair, the information here will inevitably
35fe8bf… wyoung 26 be biased in favor of Fossil purely because we spend most of our
16cb9c0… wyoung 27 time using Fossil, not Git. Ask around for second opinions from
a5284fa… drh 28 people who have used <em>both</em> Fossil and Git.
7e907a1… wyoung 29
7e907a1… wyoung 30 If you want a more practical, less philosophical guide to moving from
7e907a1… wyoung 31 Git to Fossil, see our [./gitusers.md | Git to Fossil Translation Guide].
8452627… wyoung 32
6ae97be… drh 33
6ae97be… drh 34 <h2>2.0 Differences Between Fossil And Git</h2>
6ae97be… drh 35
6ae97be… drh 36 Differences between Fossil and Git are summarized by the following table,
6ae97be… drh 37 with further description in the text that follows.
6ae97be… drh 38
8a1ba49… wyoung 39 <table style="width: fit-content">
8a1ba49… wyoung 40 <tr><th>GIT</th><th>FOSSIL</th><th>more</th></tr>
fd9e211… wyoung 41 <tr>
fd9e211… wyoung 42 <td>File versioning only</td>
8a1ba49… wyoung 43 <td>
8a1ba49… wyoung 44 VCS, tickets, wiki, docs, notes, forum, chat, UI,
8a1ba49… wyoung 45 [https://en.wikipedia.org/wiki/Role-based_access_control|RBAC]
8a1ba49… wyoung 46 </td>
fd9e211… wyoung 47 <td><a href="#features">2.1&nbsp;&darr;</a></td>
fd9e211… wyoung 48 </tr>
fd9e211… wyoung 49 <tr>
358d7d8… drh 50 <td>A federation of many small programs</td>
358d7d8… drh 51 <td>One self-contained, stand-alone executable</td>
41b3491… drh 52 <td><a href="#selfcontained">2.2&nbsp;&darr;</a></td>
fd9e211… wyoung 53 </tr>
fd9e211… wyoung 54 <tr>
358d7d8… drh 55 <td>Custom key/value data store</td>
358d7d8… drh 56 <td>[https://sqlite.org/mostdeployed.html|The most used SQL database in the world]</td>
fd9e211… wyoung 57 <td><a href="#durable">2.3&nbsp;&darr;</a></td>
fd9e211… wyoung 58 </tr>
fd9e211… wyoung 59 <tr>
358d7d8… drh 60 <td>Runs natively on POSIX systems</td>
358d7d8… drh 61 <td>Runs natively on both POSIX and Windows</td>
fd9e211… wyoung 62 <td><a href="#portable">2.4&nbsp;&darr;</a></td>
fd9e211… wyoung 63 </tr>
fd9e211… wyoung 64 <tr>
fd9e211… wyoung 65 <td>Bazaar-style development</td>
fd9e211… wyoung 66 <td>Cathedral-style development</td>
fd9e211… wyoung 67 <td><a href="#devorg">2.5.1&nbsp;&darr;</a></td>
fd9e211… wyoung 68 </tr>
fd9e211… wyoung 69 <tr>
fd9e211… wyoung 70 <td>Designed for Linux kernel development</td>
fd9e211… wyoung 71 <td>Designed for SQLite development</td>
fd9e211… wyoung 72 <td><a href="#scale">2.5.2&nbsp;&darr;</a></td>
fd9e211… wyoung 73 </tr>
fd9e211… wyoung 74 <tr>
fd9e211… wyoung 75 <td>Focus on individual branches</td>
fd9e211… wyoung 76 <td>Focus on the entire tree of changes</td>
b08f062… drh 77 <td><a href="#branches">2.5.3&nbsp;&darr;</a></td>
fd9e211… wyoung 78 </tr>
fd9e211… wyoung 79 <tr>
fd9e211… wyoung 80 <td>One check-out per repository</td>
fd9e211… wyoung 81 <td>Many check-outs per repository</td>
fd9e211… wyoung 82 <td><a href="#checkouts">2.6&nbsp;&darr;</a></td>
fd9e211… wyoung 83 </tr>
fd9e211… wyoung 84 <tr>
fd9e211… wyoung 85 <td>Remembers what you should have done</td>
fd9e211… wyoung 86 <td>Remembers what you actually did</td>
fd9e211… wyoung 87 <td><a href="#history">2.7&nbsp;&darr;</a></td>
fd9e211… wyoung 88 </tr>
fd9e211… wyoung 89 <tr>
fd9e211… wyoung 90 <td>Commit first</td>
fd9e211… wyoung 91 <td>Test first</td>
fd9e211… wyoung 92 <td><a href="#testing">2.8&nbsp;&darr;</a></td>
fd9e211… wyoung 93 </tr>
fd9e211… wyoung 94 <tr>
358d7d8… drh 95 <td>SHA-1 or SHA-2</td>
358d7d8… drh 96 <td>SHA-1 and/or SHA-3, in the same repository</td>
fd9e211… wyoung 97 <td><a href="#hash">2.9&nbsp;&darr;</a></td>
fd9e211… wyoung 98 </tr>
8a1ba49… wyoung 99 </table>
5c24bee… wyoung 100
5c24bee… wyoung 101 <h3 id="features">2.1 Featureful</h3>
5566c85… drh 102
5566c85… drh 103 Git provides file versioning services only, whereas Fossil adds
bd7c47c… wyoung 104 an integrated [./wikitheory.wiki | wiki],
ae0628a… drh 105 [./bugtheory.wiki | ticketing &amp; bug tracking],
fd1282e… drh 106 [./embeddeddoc.wiki | embedded documentation],
f5ab488… drh 107 [./event.wiki | technical notes], a [./forum.wiki | web forum],
f5ab488… drh 108 and a [./chat.md | chat service],
c5a74af… wyoung 109 all within a single nicely-designed [./customskin.md|skinnable] web
c64f28d… drh 110 [/help/ui|UI],
779ddef… wyoung 111 protected by [./caps/ | a fine-grained role-based
bd7c47c… wyoung 112 access control system].
fd99012… wyoung 113 These additional capabilities are available for Git as 3rd-party
fd99012… wyoung 114 add-ons, but with Fossil they are integrated into
c7afd68… wyoung 115 the design, to the point that it approximates
fd99012… wyoung 116 "[https://github.com/ | GitHub]-in-a-box."
fd99012… wyoung 117
c7afd68… wyoung 118 Even if you only want straight version control, Fossil has affordances
c7afd68… wyoung 119 not available in Git.
c7afd68… wyoung 120
c7afd68… wyoung 121 For instance, Fossil can do operations over all local repo clones and
c7afd68… wyoung 122 check-out directories with a single command. You can say "<tt>fossil
c7afd68… wyoung 123 all sync</tt>" on a laptop prior to taking it off the network hosting
c7afd68… wyoung 124 those repos, as before going on a trip. It doesn't matter if those
c7afd68… wyoung 125 repos are private and restricted to your company network or public
c7afd68… wyoung 126 Internet-hosted repos, you get synced up with everything you need while
c7afd68… wyoung 127 off-network.
c7afd68… wyoung 128
c7afd68… wyoung 129 You get the same capability with several other Fossil
c7afd68… wyoung 130 sub-commands as well, such as "<tt>fossil all changes</tt>" to get a list of files
d357f81… wyoung 131 that you forgot to commit prior to the end of your working day, across
d357f81… wyoung 132 all repos.
d357f81… wyoung 133
d357f81… wyoung 134 Whenever Fossil is told to modify the local checkout in some destructive
c64f28d… drh 135 way ([/help/rm|fossil rm], [/help/update|fossil update],
c64f28d… drh 136 [/help/revert|fossil revert], etc.) Fossil remembers the prior state
d357f81… wyoung 137 and is able to return the check-out directory to that state with a
c7afd68… wyoung 138 <tt>fossil undo</tt> command. While you cannot undo a commit in Fossil
c7afd68… wyoung 139 — [#history | on purpose!] — as long as the change remains confined to
d357f81… wyoung 140 the local check-out directory only, Fossil makes undo
d357f81… wyoung 141 [https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things|easier than in
d357f81… wyoung 142 Git].
d357f81… wyoung 143
c7afd68… wyoung 144 For developers who choose to self-host projects rather than rely on a
c7afd68… wyoung 145 3rd-party service such as GitHub, Fossil is much easier to set up:
f146e21… drh 146 the stand-alone Fossil executable together with a [./server/any/cgi.md|2-line CGI script]
ca891ab… drh 147 suffice to instantiate a full-featured developer website. To accomplish
fcfaae3… jan.nijtmans 148 the same using Git requires locating, installing, configuring, integrating,
ca891ab… drh 149 and managing a wide assortment of separate tools. Standing up a developer
ca891ab… drh 150 website using Fossil can be done in minutes, whereas doing the same using
ca891ab… drh 151 Git requires hours or days.
ca891ab… drh 152
5c24bee… wyoung 153 Fossil is small, complete, and self-contained. If you clone
5c24bee… wyoung 154 [https://github.com/git/git|Git's self-hosting repository], you get just
5c24bee… wyoung 155 Git's source code. If you clone Fossil's self-hosting repository, you
5c24bee… wyoung 156 get the entire Fossil website — source code, documentation, ticket
5c24bee… wyoung 157 history, and so forth.² That means you get a copy of this very article
5c24bee… wyoung 158 and all of its historical versions, plus the same for all of the other
5c24bee… wyoung 159 public content on this site.
d23a845… wyoung 160
d23a845… wyoung 161
41b3491… drh 162 <h3 id="selfcontained" name="selfcontained">2.2 Self Contained</h3>
d23a845… wyoung 163
5c24bee… wyoung 164 Git is actually a collection of many small tools, each doing one small
5c24bee… wyoung 165 part of the job, which can be recombined (by experts) to perform
5c24bee… wyoung 166 powerful operations. Git has a lot of complexity and many dependencies,
5c24bee… wyoung 167 so that most people end up installing it via some kind of package
00af3db… wyoung 168 manager, simply because the creation of complicated binary packages is
00af3db… wyoung 169 best delegated to people skilled in their creation. Normal Git users are
00af3db… wyoung 170 not expected to build Git from source and install it themselves.
00af3db… wyoung 171
c7afd68… wyoung 172 Fossil is a single self-contained stand-alone executable which
c7afd68… wyoung 173 depends only on common platform libraries in its default configuration.
c7afd68… wyoung 174 To install one of [https://fossil-scm.org/home/uv/download.html | our
c7afd68… wyoung 175 precompiled binaries], unpack the executable from the archive and put it
c7afd68… wyoung 176 somewhere in your <tt>PATH</tt>. To uninstall it, delete the executable.
c7afd68… wyoung 177
c7afd68… wyoung 178 This policy is particularly useful when running Fossil inside a
c7afd68… wyoung 179 restrictive container, anything from [./chroot.md | classic chroot
c7afd68… wyoung 180 jails] to modern [https://en.wikipedia.org/wiki/OS-level_virtualization
c7afd68… wyoung 181 | OS-level virtualization mechanisms] such as
da545c9… wyoung 182 [https://en.wikipedia.org/wiki/Docker_(software) | Docker].
b95abfd… wyoung 183 Our [./containers.md | stock container image] is under 11&nbsp;MB when
b95abfd… wyoung 184 uncompressed and running because it contains nothing but a single
283b1a4… wyoung 185 statically-linked binary.
283b1a4… wyoung 186
b95abfd… wyoung 187 If you build a dynamically linked binary instead, a Linux
b95abfd… wyoung 188 x86_64 build of Fossil drops to under 5&nbsp;MB on-disk, stripped.
b95abfd… wyoung 189 It will depend only on widespread
283b1a4… wyoung 190 platform libraries with stable ABIs such as glibc, zlib, and openssl.
283b1a4… wyoung 191
b95abfd… wyoung 192 Much the same is true on Windows, where our precompiled static binaries
b95abfd… wyoung 193 are distributed inside a ZIP archive containing "<tt>fossil.exe</tt>"
b95abfd… wyoung 194 and not a thing else, with a size on-par that of the Linux container
b95abfd… wyoung 195 build. There is no "<tt>setup.exe</tt>" to run; just copy it into your
b95abfd… wyoung 196 <tt>%PATH%</tt>.
358d7d8… drh 197
358d7d8… drh 198 Fossil is easy to build from sources. Just run
358d7d8… drh 199 "<tt>./configure && make</tt>" on POSIX systems and
358d7d8… drh 200 "<tt>nmake /f Makefile.msc</tt>" on Windows.
358d7d8… drh 201
b95abfd… wyoung 202 Git, by contrast, takes 25&nbsp;MiB on Ubuntu 26.04 across 940 files.
b95abfd… wyoung 203 That doesn't count platform facilities like the POSIX shell and script
b95abfd… wyoung 204 interpreters its full feature set requires. A fairer comparison to
b95abfd… wyoung 205 Fossil's single static binary container is the Docker Hardened Image for
b95abfd… wyoung 206 [https://hub.docker.com/hardened-images/catalog/dhi/git |Git 2.x on
b95abfd… wyoung 207 Alpine], which presently weighs in at 36.3 megs unpacked and 607 files,
b95abfd… wyoung 208 if you count all the <tt>busybox</tt> symlinks which would otherwise be
b95abfd… wyoung 209 separate binaries on a more traditional Linux system. Worst of all are
b95abfd… wyoung 210 the "Git for Windows" packages where they end up needing to ship a large
b95abfd… wyoung 211 yet nerfed Linux-like userland to support Git's many loosely coupled
b95abfd… wyoung 212 pieces, approaching a hundred megs and thousands of files.
5c24bee… wyoung 213
5c24bee… wyoung 214 Some say that Git more closely adheres to the Unix philosophy,
5c24bee… wyoung 215 summarized as "many small tools, loosely joined," but we have many
5c24bee… wyoung 216 examples of other successful Unix software that violates that principle
5c24bee… wyoung 217 to good effect, from Apache to Python to ZFS. We can infer from that
5c24bee… wyoung 218 that this is not an absolute principle of good software design.
5c24bee… wyoung 219 Sometimes "many features, tightly-coupled" works better. What actually
5c24bee… wyoung 220 matters is effectiveness and efficiency. We believe Fossil achieves
5c24bee… wyoung 221 this.
5c24bee… wyoung 222
9dcb3de… wyoung 223 The above size comparisons aren't apples-to-apples anyway. We've
9dcb3de… wyoung 224 compared the size of Fossil with all of its [#features | many built-in
b95abfd… wyoung 225 features] to a relatively bare-bones Git installation. You must add a
b95abfd… wyoung 226 lot of third-party software to Git to give it a Fossil-equivalent
b95abfd… wyoung 227 feature set.
b95abfd… wyoung 228
b95abfd… wyoung 229 Consider [https://about.gitlab.com/|GitLab], which wraps Git in enough
b95abfd… wyoung 230 features to bring it to a rough (very rough) parity with Fossil. While
b95abfd… wyoung 231 it is certainly ahead in some areas — automation comes to mind — it must
b95abfd… wyoung 232 be noted that GitLab's own forums are on Discourse, not self-hosted as
b95abfd… wyoung 233 with Fossil. You may then argue that Discourse is superior to the Fossil
b95abfd… wyoung 234 forum feature, but this merely brings us back to another of Fossil's
b95abfd… wyoung 235 advantages: when the posts are part of the repo, you can migrate your
b95abfd… wyoung 236 entire project to another host merely by standing that repo back up on
b95abfd… wyoung 237 other hardware. Choosing to assemble your project hosting from multiple
b95abfd… wyoung 238 pieces requires each to have their own backups, their own management
b95abfd… wyoung 239 processes, and their own migration strategies.
b95abfd… wyoung 240
b95abfd… wyoung 241 Even then, these disparate services do not cooperate at the same level
b95abfd… wyoung 242 as in Fossil, where the ability to have a forum post linking to a wiki
b95abfd… wyoung 243 article linking to a trouble ticket linking to a commit falls out of the
b95abfd… wyoung 244 model nearly for free. These are all internal links, mind, potentially
b95abfd… wyoung 245 using nothing but repository artifact hashes, all backed by SQLite's
b95abfd… wyoung 246 referential integrity. With something like GitLab, its "internal
b95abfd… wyoung 247 references" are tacked on after the fact, not Git repo hashes at all,
b95abfd… wyoung 248 and when it comes to external services like Discourse, history tells us
b95abfd… wyoung 249 you're storing up tech debt which will come due at some future point in
b95abfd… wyoung 250 the form of piles of broken links when one piece or the other needs
b95abfd… wyoung 251 changing out.
b95abfd… wyoung 252
b95abfd… wyoung 253 Furthermore, GitLab is far more resource hungry even in its
b95abfd… wyoung 254 [https://docs.gitlab.com/omnibus/settings/memory_constrained_envs/ |
b95abfd… wyoung 255 minimal configuration], hence more costly to run than the equivalent
b95abfd… wyoung 256 Fossil setup. [https://hub.docker.com/r/gitlab/gitlab-ce/ | The
b95abfd… wyoung 257 official GitLab Community Edition container] currently clocks in at
b95abfd… wyoung 258 3.44 GiB, independent of add-ons like Discourse. You can expect it to
b95abfd… wyoung 259 cost around 8× as much to host it on a cloud service. Even pared down
b95abfd… wyoung 260 to the minimum, there remain the consequences from the difference in
b95abfd… wyoung 261 basic technology choices: Ruby and PostgreSQL vs C and SQLite.
41b3491… drh 262
41b3491… drh 263 The Fossil project itself is [./selfhost.wiki|hosted on a small and
41b3491… drh 264 inexpensive VPS]. A bare-bones $5/month VPS or a
41b3491… drh 265 spare Raspberry Pi is sufficient to run a full-up project
f5ab488… drh 266 site, complete with tickets, wiki, chat, and forum, in addition to
41b3491… drh 267 being a code repository.
41b3491… drh 268
358d7d8… drh 269 <h3 id="durable" name="database">2.3 Query Language</h3>
fd99012… wyoung 270
fd99012… wyoung 271 The baseline data structures for Fossil and Git are the same, modulo
e299892… wyoung 272 formatting details. Both systems manage a
e299892… wyoung 273 [https://en.wikipedia.org/wiki/Directed_acyclic_graph | directed acyclic
e299892… wyoung 274 graph] (DAG) of [https://en.wikipedia.org/wiki/Merkle_tree | Merkle
1ddb400… wyoung 275 tree] structured check-in objects.
e299892… wyoung 276 Check-ins are identified by a cryptographic hash of the check-in
358d7d8… drh 277 contents, and each check-in refers to its parent via the parent's hash.
e299892… wyoung 278
e299892… wyoung 279 The difference is that Git stores its objects as individual files in the
358d7d8… drh 280 <tt>.git</tt> folder or compressed into bespoke key/value
e299892… wyoung 281 [https://git-scm.com/book/en/v2/Git-Internals-Packfiles|pack-files],
e299892… wyoung 282 whereas Fossil stores its objects in a [https://www.sqlite.org/|SQLite]
358d7d8… drh 283 database file which provides ACID transactions and a high-level query
358d7d8… drh 284 language.
939136a… wyoung 285
939136a… wyoung 286 This difference is more than an implementation detail; it has important
e299892… wyoung 287 practical consequences.
e299892… wyoung 288
939136a… wyoung 289 One notable example is that it is difficult to find the descendants
358d7d8… drh 290 of check-ins in Git.
358d7d8… drh 291 One can easily locate the ancestors of a particular Git check-in
939136a… wyoung 292 by following the pointers embedded in the check-in object, but
939136a… wyoung 293 going the other direction is difficult enough
939136a… wyoung 294 that neither native Git nor the big "forge" facilities
939136a… wyoung 295 like GitHub and GitLab provide this capability short of crawling the
939136a… wyoung 296 [https://www.git-scm.com/docs/git-log|commit log]. In Fossil,
939136a… wyoung 297 we can find descendants using a simple SQL query, which then allows
939136a… wyoung 298 us to see [/timeline?df=release&y=ci|all check-ins since the last release],
939136a… wyoung 299 as but one example.
939136a… wyoung 300 Git lets you see "what came before," but Fossil makes it just as
939136a… wyoung 301 easy to also see "what came after."
fd99012… wyoung 302
fd99012… wyoung 303 Leaf check-ins in Git that lack a "ref" become "detached," making them
cd989fe… wyoung 304 difficult to locate and subject to garbage collection. This
788db46… stephan 305 [https://stackoverflow.com/q/3965676 | detached head
358d7d8… drh 306 state] problem has caused grief for
939136a… wyoung 307 [https://www.google.com/search?q=git+detached+head+state |
939136a… wyoung 308 untold millions of Git users]. With
e299892… wyoung 309 Fossil, detached heads are simply impossible because we can always find
358d7d8… drh 310 our way back into the Merkle tree using one or more of the relations
358d7d8… drh 311 in the SQL database.
358d7d8… drh 312
358d7d8… drh 313 The SQL query capabilities of Fossil make it easier to track the
358d7d8… drh 314 changes for one particular file within a project. For example,
358d7d8… drh 315 you can easily find
358d7d8… drh 316 [/finfo/www/fossil-v-git.wiki|the complete edit history of this one document],
358d7d8… drh 317 or even
358d7d8… drh 318 [/finfo/www/fossil-v-git.wiki?ubg|the same history color-coded by committer],
939136a… wyoung 319 Both come down to simple SQL queries in Fossil, with procedural code
358d7d8… drh 320 only being used to format the result for display.
358d7d8… drh 321 The same result could be obtained from Git, but because the data is
358d7d8… drh 322 in a key/value store, much more procedural code has to be written to
939136a… wyoung 323 walk the data and compute the result.
358d7d8… drh 324
358d7d8… drh 325 The ease of querying Fossil data using SQL means that status or
358d7d8… drh 326 history information about the project under management is easier
939136a… wyoung 327 to obtain, hence more likely to happen, giving its developers better
939136a… wyoung 328 situational awareness.
358d7d8… drh 329 Fossil reports tend to be more detailed and useful.
e28c25e… wyoung 330 Compare [/timeline?c=6df7a853ec16865b|this Fossil timeline]
e28c25e… wyoung 331 to
9f135f2… wyoung 332 [https://github.com/drhsqlite/fossil-mirror/commits/master?after=f720c106d297ca1f61bccb30c5c191b88a626d01+34 |
939136a… wyoung 333 its closest equivalent in the GitHub mirror]. Judge for yourself: which of those
358d7d8… drh 334 reports is more useful to a developer trying to understand what happened?
64a33a6… wyoung 335
64a33a6… wyoung 336 <h3 id="portable">2.4 Portable</h3>
64a33a6… wyoung 337
64a33a6… wyoung 338 Fossil is largely written in ISO C, almost purely conforming to the
64a33a6… wyoung 339 original 1989 standard. We make very little use of
4b574be… wyoung 340 [https://en.wikipedia.org/wiki/C99|C99], and we do not knowingly make
4b574be… wyoung 341 any use of
64a33a6… wyoung 342 [https://en.wikipedia.org/wiki/C11_(C_standard_revision)|C11]. Fossil
4b574be… wyoung 343 does call POSIX and Windows APIs where necessary, but it's about
64a33a6… wyoung 344 as portable as you can ask given that ISO C doesn't define all of the
64a33a6… wyoung 345 facilities Fossil needs to do its thing. (Network sockets, file locking,
64a33a6… wyoung 346 etc.) There are certainly well-known platforms Fossil hasn't been ported
64a33a6… wyoung 347 to yet, but that's most likely due to lack of interest rather than
64a33a6… wyoung 348 inherent difficulties in doing the port. We believe the most stringent
64a33a6… wyoung 349 limit on its portability is that it assumes at least a 32-bit CPU and
b95abfd… wyoung 350 several megs of flat-addressed memory.³ Fossil isn't quite as
64a33a6… wyoung 351 [https://www.sqlite.org/custombuild.html|portable as SQLite], but it's
64a33a6… wyoung 352 close.
64a33a6… wyoung 353
4b574be… wyoung 354 Over half of the C code in Fossil is actually an embedded copy of the
64a33a6… wyoung 355 current version of SQLite. Much of what is Fossil-specific after you set
64a33a6… wyoung 356 SQLite itself aside is SQL code calling into SQLite. The number of lines
64a33a6… wyoung 357 of SQL code in Fossil isn't large by percentage, but since SQL is such
64a33a6… wyoung 358 an expressive, declarative language, it has an outsized contribution to
64a33a6… wyoung 359 Fossil's user-visible functionality.
64a33a6… wyoung 360
21c7f1f… wyoung 361 Fossil isn't entirely C and SQL code. Its web UI [./javascript.md |
21c7f1f… wyoung 362 uses JavaScript where
21c7f1f… wyoung 363 necessary]. The server-side
0996347… wyoung 364 UI scripting uses a custom minimal
4b574be… wyoung 365 [https://en.wikipedia.org/wiki/Tcl|Tcl] dialect called
56e59a3… stephan 366 [./th1.md|TH1], which is
0996347… wyoung 367 embedded into Fossil itself. Fossil's build system and test suite are
b95abfd… wyoung 368 largely based on Tcl.⁴ All of this is quite portable.
4b574be… wyoung 369
4b574be… wyoung 370 About half of Git's code is POSIX C, and about a third is POSIX shell
4b574be… wyoung 371 code. This is largely why the so-called "Git for Windows" distributions
4b574be… wyoung 372 (both [https://git-scm.com/download/win|first-party] and
64a33a6… wyoung 373 [https://gitforwindows.org/|third-party]) are actually an
aacd371… danield 374 [https://www.msys2.org/wiki/Home/|MSYS POSIX portability environment] bundled
64a33a6… wyoung 375 with all of the Git stuff, because it would be too painful to port Git
64a33a6… wyoung 376 natively to Windows. Git is a foreign citizen on Windows, speaking to it
b95abfd… wyoung 377 only through a translator.⁵
64a33a6… wyoung 378
64a33a6… wyoung 379 While Fossil does lean toward POSIX norms when given a choice — LF-only
64a33a6… wyoung 380 line endings are treated as first-class citizens over CR+LF, for example
64a33a6… wyoung 381 — the Windows build of Fossil is truly native.
64a33a6… wyoung 382
64a33a6… wyoung 383 The third-party extensions to Git tend to follow this same pattern.
f8baa04… danield 384 [https://docs.gitlab.com/ee/install/install_methods.html#microsoft-windows |
f8baa04… danield 385 GitLab isn't portable to Windows at all],
64a33a6… wyoung 386 for example. For that matter, GitLab isn't even officially supported on
4b574be… wyoung 387 macOS, the BSDs, or uncommon Linuxes! We have many users who regularly
4b574be… wyoung 388 build and run Fossil on all of these systems.
64a33a6… wyoung 389
64a33a6… wyoung 390
64a33a6… wyoung 391 <h3 id="vs-linux">2.5 Linux vs. SQLite</h3>
69ec89b… wyoung 392
69ec89b… wyoung 393 Fossil and Git promote different development styles because each one was
0297ae7… wyoung 394 specifically designed to support the creator's main software
69ec89b… wyoung 395 development project: [https://en.wikipedia.org/wiki/Linus_Torvalds|Linus
69ec89b… wyoung 396 Torvalds] designed Git to support development of
69ec89b… wyoung 397 [https://www.kernel.org/|the Linux kernel], and
69ec89b… wyoung 398 [https://en.wikipedia.org/wiki/D._Richard_Hipp|D. Richard Hipp] designed
69ec89b… wyoung 399 Fossil to support the development of [https://sqlite.org/|SQLite].
69ec89b… wyoung 400 Both projects must rank high on any objective list of "most
69ec89b… wyoung 401 important FOSS projects," yet these two projects are almost entirely unlike
466d74c… wyoung 402 one another, so it is natural that the DVCSes created to support these
466d74c… wyoung 403 projects also differ in many ways.
69ec89b… wyoung 404
e9628d7… wyoung 405 In the following sections, we will explain how four key differences
466d74c… wyoung 406 between the Linux and SQLite software development projects dictated the
466d74c… wyoung 407 design of each DVCS's low-friction usage path.
69ec89b… wyoung 408
69ec89b… wyoung 409 When deciding between these two DVCSes, you should ask yourself, "Is my
69ec89b… wyoung 410 project more like Linux or more like SQLite?"
69ec89b… wyoung 411
69ec89b… wyoung 412
64a33a6… wyoung 413 <h4 id="devorg">2.5.1 Development Organization</h4>
69ec89b… wyoung 414
69ec89b… wyoung 415 Eric S. Raymond's seminal essay-turned-book
69ec89b… wyoung 416 "[https://en.wikipedia.org/wiki/The_Cathedral_and_the_Bazaar|The
69ec89b… wyoung 417 Cathedral and the Bazaar]" details the two major development
69ec89b… wyoung 418 organization styles found in
69ec89b… wyoung 419 [https://en.wikipedia.org/wiki/Free_and_open-source_software|FOSS]
69ec89b… wyoung 420 projects. As it happens, Linux and SQLite fall on opposite sides of this
69ec89b… wyoung 421 dichotomy. Differing development organization styles dictate a different
69ec89b… wyoung 422 design and low-friction usage path in the tools created to support each
69ec89b… wyoung 423 project.
69ec89b… wyoung 424
69ec89b… wyoung 425 Git promotes the Linux kernel's bazaar development style, in which a
69ec89b… wyoung 426 loosely-associated mass of developers contribute their work through
69ec89b… wyoung 427 [https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows#_dictator_and_lieutenants_workflow|a
69ec89b… wyoung 428 hierarchy of lieutenants] who manage and clean up these contributions
0996347… wyoung 429 for consideration by Linus Torvalds, who has the power to cherry-pick
69ec89b… wyoung 430 individual contributions into his version of the Linux kernel. Git
69ec89b… wyoung 431 allows an anonymous developer to rebase and push specific locally-named
69ec89b… wyoung 432 private branches, so that a Git repo clone often isn't really a clone at
69ec89b… wyoung 433 all: it may have an arbitrary number of differences relative to the
69ec89b… wyoung 434 repository it originally cloned from. Git encourages siloed development.
69ec89b… wyoung 435 Select work in a developer's local repository may remain private
69ec89b… wyoung 436 indefinitely.
69ec89b… wyoung 437
69ec89b… wyoung 438 All of this is exactly what one wants when doing bazaar-style
69ec89b… wyoung 439 development.
69ec89b… wyoung 440
69ec89b… wyoung 441 Fossil's normal mode of operation differs on every one of these points,
69ec89b… wyoung 442 with the specific designed-in goal of promoting SQLite's cathedral
69ec89b… wyoung 443 development model:
69ec89b… wyoung 444
1fd407f… wyoung 445 * <b>Personal engagement:</b> SQLite's developers know each
1fd407f… wyoung 446 other by name and work together daily on the project.
1fd407f… wyoung 447
1fd407f… wyoung 448 * <b>Trust over hierarchy:</b> SQLite's developers check
1fd407f… wyoung 449 changes into their local repository, and these are immediately and
1fd407f… wyoung 450 automatically synchronized up to the central repository; there is no
1fd407f… wyoung 451 "[https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows#_dictator_and_lieutenants_workflow|dictator
1fd407f… wyoung 452 and lieutenants]" hierarchy as with Linux kernel contributions. D.
1fd407f… wyoung 453 Richard Hipp rarely overrides decisions made by those he has trusted
1fd407f… wyoung 454 with commit access on his repositories. Fossil allows you to give
1fd407f… wyoung 455 [./caps/admin-v-setup.md|some users] more power over what
1fd407f… wyoung 456 they can do with the repository, but Fossil [./caps/index.md#ucap |
1fd407f… wyoung 457 only loosely supports] the enforcement of a development organization's
1fd407f… wyoung 458 social and power hierarchies. Fossil is a great fit for
1fd407f… wyoung 459 [https://en.wikipedia.org/wiki/Flat_organization|flat
1fd407f… wyoung 460 organizations].
1fd407f… wyoung 461
1fd407f… wyoung 462 * <b>No easy drive-by contributions:</b> Git
1fd407f… wyoung 463 [https://www.git-scm.com/docs/git-request-pull|pull requests] offer
1fd407f… wyoung 464 a low-friction path to accepting
1fd407f… wyoung 465 [https://www.jonobacon.com/2012/07/25/building-strong-community-structural-integrity/|drive-by
1fd407f… wyoung 466 contributions]. Fossil's closest equivalents are its unique
c64f28d… drh 467 [/help/bundle|bundle] and [/help/patch|patch] features, which require higher engagement
b95abfd… wyoung 468 than firing off a PR.⁶ This difference comes directly from the
1fd407f… wyoung 469 initial designed purpose for each tool: the SQLite project doesn't
1fd407f… wyoung 470 accept outside contributions from previously-unknown developers, but
1fd407f… wyoung 471 the Linux kernel does.
1fd407f… wyoung 472
1fd407f… wyoung 473 * <b>No rebasing:</b> When your local repo clone syncs changes
1fd407f… wyoung 474 up to its parent, those changes are sent exactly as they were
1fd407f… wyoung 475 committed locally. [#history|There is no rebasing mechanism in
1fd407f… wyoung 476 Fossil, on purpose.]
1fd407f… wyoung 477
1fd407f… wyoung 478 * <b>Sync over push:</b> Explicit pushes are uncommon in
1fd407f… wyoung 479 Fossil-based projects: the default is to rely on
c64f28d… drh 480 [/help/autosync|autosync mode] instead, in which each commit
1fd407f… wyoung 481 syncs immediately to its parent repository. This is a mode so you
1fd407f… wyoung 482 can turn it off temporarily when needed, such as when working
1fd407f… wyoung 483 offline. Fossil is still a truly distributed version control system;
1fd407f… wyoung 484 it's just that its starting default is to assume you're rarely out
1fd407f… wyoung 485 of communication with the parent repo.
1fd407f… wyoung 486 <br><br>
1fd407f… wyoung 487 This is not merely a reflection of modern always-connected computing
1fd407f… wyoung 488 environments. It is a conscious decision in direct support of
1fd407f… wyoung 489 SQLite's cathedral development model: we don't want developers going
1fd407f… wyoung 490 dark, then showing up weeks later with a massive bolus of changes
1fd407f… wyoung 491 for us to integrate all at once.
1fd407f… wyoung 492 [https://en.wikipedia.org/wiki/Jim_McCarthy_(author)|Jim McCarthy]
1fd407f… wyoung 493 put it well in his book on software project management,
1fd407f… wyoung 494 <i>[https://www.amazon.com/dp/0735623198/|Dynamics of Software
1fd407f… wyoung 495 Development]</i>: "[https://www.youtube.com/watch?v=oY6BCHqEbyc|Beware
1fd407f… wyoung 496 of a guy in a room]."
1fd407f… wyoung 497
1fd407f… wyoung 498 * <b>Branch names sync:</b> Unlike in Git, branch names in
1fd407f… wyoung 499 Fossil are not purely local labels. They sync along with everything
1fd407f… wyoung 500 else, so everyone sees the same set of branch names. Fossil's design
1fd407f… wyoung 501 choice here is a direct reflection of the Linux vs. SQLite project
1fd407f… wyoung 502 outlook: SQLite's developers collaborate closely on a single
1fd407f… wyoung 503 coherent project, whereas Linux's developers go off on tangents and
1fd407f… wyoung 504 occasionally send selected change sets to each other.
1fd407f… wyoung 505
1fd407f… wyoung 506 * <b>Private branches are rare:</b>
1fd407f… wyoung 507 [/doc/trunk/www/private.wiki|Private branches exist in Fossil], but
1fd407f… wyoung 508 they're normally used to handle rare exception cases, whereas in
1fd407f… wyoung 509 many Git projects, they're part of the straight-line development
1fd407f… wyoung 510 process.
1fd407f… wyoung 511
1fd407f… wyoung 512 * <b>Identical clones:</b> Fossil's autosync system tries to
1fd407f… wyoung 513 keep each local clone identical to the repository it cloned
1fd407f… wyoung 514 from.
69ec89b… wyoung 515
69ec89b… wyoung 516 Where Git encourages siloed development, Fossil fights against it.
69e6418… wyoung 517 Fossil places a lot of emphasis on synchronizing everyone's work and on
69e6418… wyoung 518 reporting on the state of the project and the work of its developers, so
69e6418… wyoung 519 that everyone — especially the project leader — can maintain a better
69e6418… wyoung 520 mental picture of what is happening, leading to better situational
69e6418… wyoung 521 awareness.
c0269e3… wyoung 522
a59af25… danield 523 By contrast, "…[https://docs.github.com/en/get-started/quickstart/contributing-to-projects|forking is
765b215… wyoung 524 at the core of social coding at GitHub]". As of June 2026,
765b215… wyoung 525 [https://github.com/search?q=is:public|Github hosts 324 million distinct
c0269e3… wyoung 526 software projects], most of which were created by forking a
c0269e3… wyoung 527 previously-existing project. Since this is
a90f60c… wyoung 528 [https://www.griddynamics.com/blog/number-software-developers-world |
a90f60c… wyoung 529 ~11× the number of developers in the world], it beggars belief that
c0269e3… wyoung 530 most of these forks are still under active development. The vast bulk
c0269e3… wyoung 531 of these must be abandoned one-off efforts. This is part of the nature
c0269e3… wyoung 532 of bazaar style development.
b0f2a48… wyoung 533
b0f2a48… wyoung 534 You can think about this difference in terms of
b0f2a48… wyoung 535 [https://en.wikipedia.org/wiki/Feedback | feedback loop size], which we
b0f2a48… wyoung 536 know from the mathematics of
b0f2a48… wyoung 537 [https://en.wikipedia.org/wiki/Control_theory | control theory] to
b0f2a48… wyoung 538 directly affect the speed at which any system can safely make changes.
b0f2a48… wyoung 539 The larger the feedback loop, the slower the whole system must run in
b0f2a48… wyoung 540 order to avoid loss of control. The same concept shows up in other
b0f2a48… wyoung 541 contexts, such as in the [https://en.wikipedia.org/wiki/OODA_loop | OODA
c00b6a4… wyoung 542 loop] concept.
b0f2a48… wyoung 543 Committing your changes to private branches in order to delay a public
b0f2a48… wyoung 544 push to the parent repo increases the size of your collaborators'
b0f2a48… wyoung 545 control loops, either causing them to slow their work in order to safely
e28c25e… wyoung 546 react to your work, or to over-correct in response to each change.
64a33a6… wyoung 547
69ec89b… wyoung 548 Each DVCS can be used in the opposite style, but doing so works against
69ec89b… wyoung 549 their low-friction paths.
69ec89b… wyoung 550
8452627… wyoung 551
64a33a6… wyoung 552 <h4 id="scale">2.5.2 Scale</h4>
69ec89b… wyoung 553
69ec89b… wyoung 554 The Linux kernel has a far bigger developer community than that of
69ec89b… wyoung 555 SQLite: there are thousands and thousands of contributors to Linux, most
e28c25e… wyoung 556 of whom do not know each other's names. These thousands are responsible
21c98b4… wyoung 557 for producing roughly 73× more code than is in SQLite. (32.0
21c98b4… wyoung 558 [https://en.wikipedia.org/wiki/Source_lines_of_code|MLOC] vs. 0.44 MLOC
e4beb0b… wyoung 559 according to [https://github.com/boyter/scc | scc].) The Linux
69ec89b… wyoung 560 kernel and its development process were already uncommonly large back in
69ec89b… wyoung 561 2005 when Git was designed, specifically to support the consequences of
69ec89b… wyoung 562 having such a large set of developers working on such a large code base.
69ec89b… wyoung 563
21c98b4… wyoung 564 95% of the code in SQLite comes from just six programmers, and 62% of
69ec89b… wyoung 565 it is from the lead developer alone. The SQLite developers know each
69ec89b… wyoung 566 other well and interact daily. Fossil was designed for this development
0e0d76e… wyoung 567 model.
0e0d76e… wyoung 568
5171e59… wyoung 569 When choosing your DVCS, we think you should ask yourself whether the
5171e59… wyoung 570 scale of your software configuration management problems is closer to
5171e59… wyoung 571 those Linus Torvalds designed Git to cope with or whether your work's
5171e59… wyoung 572 scale is closer to that of SQLite, for which D. Richard Hipp designed
5171e59… wyoung 573 Fossil. An [https://en.wikipedia.org/wiki/Impact_wrench|automotive air
5171e59… wyoung 574 impact wrench] running at 8000 RPM driving an M8 socket-cap bolt at 16
5171e59… wyoung 575 cm/s is not the best way to hang a picture on the living room wall.
5171e59… wyoung 576
5171e59… wyoung 577 Fossil works well for projects several times the size of SQLite,
ab48b9d… wyoung 578 [https://core.tcl-lang.org/tcl/ | such as Tcl], with a repository over
5171e59… wyoung 579 twice the size and with many more core committers.
b3080a2… drh 580
b3080a2… drh 581
b3080a2… drh 582 <h4 id="branches">2.5.3 Individual Branches vs. The Entire Change History</h4>
bcea529… drh 583
bcea529… drh 584 Both Fossil and Git store history as a directed acyclic graph (DAG)
fd99012… wyoung 585 of changes, but Git tends to focus more on individual branches of
bcea529… drh 586 the DAG, whereas Fossil puts more emphasis on the entire DAG.
bcea529… drh 587
03f2393… wyoung 588 While a common usage pattern in Git is to only synchronize
03f2393… wyoung 589 a single branch — <tt>git pull upstream feature/branch</tt> — instead
4146f2d… wyoung 590 of all refs, Fossil does not give you a choice; it
03f2393… wyoung 591 syncs the entire DAG or nothing. Git commands,
fd99012… wyoung 592 GitHub, and GitLab tend to show only a single branch at
fd99012… wyoung 593 a time, whereas Fossil usually shows all parallel branches at
bcea529… drh 594 once. Git has commands like "rebase" that help keep all relevant
bcea529… drh 595 changes on a single branch, whereas Fossil encourages a style of
79c2cb0… wyoung 596 many concurrent branches constantly springing into existence,
bcea529… drh 597 undergoing active development in parallel for a few days or weeks, then
bcea529… drh 598 merging back into the main line and disappearing.
bcea529… drh 599
bcea529… drh 600 This difference in emphasis arises from the different purposes of
4146f2d… wyoung 601 the two systems. Git's focus on individual branches
bcea529… drh 602 is exactly what you want for a highly-distributed bazaar-style project
bcea529… drh 603 such as Linux. Linus Torvalds does not want to see every check-in
e28c25e… wyoung 604 by every contributor to Linux: such extreme visibility does not scale
e28c25e… wyoung 605 well. Contrast Fossil, which was written for the cathedral-style SQLite project
e28c25e… wyoung 606 and its handful of active committers. Seeing all
bcea529… drh 607 changes on all branches all at once helps keep the whole team
fd1282e… drh 608 up-to-date with what everybody else is doing, resulting in a more
bcea529… drh 609 tightly focused and cohesive implementation.
bcea529… drh 610
69ec89b… wyoung 611
64a33a6… wyoung 612 <h3 id="checkouts">2.6 One vs. Many Check-outs per Repository</h3>
64a33a6… wyoung 613
f6e04cc… wyoung 614 Because Git commingles the repository data with the initial checkout of
f6e04cc… wyoung 615 that repository, the default mode of operation in Git is to stick to that
f6e04cc… wyoung 616 single work/repo tree, even when that's a shortsighted way of working.
10a57ce… wyoung 617
c0654b1… brickviking 618 Fossil doesn't work that way. A Fossil repository is an SQLite database
f6e04cc… wyoung 619 file which is normally stored outside the working checkout directory. You can
c64f28d… drh 620 [/help/open | open] a Fossil repository any number of times into
10a57ce… wyoung 621 any number of working directories. A common usage pattern is to have one
10a57ce… wyoung 622 working directory per active working branch, so that switching branches
10a57ce… wyoung 623 is done with a <tt>cd</tt> command rather than by checking out the
10a57ce… wyoung 624 branches successively in a single working directory.
10a57ce… wyoung 625
f6e04cc… wyoung 626 Fossil does allow you to switch branches within a working checkout
f6e04cc… wyoung 627 directory, and this is also often done. It is simply that there is no
f6e04cc… wyoung 628 inherent penalty to either choice in Fossil as there is in Git. The
f6e04cc… wyoung 629 standard advice is to use a switch-in-place workflow in Fossil when
f6e04cc… wyoung 630 the disturbance from switching branches is small, and to use multiple
f6e04cc… wyoung 631 checkouts when you have long-lived working branches that are different
f6e04cc… wyoung 632 enough that switching in place is disruptive.
f6e04cc… wyoung 633
2bfb72a… wyoung 634 While you can [./gitusers.md#worktree | use Git in the Fossil style] via
2bfb72a… wyoung 635 its worktree feature, tutorials continue to teach the style of having
2bfb72a… wyoung 636 one working directory only. Git can even fight you on this, as when
2bfb72a… wyoung 637 working with a forked repository; it is best to have independent clones
2bfb72a… wyoung 638 of the upstream and your fork, to allow separate "remote" lists and
2bfb72a… wyoung 639 such. This can result in two working directories but each having a
2bfb72a… wyoung 640 captive repo clone each, which isn't in the spirit of <tt>git
2bfb72a… wyoung 641 worktree</tt> at all. Yet, it beats the alternative, which then
2bfb72a… wyoung 642 highlights a gap in the model of diverging and re-converging forks.
2bfb72a… wyoung 643 Ideally, Git would let you create one of these forks as a worktree while
2bfb72a… wyoung 644 maintaining a strong separation between your fork and the upstream repo,
2bfb72a… wyoung 645 but it ends up being too much hassle to bother with.
2bfb72a… wyoung 646
2bfb72a… wyoung 647 There are
10a57ce… wyoung 648 [https://duckduckgo.com/?q=git+worktree+problem | several known
2bfb72a… wyoung 649 problems] with the single worktree style, ones which don't happen in
2bfb72a… wyoung 650 Fossil because of the clear [./ckout-workflows.md | separation] between
2bfb72a… wyoung 651 a Fossil repository and each working directory.
10a57ce… wyoung 652
f6e04cc… wyoung 653 This distinction matters because switching branches inside a single working directory loses local context
10a57ce… wyoung 654 on each switch.
10a57ce… wyoung 655
10a57ce… wyoung 656 For instance, in any software project where the runnable program must be
10a57ce… wyoung 657 built from source files, you invalidate build objects on each switch,
f6e04cc… wyoung 658 artificially increasing the time required to switch versions. Most obviously, this
10a57ce… wyoung 659 affects software written in statically-compiled programming languages
10a57ce… wyoung 660 such as C, Java, and Haskell, but it can even affect programs written in
f6e04cc… wyoung 661 dynamic languages like JavaScript. A typical
10a57ce… wyoung 662 [https://en.wikipedia.org/wiki/Single-page_application | SPA] build
f6e04cc… wyoung 663 process involves several passes: [http://browserify.org/ | Browserify] to convert
f6e04cc… wyoung 664 [https://nodejs.org/ | Node] packages so they'll run in a web browser,
f6e04cc… wyoung 665 [https://sass-lang.com | SASS] to CSS translation,
f6e04cc… wyoung 666 transpilation of [https://www.typescriptlang.org | Typescript] to JavaScript,
f6e04cc… wyoung 667 [https://github.com/mishoo/UglifyJS | uglification], etc.
f6e04cc… wyoung 668 Once all that processing work is done for a given input
10a57ce… wyoung 669 file in a given working directory, why re-do that work just to switch
f6e04cc… wyoung 670 versions? If most of the files that differ between versions don't change
f6e04cc… wyoung 671 very often, you can save substantial time by switching branches with
f6e04cc… wyoung 672 <tt>cd</tt> rather than swapping versions in-place within a working
f6e04cc… wyoung 673 checkout directory.
10a57ce… wyoung 674
10a57ce… wyoung 675 For another example, you might have an active long-running test grinding
10a57ce… wyoung 676 away in a working directory, then get a call from a customer requiring
10a57ce… wyoung 677 that you switch to a stable branch to answer questions in terms of the
10a57ce… wyoung 678 version that customer is running. You don't want to stop the test in
10a57ce… wyoung 679 order to switch your lone working directory to the stable branch.
10a57ce… wyoung 680
e28c25e… wyoung 681 Disk space is cheap. Having several working directories — each with its
e28c25e… wyoung 682 own local state — makes switching versions cheap and fast.
e28c25e… wyoung 683
e28c25e… wyoung 684 Plus,
f6e04cc… wyoung 685 <tt>cd</tt> is faster to type than <tt>git checkout</tt> or <tt>fossil
f6e04cc… wyoung 686 update</tt>.
64a33a6… wyoung 687
64a33a6… wyoung 688 <h3 id="history">2.7 What you should have done vs. What you actually did</h3>
ca891ab… drh 689
ca891ab… drh 690 Git puts a lot of emphasis on maintaining
ca891ab… drh 691 a "clean" check-in history. Extraneous and experimental branches by
18fc697… wyoung 692 individual developers often never make it into the main repository.
18fc697… wyoung 693 Branches may be rebased before being pushed to make
18fc697… wyoung 694 it appear as if development had been linear, or "squashed" to make it
18fc697… wyoung 695 appear that multiple commits were made as a single commit.
18fc697… wyoung 696 There are [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History |
18fc697… wyoung 697 other history rewriting mechanisms in Git] as well. Git strives to record what
ca891ab… drh 698 the development of a project should have looked like had there been no
ca891ab… drh 699 mistakes.
ca891ab… drh 700
ca891ab… drh 701 Fossil, in contrast, puts more emphasis on recording exactly what happened,
ca891ab… drh 702 including all of the messy errors, dead-ends, experimental branches, and
ca891ab… drh 703 so forth. One might argue that this
29997f8… wyoung 704 makes the history of a Fossil project "messy," but another point of view
fd99012… wyoung 705 is that this makes the history "accurate." In actual practice, the
e28c25e… wyoung 706 superior reporting tools available in Fossil mean that this incidental mess
ca891ab… drh 707 is not a factor.
ca891ab… drh 708
c64f28d… drh 709 Like Git, Fossil has an [/help/amend|amend command] for modifying
e878d54… wyoung 710 prior commits, but unlike in Git, this works not by replacing data in
e878d54… wyoung 711 the repository, but by adding a correction record to the repository that
e878d54… wyoung 712 affects how later Fossil operations present the corrected data. The old
e878d54… wyoung 713 information is still there in the repository, it is just overridden from
18fc697… wyoung 714 the amendment point forward.
18fc697… wyoung 715
18fc697… wyoung 716 Fossil lacks almost every other history rewriting mechanism listed on
18fc697… wyoung 717 the Git documentation page linked above. [./rebaseharm.md | There is no
18fc697… wyoung 718 rebase] in Fossil, on purpose, thus no way to reorder or copy commits
18fc697… wyoung 719 around in the commit hash tree. There is no commit squashing, dropping,
18fc697… wyoung 720 or interactive patch-based cherry-picking of commit elements in Fossil.
18fc697… wyoung 721 There is nothing like Git's <tt>filter-branch</tt> in Fossil.
18fc697… wyoung 722
18fc697… wyoung 723 The lone exception is deleting commits. Fossil has two methods for doing
18fc697… wyoung 724 that, both of which have stringent limitations, on purpose.
18fc697… wyoung 725
18fc697… wyoung 726 The first is [/doc/trunk/www/shunning.wiki | shunning]. See that
18fc697… wyoung 727 document for details, but briefly, you only get mandatory compliance
18fc697… wyoung 728 for shun requests within a single repository. Shun requests do not
18fc697… wyoung 729 propagate automatically between repository clones. A Fossil repository
18fc697… wyoung 730 administrator can <i>cooperatively</i> pull another repo's shun requests
18fc697… wyoung 731 across a sync boundary, so that two admins can get together and agree to
18fc697… wyoung 732 shun certain committed artifacts, but a person cannot force their local
18fc697… wyoung 733 shun requests into another repo without having admin-level control over
18fc697… wyoung 734 the receiving repo as well. Fossil's shun feature isn't for fixing up
18fc697… wyoung 735 everyday bad commits, it's for dealing with extreme situations: public
18fc697… wyoung 736 commits of secret material, ticket/wiki/forum spam, law enforcement
18fc697… wyoung 737 takedown demands, etc.
18fc697… wyoung 738
c64f28d… drh 739 There is also the experimental [/help/purge | <tt>purge</tt>
18fc697… wyoung 740 command], which differs from shunning in ways that aren't especially
18fc697… wyoung 741 important in the context of this document. At a 30000 foot level, you
18fc697… wyoung 742 can think of purging as useful only when you've turned off Fossil's
18fc697… wyoung 743 autosync feature and want to pluck artifacts out of its hash tree before
18fc697… wyoung 744 they get pushed. In that sense, it's approximately the same as
18fc697… wyoung 745 <tt>git rebase -i, drop</tt>. However, given that Fossil defaults to
18fc697… wyoung 746 having autosync enabled [#devorg | for good reason], the purge command
18fc697… wyoung 747 isn't very useful in practice: once a commit has been pushed into
18fc697… wyoung 748 another repo, shunning is more useful if you need to delete it from
18fc697… wyoung 749 history.
18fc697… wyoung 750
18fc697… wyoung 751 If these accommodations strike you as incoherent with respect to
18fc697… wyoung 752 Fossil's philosophy of durable, unchanging commits, realize that if
18fc697… wyoung 753 shunning and purging were removed from Fossil, you could still remove
18fc697… wyoung 754 artifacts from the repository with SQL <tt>DELETE</tt> statements; the
18fc697… wyoung 755 repository database file is, after all, directly modifiable, being
18fc697… wyoung 756 writable by your user. Where the Fossil philosophy really takes hold is
18fc697… wyoung 757 in making it difficult to violate the integrity of the hash tree.
18fc697… wyoung 758 It's somewhat tangential, but the document [./blockchain.md | "Is Fossil
18fc697… wyoung 759 a Blockchain?"] touches on this and related topics.
e878d54… wyoung 760
e878d54… wyoung 761 One commentator characterized Git as recording history according to
ca891ab… drh 762 the victors, whereas Fossil records history as it actually happened.
ca891ab… drh 763
e5ba457… wyoung 764
e5ba457… wyoung 765 <h3 id="testing">2.8 Test Before Commit</h3>
e5ba457… wyoung 766
e5ba457… wyoung 767 One of the things that falls out of Git's default separation of commit
e5ba457… wyoung 768 from push is that there are several Git sub-commands that jump straight
e5ba457… wyoung 769 to the commit step before a change could possibly be tested. Fossil, by
e5ba457… wyoung 770 contrast, makes the equivalent change to the local working check-out
e5ba457… wyoung 771 only, requiring a separate check-in step to commit the change. This
e5ba457… wyoung 772 design difference falls naturally out of Fossil's default-enabled
18fc697… wyoung 773 autosync feature and its philosophy of [#history | not offering history
18fc697… wyoung 774 rewriting features].
e5ba457… wyoung 775
e5ba457… wyoung 776 The prime example in Git is rebasing: the change happens to the local
e5ba457… wyoung 777 repository immediately if successful, even though you haven't tested the
e5ba457… wyoung 778 change yet. It's possible to argue for such a design in a tool like Git
18fc697… wyoung 779 since it lacks an autosync feature, because you can still test the
18fc697… wyoung 780 change before pushing local changes to the parent repo, but in the
18fc697… wyoung 781 meantime you've made a durable change to your local Git repository. You
18fc697… wyoung 782 must do something drastic like <tt>git reset --hard</tt> to revert that
18fc697… wyoung 783 rebase or rewrite history before pushing it if the rebase causes a
18fc697… wyoung 784 problem. If you push your rebased local repo up to the parent without
18fc697… wyoung 785 testing first, you cannot fix it without violating
e5ba457… wyoung 786 [https://www.atlassian.com/git/tutorials/merging-vs-rebasing#the-golden-rule-of-rebasing
e5ba457… wyoung 787 | the golden rule of rebasing].
e5ba457… wyoung 788
e5ba457… wyoung 789 Lesser examples are the Git <tt>merge</tt>, <tt>cherry-pick</tt>, and
e5ba457… wyoung 790 <tt>revert</tt> commands, all of which apply work from one branch onto
18fc697… wyoung 791 another, and all of which commit their change to the local repository
18fc697… wyoung 792 immediately without giving you
18fc697… wyoung 793 an opportunity to test the change first unless you give the
18fc697… wyoung 794 <tt>--no-commit</tt> option. Otherwise, you're back in the same boat:
18fc697… wyoung 795 reset the local repository or rewrite history to fix things, then maybe
18fc697… wyoung 796 retry.
e5ba457… wyoung 797
e5ba457… wyoung 798 Fossil cannot sensibly work that way because of its default-enabled
18fc697… wyoung 799 autosync feature and its purposeful paucity of commands for modifying
18fc697… wyoung 800 commits, as discussed in [#history | the prior section].
18fc697… wyoung 801
18fc697… wyoung 802 Instead of jumping straight to the commit step, Fossil
e5ba457… wyoung 803 applies the proposed merge to the local working directory only,
e5ba457… wyoung 804 requiring a separate check-in step before the change is committed to the
1ddb400… wyoung 805 repository. This gives you a chance to test the change first,
2cfd125… wyoung 806 either manually or by running your software's automatic tests. (Ideally,
18fc697… wyoung 807 both!) Thus, Fossil doesn't need rebase, squashing,
18fc697… wyoung 808 <tt>reset --hard</tt>, or other Git commit mutating mechanisms.
e5ba457… wyoung 809
18fc697… wyoung 810 Because Fossil requires an explicit commit for a merge, it has the nice
18fc697… wyoung 811 side benefit that it makes you give an explicit commit <i>message</i>
18fc697… wyoung 812 for each merge, whereas Git writes that commit message itself by default
e5ba457… wyoung 813 unless you give the optional <tt>--edit</tt> flag to override it.
e5ba457… wyoung 814
e5ba457… wyoung 815 We don't look at this difference as a workaround in Fossil for autosync,
18fc697… wyoung 816 but instead as a test-first philosophical difference:
18fc697… wyoung 817 <tt>fossil commit</tt> is a <i>commitment</i>. When every commit is
18fc697… wyoung 818 pushed to the parent repo by default, it encourages a working style in
18fc697… wyoung 819 which every commit is tested first. It encourages thinking before
18fc697… wyoung 820 acting. We believe this is an inherently good thing.
e5ba457… wyoung 821
e5ba457… wyoung 822 Incidentally, this is a good example of Git's messy command design.
e5ba457… wyoung 823 These three commands:
e5ba457… wyoung 824
e5ba457… wyoung 825 <pre>
8a1ba49… wyoung 826 $ git merge HASH
8a1ba49… wyoung 827 $ git cherry-pick HASH
8a1ba49… wyoung 828 $ git revert HASH
e5ba457… wyoung 829 </pre>
e5ba457… wyoung 830
e5ba457… wyoung 831 ...are all the same command in Fossil:
e5ba457… wyoung 832
e5ba457… wyoung 833 <pre>
8a1ba49… wyoung 834 $ fossil merge HASH
8a1ba49… wyoung 835 $ fossil merge --cherrypick HASH
8a1ba49… wyoung 836 $ fossil merge --backout HASH
e5ba457… wyoung 837 </pre>
e5ba457… wyoung 838
e5ba457… wyoung 839 If you think about it, they're all the same function: apply work done on
e5ba457… wyoung 840 one branch to another. All that changes between these commands is how
e5ba457… wyoung 841 much work gets applied — just one check-in or a whole branch — and the
e5ba457… wyoung 842 merge direction. This is the sort of thing we mean when we point out
e5ba457… wyoung 843 that Fossil's command interface is simpler than Git's: there are fewer
e5ba457… wyoung 844 concepts to keep track of in your mental model of Fossil's internal
e5ba457… wyoung 845 operation.
e5ba457… wyoung 846
e5ba457… wyoung 847 Fossil's implementation of the feature is also simpler to describe. The
c64f28d… drh 848 brief online help for <tt>[/help/merge | fossil merge]</tt> is
26a96e8… wyoung 849 currently 50 lines long, to which you want to add the ~800 lines of
8f7576b… wyoung 850 [./branching.wiki | the branching document]. The equivalent
8f7576b… wyoung 851 documentation in Git is the aggregation of the man pages for the above
26a96e8… wyoung 852 three commands, which is approaching 1400 lines as of this writing, much of it mutually redundant.
2cfd125… wyoung 853 (e.g. Git's <tt>--edit</tt> and <tt>--no-commit</tt> options get
d887a6d… wyoung 854 described three times, each time differently.) Fossil's
8f7576b… wyoung 855 documentation is not only more concise, it gives a nice split of brief
8f7576b… wyoung 856 online help and full online documentation.
29997f8… wyoung 857
29997f8… wyoung 858
e5ba457… wyoung 859 <h3 id="hash">2.9 Hash Algorithm: SHA-3 vs SHA-2 vs SHA-1</h3>
42b8890… wyoung 860
42b8890… wyoung 861 Fossil started out using 160-bit SHA-1 hashes to identify check-ins,
42b8890… wyoung 862 just as in Git. That changed in early 2017 when news of the
42b8890… wyoung 863 [https://shattered.io/|SHAttered attack] broke, demonstrating that SHA-1
42b8890… wyoung 864 collisions were now practical to create. Two weeks later, the creator of
42b8890… wyoung 865 Fossil delivered a new release allowing a clean migration to
42b8890… wyoung 866 [https://en.wikipedia.org/wiki/SHA-3|256-bit SHA-3] with
42b8890… wyoung 867 [./hashpolicy.wiki|full backwards compatibility] to old SHA-1 based
42b8890… wyoung 868 repositories.
42b8890… wyoung 869
4fdc8db… wyoung 870 In October 2019, after the last of the major binary
4fdc8db… wyoung 871 package repos offering Fossil upgraded to Fossil 2.<i>x</i>,
ad47a44… wyoung 872 we switched the default hash mode so that
ad47a44… wyoung 873 the conversion to SHA-3 is fully automatic.
4fdc8db… wyoung 874 This not
d887a6d… wyoung 875 only solves the SHAttered problem, it should prevent a reoccurrence of
d887a6d… wyoung 876 similar problems for the foreseeable future.
d887a6d… wyoung 877
4fdc8db… wyoung 878 Meanwhile, the Git community took until August 2018 to publish
35fe8bf… wyoung 879 [https://git-scm.com/docs/hash-function-transition/ | their plan] for
35fe8bf… wyoung 880 solving the same problem by moving to SHA-256, a variant of the
35fe8bf… wyoung 881 [https://en.wikipedia.org/wiki/SHA-2 | older SHA-2 algorithm]. That is
35fe8bf… wyoung 882 now technically implemented in the sense that <tt>git init
35fe8bf… wyoung 883 --object-format=sha256</tt> exists, but note well: this is not only an
35fe8bf… wyoung 884 optional setting, Git forge support is mixed, most notably
35fe8bf… wyoung 885 [https://github.com/GitoxideLabs/gitoxide/issues/281 | lacking in
35fe8bf… wyoung 886 GitHub], plus also BitBucket and others. This is doubtless because of
35fe8bf… wyoung 887 this warning in the latest ([https://git-scm.com/docs/git-init/2.54.0 |
35fe8bf… wyoung 888 as of this writing]) <tt>git init</tt> docs:
35fe8bf… wyoung 889
35fe8bf… wyoung 890 <blockquote>Note: At present, there is no interoperability between
35fe8bf… wyoung 891 SHA-256 repositories and SHA-1 repositories.</blockquote>
35fe8bf… wyoung 892
35fe8bf… wyoung 893 Although we are now in the <i>tenth year</i> of this situation, there
35fe8bf… wyoung 894 remains hope that Git will manage to make the transition without taking
35fe8bf… wyoung 895 the full decade: the
35fe8bf… wyoung 896 [https://www.deployhq.com/blog/git-3-0-on-the-horizon-what-git-users-need-to-know-about-the-next-major-release
35fe8bf… wyoung 897 | latest plan] is that Git 3.0 will finally <i>(finally!)</i> switch to
35fe8bf… wyoung 898 SHA256 by default, forcing the issue. Given the track record, we are
35fe8bf… wyoung 899 taking a "show me" stance on this claim.
35fe8bf… wyoung 900
35fe8bf… wyoung 901 Always remember, attacks only get better, never worse.
4fdc8db… wyoung 902 Almost three years after Fossil solved this problem, the
4fdc8db… wyoung 903 [https://sha-mbles.github.io/ | SHAmbles attack] was published, further
4fdc8db… wyoung 904 weakening the case for continuing to use SHA-1.
4fdc8db… wyoung 905
4fdc8db… wyoung 906 The practical impact of attacks like SHAttered and SHAmbles on the
e673065… wyoung 907 Git and Fossil Merkle trees isn't clear, but you want to have your repositories
35fe8bf… wyoung 908 moved over to a stronger hash algorithm <i>before</i> someone figures out how
35fe8bf… wyoung 909 to make use of the weaknesses in the old one. Fossil's solution is long
35fe8bf… wyoung 910 since [https://repology.org/project/fossil/versions | universally deployed].
8452627… wyoung 911
8452627… wyoung 912 <hr/>
8452627… wyoung 913
8452627… wyoung 914 <h3>Asides and Digressions</h3>
8452627… wyoung 915
8452627… wyoung 916 <i><small><ol>
0ef227b… wyoung 917 <li><p>[./mirrorlimitations.md|Many
0ef227b… wyoung 918 things are lost] in making a Git mirror of a Fossil repo due to
0ef227b… wyoung 919 limitations of Git relative to Fossil. GitHub adds some of these
0ef227b… wyoung 920 missing features to stock
8452627… wyoung 921 Git, but because they're not part of Git proper,
8452627… wyoung 922 [./mirrortogithub.md|exporting a Fossil repository to GitHub] will
8452627… wyoung 923 still not include them; Fossil tickets do not become GitHub issues,
0ef227b… wyoung 924 for example.
0ef227b… wyoung 925
d23a845… wyoung 926 <li><p>The <tt>fossil-scm.org</tt> web site is actually hosted in
d23a845… wyoung 927 several parts, so that it is not strictly true that "everything" on
d23a845… wyoung 928 it is in the self-hosting Fossil project repo. The web forum is
5866461… wyoung 929 hosted as [https://fossil-scm.org/forum/|a separate Fossil repo]
09908ab… drh 930 from the [https://fossil-scm.org/home/|main Fossil self-hosting
5866461… wyoung 931 repo] for administration reasons, and the Download page content
0996347… wyoung 932 isn't normally synchronized with a "<tt>fossil clone</tt>" command unless
5866461… wyoung 933 you add the "-u" option. (See "[./aboutdownload.wiki|How the
f5ab488… drh 934 Download Page Works]" for details.)
f5ab488… drh 935 Chat history is deliberately not synced as
f5ab488… drh 936 chat messages are intended to be ephemeral.
f5ab488… drh 937 There may also be some purely
5866461… wyoung 938 static elements of the web site served via D. Richard Hipp's own
5866461… wyoung 939 lightweight web server,
6ef97bd… drh 940 <tt>[https://sqlite.org/althttpd/|althttpd]</tt>,
5866461… wyoung 941 which is configured as a front end to Fossil running in CGI mode on
5866461… wyoung 942 these sites.
5866461… wyoung 943
4b574be… wyoung 944 <li><p>This means you can give up waiting for Fossil to be ported to
4b574be… wyoung 945 the PDP-11, but we remain hopeful that someone may eventually port
4b574be… wyoung 946 it to [https://en.wikipedia.org/wiki/Z/OS|z/OS].
4b574be… wyoung 947
4b574be… wyoung 948 <li><p>"Why is there all this Tcl in and around Fossil?" you may
4b574be… wyoung 949 ask. It is because D. Richard Hipp is a long-time Tcl user and
4b574be… wyoung 950 contributor. SQLite started out as an embedded database for Tcl
4b574be… wyoung 951 specifically. ([https://sqlite.org/tclsqlite.html | [Reference]])
4b574be… wyoung 952 When he then created Fossil to manage the development of SQLite, it
4b574be… wyoung 953 was natural for him to use Tcl-based tools for its scripting, build
4b574be… wyoung 954 system, test system, etc. It came full circle in 2011 when
4b574be… wyoung 955 [https://www.reddit.com/r/programming/comments/fwrx5/tcl_and_tk_move_away_from_cvs_to_fossil/
4b574be… wyoung 956 | the Tcl and Tk projects moved from CVS to Fossil].
4b574be… wyoung 957
1296ee4… wyoung 958 <li><p>A minority of the pieces of the Git core software suite are
1296ee4… wyoung 959 written in other languages, primarily Perl, Python, and Tcl. (e.g.
1296ee4… wyoung 960 <tt>git-send-mail</tt>, <tt>git-p4</tt>, and <tt>gitk</tt>,
1296ee4… wyoung 961 respectively.) Although these interpreters are quite portable, they
1296ee4… wyoung 962 aren't installed by default everywhere, and on some platforms you
1296ee4… wyoung 963 can't count on them at all. (Not just Windows, but also the BSDs and
1296ee4… wyoung 964 many other non-Linux platforms.) This expands the dependency
1296ee4… wyoung 965 footprint of Git considerably. It is why the current Git for Windows
1296ee4… wyoung 966 distribution is 44.7&nbsp;MiB but the current <tt>fossil.exe</tt>
1296ee4… wyoung 967 zip file for Windows is 2.24&nbsp;MiB. Fossil is much smaller
1296ee4… wyoung 968 despite using a roughly similar amount of high-level scripting code
1296ee4… wyoung 969 because its interpreters are compact and built into Fossil itself.
1296ee4… wyoung 970
8452627… wyoung 971 <li><p>Both Fossil and Git support
8452627… wyoung 972 [https://en.wikipedia.org/wiki/Patch_(Unix)|<tt>patch(1)</tt>
e3e06d3… wyoung 973 files] — unified diff formatted output — for accepting drive-by contributions, but it's a
8452627… wyoung 974 lossy contribution path for both systems. Unlike Git PRs and Fossil
79c2cb0… wyoung 975 bundles, patch files collapse multiple checkins together, they don't
8452627… wyoung 976 include check-in comments, and they cannot encode changes made above
79c2cb0… wyoung 977 the individual file content layer: you lose branching decisions,
ad47a44… wyoung 978 tag changes, file renames, and more when using patch files. The
ad47a44… wyoung 979 [./patchcmd.md | <tt>fossil patch</tt> command]
e3e06d3… wyoung 980 also solves these problems, but it is because it works like a Fossil
e3e06d3… wyoung 981 bundle, only for uncommitted changes; it doesn't use Larry Wall's
e3e06d3… wyoung 982 <tt>patch</tt> tool to apply unified diff output to the receiving
e3e06d3… wyoung 983 Fossil checkout.</p></li>
8452627… wyoung 984 </ol></i></small>

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button