# Document Title
Fossil Versus Git
1.0 Don't Stress!
The feature sets of Fossil and Git overlap in many ways. Both are distributed version control systems which store a tree of check-in objects to a local repository clone. In both systems, the local clone starts out as a full copy of the remote parent. New content gets added to the local clone and then later optionally pushed up to the remote, and changes to the remote can be pulled down to the local clone at will. Both systems offer diffing, patching, branching, merging, cherry-picking, bisecting, private branches, a stash, etc.
Fossil has inbound and outbound Git conversion features, so if you start out using one DVCS and later decide you like the other better, you can easily move your version-controlled file content.¹
In this document, we set all of that similarity and interoperability aside and focus on the important differences between the two, especially those that impact the user experience.
Keep in mind that you are reading this on a Fossil website, and though we try to be fair, the information here might be biased in favor of Fossil, if only because we spend most of our time using Fossil, not Git. Ask around for second opinions from people who have used both Fossil and Git.
If you want a more practical, less philosophical guide to moving from Git to Fossil, see our Git to Fossil Translation Guide.
2.0 Differences Between Fossil And Git
Differences between Fossil and Git are summarized by the following table, with further description in the text that follows.
| GIT                                   | FOSSIL                                                 | more    |
| File versioning only                  | VCS, tickets, wiki, docs, notes, forum, chat, UI, RBAC | 2.1 ↓   |
| A federation of many small programs   | One self-contained, stand-alone executable             | 2.2 ↓   |
| Custom key/value data store           | The most used SQL database in the world                | 2.3 ↓   |
| Runs natively on POSIX systems        | Runs natively on both POSIX and Windows                | 2.4 ↓   |
| Bazaar-style development              | Cathedral-style development                            | 2.5.1 ↓ |
| Designed for Linux kernel development | Designed for SQLite development                        | 2.5.2 ↓ |
| Many contributors                     | Select contributors                                    | 2.5.3 ↓ |
| Focus on individual branches          | Focus on the entire tree of changes                    | 2.5.4 ↓ |
| One check-out per repository          | Many check-outs per repository                         | 2.6 ↓   |
| Remembers what you should have done   | Remembers what you actually did                        | 2.7 ↓   |
| Commit first                          | Test first                                             | 2.8 ↓   |
| SHA-1 or SHA-2                        | SHA-1 and/or SHA-3, in the same repository             | 2.9 ↓   |
2.1 Featureful
Git provides file versioning services only, whereas Fossil adds an integrated wiki, ticketing & bug tracking, embedded documentation, technical notes, a web forum, and a chat service, all within a single nicely-designed skinnable web UI, protected by a fine-grained role-based access control system. These additional capabilities are available for Git as 3rd-party add-ons, but with Fossil they are integrated into the design, to the point that it approximates "GitHub-in-a-box."
Even if you only want straight version control, Fossil has affordances not available in Git.
For instance, Fossil can do operations over all local repo clones and check-out directories with a single command. You can say "fossil all sync" on a laptop prior to taking it off the network hosting those repos, as before going on a trip. It doesn't matter if those repos are private and restricted to your company network or public Internet-hosted repos, you get synced up with everything you need while off-network.
You get the same capability with several other Fossil sub-commands as well, such as "fossil all changes" to get a list of files that you forgot to commit prior to the end of your working day, across all repos.
Whenever Fossil is told to modify the local checkout in some destructive way (fossil rm, fossil update, fossil revert, etc.) Fossil remembers the prior state and is able to return the check-out directory to that state with a fossil undo command. While you cannot undo a commit in Fossil — on purpose! — as long as the change remains confined to the local check-out directory only, Fossil makes undo easier than in Git.
For developers who choose to self-host projects rather than rely on a 3rd-party service such as GitHub, Fossil is much easier to set up: the stand-alone Fossil executable together with a 2-line CGI script suffice to instantiate a full-featured developer website. To accomplish the same using Git requires locating, installing, configuring, integrating, and managing a wide assortment of separate tools. Standing up a developer website using Fossil can be done in minutes, whereas doing the same using Git requires hours or days.
Fossil is small, complete, and self-contained. If you clone Git's self-hosting repository, you get just Git's source code. If you clone Fossil's self-hosting repository, you get the entire Fossil website — source code, documentation, ticket history, and so forth.² That means you get a copy of this very article and all of its historical versions, plus the same for all of the other public content on this site.
2.2 Self Contained
Git is actually a collection of many small tools, each doing one small part of the job, which can be recombined (by experts) to perform powerful operations. Git has a lot of complexity and many dependencies, so that most people end up installing it via some kind of package manager, simply because the creation of complicated binary packages is best delegated to people skilled in their creation. Normal Git users are not expected to build Git from source and install it themselves.
Fossil is a single self-contained stand-alone executable which depends only on common platform libraries in its default configuration. To install one of our precompiled binaries, unpack the executable from the archive and put it somewhere in your PATH. To uninstall it, delete the executable.
This policy is particularly useful when running Fossil inside a restrictive container, anything from classic chroot jails to modern OS-level virtualization mechanisms such as Docker. Our stock container image is under 8 MB when uncompressed and running. It contains nothing but a single statically-linked binary.
If you build a dynamically linked binary instead, Fossil's on-disk size drops to around 6 MB, and it's dependent only on widespread platform libraries with stable ABIs such as glibc, zlib, and openssl.
Full static linking is easier on Windows, so our precompiled Windows binaries are just a ZIP archive containing only "fossil.exe". There is no "setup.exe" to run.
Fossil is easy to build from sources. Just run "./configure && make" on POSIX systems and "nmake /f Makefile.msc" on Windows.
Contrast a basic installation of Git, which takes up about 15 MiB on Debian 10 across 230 files, not counting the contents of /usr/share/doc or /usr/share/locale. If you need to deploy to any platform where you cannot count on facilities like the POSIX shell, Perl interpreter, and Tcl/Tk platform needed to fully use Git as part of the base platform, the full footprint of a Git installation extends to more like 45 MiB and thousands of files. This complicates several common scenarios: Git for Windows, chrooted Git servers, Docker images...
Some say that Git more closely adheres to the Unix philosophy, summarized as "many small tools, loosely joined," but we have many examples of other successful Unix software that violates that principle to good effect, from Apache to Python to ZFS. We can infer from that that this is not an absolute principle of good software design. Sometimes "many features, tightly-coupled" works better. What actually matters is effectiveness and efficiency. We believe Fossil achieves this.
The above size comparisons aren't apples-to-apples anyway. We've compared the size of Fossil with all of its many built-in features to a fairly minimal Git installation. You must add a lot of third-party software to Git to give it a Fossil-equivalent feature set. Consider GitLab, a third-party extension to Git wrapping it in many features, making it roughly Fossil-equivalent, though much more resource hungry and hence more costly to run than the equivalent Fossil setup. The official GitLab Community Edition container currently clocks in at 2.66 GiB!
GitLab's requirements are easy to accept when you're dedicating a local rack server or blade to it, since its minimum requirements are more or less a description of the smallest thing you could call a "server" these days, but when you go to host that in the cloud, you can expect to pay about 8 times as much to comfortably host GitLab as for Fossil.³ This difference is largely due to basic technology choices: Ruby and PostgreSQL vs C and SQLite.
The Fossil project itself is hosted on a small and inexpensive VPS. A bare-bones $5/month VPS or a spare Raspberry Pi is sufficient to run a full-up project site, complete with tickets, wiki, chat, and forum, in addition to being a code repository.
2.3 Query Language
The baseline data structures for Fossil and Git are the same, modulo formatting details. Both systems manage a directed acyclic graph (DAG) of Merkle tree structured check-in objects. Check-ins are identified by a cryptographic hash of the check-in contents, and each check-in refers to its parent via the parent's hash.
The difference is that Git stores its objects as individual files in the .git folder or compressed into bespoke key/value pack-files, whereas Fossil stores its objects in a SQLite database file which provides ACID transactions and a high-level query language. This difference is more than an implementation detail. It has important practical consequences.
One notable consequence is that it is difficult to find the descendants of check-ins in Git. One can easily locate the ancestors of a particular Git check-in by following the pointers embedded in the check-in object, but it is difficult to go the other direction and locate the descendants of a check-in. It is so difficult, in fact, that neither native Git nor GitHub provide this capability short of crawling the commit log. With Fossil, on the other hand, finding descendants is a simple SQL query. It is common in Fossil to ask to see all check-ins since the last release. Git lets you see "what came before". Fossil makes it just as easy to also see "what came after".
Leaf check-ins in Git that lack a "ref" become "detached," making them difficult to locate and subject to garbage collection. This detached head state problem has caused grief for many Git users. With Fossil, detached heads are simply impossible because we can always find our way back into the Merkle tree using one or more of the relations in the SQL database.
The SQL query capabilities of Fossil make it easier to track the changes for one particular file within a project. For example, you can easily find the complete edit history of this one document, or even the same history color-coded by committer, Both questions are simple SQL query in Fossil, with procedural code only being used to format the result for display. The same result could be obtained from Git, but because the data is in a key/value store, much more procedural code has to be written to walk the data and compute the result. And since that is a lot more work, the question is seldom asked.
The ease of querying Fossil data using SQL means that status or history information about the project under management is easier to obtain. Being easier means that it is more likely to happen. Fossil reports tend to be more detailed and useful. Compare this Fossil timeline to its closest equivalent in GitHub. Judge for yourself: which of those reports is more useful to a developer trying to understand what happened?
The bottom line is that even though Fossil and Git are built around the same low-level data structure, the use of SQL to query this data makes the data more accessible in Fossil, resulting in more detailed information being available to the user. This improves situational awareness and makes working on the project easier.
2.4 Portable
Fossil is largely written in ISO C, almost purely conforming to the original 1989 standard. We make very little use of C99, and we do not knowingly make any use of C11. Fossil does call POSIX and Windows APIs where necessary, but it's about as portable as you can ask given that ISO C doesn't define all of the facilities Fossil needs to do its thing. (Network sockets, file locking, etc.) There are certainly well-known platforms Fossil hasn't been ported to yet, but that's most likely due to lack of interest rather than inherent difficulties in doing the port. We believe the most stringent limit on its portability is that it assumes at least a 32-bit CPU and several megs of flat-addressed memory.⁴ Fossil isn't quite as portable as SQLite, but it's close.
Over half of the C code in Fossil is actually an embedded copy of the current version of SQLite. Much of what is Fossil-specific after you set SQLite itself aside is SQL code calling into SQLite. The number of lines of SQL code in Fossil isn't large by percentage, but since SQL is such an expressive, declarative language, it has an outsized contribution to Fossil's user-visible functionality.
Fossil isn't entirely C and SQL code. Its web UI uses JavaScript where necessary. The server-side UI scripting uses a custom minimal Tcl dialect called TH1, which is embedded into Fossil itself. Fossil's build system and test suite are largely based on Tcl.⁵ All of this is quite portable.
About half of Git's code is POSIX C, and about a third is POSIX shell code. This is largely why the so-called "Git for Windows" distributions (both first-party and third-party) are actually an MSYS POSIX portability environment bundled with all of the Git stuff, because it would be too painful to port Git natively to Windows. Git is a foreign citizen on Windows, speaking to it only through a translator.⁶
While Fossil does lean toward POSIX norms when given a choice — LF-only line endings are treated as first-class citizens over CR+LF, for example — the Windows build of Fossil is truly native.
The third-party extensions to Git tend to follow this same pattern. GitLab isn't portable to Windows at all, for example. For that matter, GitLab isn't even officially supported on macOS, the BSDs, or uncommon Linuxes! We have many users who regularly build and run Fossil on all of these systems.
2.5 Linux vs. SQLite
Fossil and Git promote different development styles because each one was specifically designed to support the creator's main software development project: Linus Torvalds designed Git to support development of the Linux kernel, and D. Richard Hipp designed Fossil to support the development of SQLite. Both projects must rank high on any objective list of "most important FOSS projects," yet these two projects are almost entirely unlike one another, so it is natural that the DVCSes created to support these projects also differ in many ways.
In the following sections, we will explain how four key differences between the Linux and SQLite software development projects dictated the design of each DVCS's low-friction usage path.
When deciding between these two DVCSes, you should ask yourself, "Is my project more like Linux or more like SQLite?"
2.5.1 Development Organization
Eric S. Raymond's seminal essay-turned-book "The Cathedral and the Bazaar" details the two major development organization styles found in FOSS projects. As it happens, Linux and SQLite fall on opposite sides of this dichotomy. Differing development organization styles dictate a different design and low-friction usage path in the tools created to support each project.
Git promotes the Linux kernel's bazaar development style, in which a loosely-associated mass of developers contribute their work through a hierarchy of lieutenants who manage and clean up these contributions for consideration by Linus Torvalds, who has the power to cherry-pick individual contributions into his version of the Linux kernel. Git allows an anonymous developer to rebase and push specific locally-named private branches, so that a Git repo clone often isn't really a clone at all: it may have an arbitrary number of differences relative to the repository it originally cloned from. Git encourages siloed development. Select work in a developer's local repository may remain private indefinitely.
All of this is exactly what one wants when doing bazaar-style development.
Fossil's normal mode of operation differs on every one of these points, with the specific designed-in goal of promoting SQLite's cathedral development model:
    Personal engagement: SQLite's developers know each other by name and work together daily on the project.
    Trust over hierarchy: SQLite's developers check changes into their local repository, and these are immediately and automatically synchronized up to the central repository; there is no "dictator and lieutenants" hierarchy as with Linux kernel contributions. D. Richard Hipp rarely overrides decisions made by those he has trusted with commit access on his repositories. Fossil allows you to give some users more power over what they can do with the repository, but Fossil only loosely supports the enforcement of a development organization's social and power hierarchies. Fossil is a great fit for flat organizations.
    No easy drive-by contributions: Git pull requests offer a low-friction path to accepting drive-by contributions. Fossil's closest equivalents are its unique bundle and patch features, which require higher engagement than firing off a PR.⁷ This difference comes directly from the initial designed purpose for each tool: the SQLite project doesn't accept outside contributions from previously-unknown developers, but the Linux kernel does.
    No rebasing: When your local repo clone syncs changes up to its parent, those changes are sent exactly as they were committed locally. There is no rebasing mechanism in Fossil, on purpose.
    Sync over push: Explicit pushes are uncommon in Fossil-based projects: the default is to rely on autosync mode instead, in which each commit syncs immediately to its parent repository. This is a mode so you can turn it off temporarily when needed, such as when working offline. Fossil is still a truly distributed version control system; it's just that its starting default is to assume you're rarely out of communication with the parent repo.
    This is not merely a reflection of modern always-connected computing environments. It is a conscious decision in direct support of SQLite's cathedral development model: we don't want developers going dark, then showing up weeks later with a massive bolus of changes for us to integrate all at once. Jim McCarthy put it well in his book on software project management, Dynamics of Software Development: "Beware of a guy in a room."
    Branch names sync: Unlike in Git, branch names in Fossil are not purely local labels. They sync along with everything else, so everyone sees the same set of branch names. Fossil's design choice here is a direct reflection of the Linux vs. SQLite project outlook: SQLite's developers collaborate closely on a single coherent project, whereas Linux's developers go off on tangents and occasionally send selected change sets to each other.
    Private branches are rare: Private branches exist in Fossil, but they're normally used to handle rare exception cases, whereas in many Git projects, they're part of the straight-line development process.
    Identical clones: Fossil's autosync system tries to keep each local clone identical to the repository it cloned from.
Where Git encourages siloed development, Fossil fights against it. Fossil places a lot of emphasis on synchronizing everyone's work and on reporting on the state of the project and the work of its developers, so that everyone — especially the project leader — can maintain a better mental picture of what is happening, leading to better situational awareness.
By contrast, "…forking is at the core of social coding at GitHub". As of January 2022, Github hosts 47 million distinct software projects, most of which were created by forking a previously-existing project. Since this is roughly twice the number of developers in the world, it beggars belief that most of these forks are still under active development. The vast bulk of these must be abandoned one-off efforts. This is part of the nature of bazaar style development.
You can think about this difference in terms of feedback loop size, which we know from the mathematics of control theory to directly affect the speed at which any system can safely make changes. The larger the feedback loop, the slower the whole system must run in order to avoid loss of control. The same concept shows up in other contexts, such as in the OODA loop concept. Committing your changes to private branches in order to delay a public push to the parent repo increases the size of your collaborators' control loops, either causing them to slow their work in order to safely react to your work, or to over-correct in response to each change.
Each DVCS can be used in the opposite style, but doing so works against their low-friction paths.
2.5.2 Scale
The Linux kernel has a far bigger developer community than that of SQLite: there are thousands and thousands of contributors to Linux, most of whom do not know each other's names. These thousands are responsible for producing roughly 89× more code than is in SQLite. (10.7 MLOC vs. 0.12 MLOC according to SLOCCount.) The Linux kernel and its development process were already uncommonly large back in 2005 when Git was designed, specifically to support the consequences of having such a large set of developers working on such a large code base.
95% of the code in SQLite comes from just four programmers, and 64% of it is from the lead developer alone. The SQLite developers know each other well and interact daily. Fossil was designed for this development model.
When choosing your DVCS, we think you should ask yourself whether the scale of your software configuration management problems is closer to those Linus Torvalds designed Git to cope with or whether your work's scale is closer to that of SQLite, for which D. Richard Hipp designed Fossil. An automotive air impact wrench running at 8000 RPM driving an M8 socket-cap bolt at 16 cm/s is not the best way to hang a picture on the living room wall.
Fossil works well for projects several times the size of SQLite, such as Tcl, with a repository over twice the size and with many more core committers.
2.5.3 Individual Branches vs. The Entire Change History
Both Fossil and Git store history as a directed acyclic graph (DAG) of changes, but Git tends to focus more on individual branches of the DAG, whereas Fossil puts more emphasis on the entire DAG.
For example, the default behavior in Git is to only synchronize a single branch, whereas with Fossil the only sync option is to sync the entire DAG. Git commands, GitHub, and GitLab tend to show only a single branch at a time, whereas Fossil usually shows all parallel branches at once. Git has commands like "rebase" that help keep all relevant changes on a single branch, whereas Fossil encourages a style of many concurrent branches constantly springing into existence, undergoing active development in parallel for a few days or weeks, then merging back into the main line and disappearing.
This difference in emphasis arises from the different purposes of the two systems. Git focuses on individual branches, because that is exactly what you want for a highly-distributed bazaar-style project such as Linux. Linus Torvalds does not want to see every check-in by every contributor to Linux: such extreme visibility does not scale well. Contrast Fossil, which was written for the cathedral-style SQLite project and its handful of active committers. Seeing all changes on all branches all at once helps keep the whole team up-to-date with what everybody else is doing, resulting in a more tightly focused and cohesive implementation.
2.6 One vs. Many Check-outs per Repository
Because Git commingles the repository data with the initial checkout of that repository, the default mode of operation in Git is to stick to that single work/repo tree, even when that's a shortsighted way of working.
Fossil doesn't work that way. A Fossil repository is a SQLite database file which is normally stored outside the working checkout directory. You can open a Fossil repository any number of times into any number of working directories. A common usage pattern is to have one working directory per active working branch, so that switching branches is done with a cd command rather than by checking out the branches successively in a single working directory.
Fossil does allow you to switch branches within a working checkout directory, and this is also often done. It is simply that there is no inherent penalty to either choice in Fossil as there is in Git. The standard advice is to use a switch-in-place workflow in Fossil when the disturbance from switching branches is small, and to use multiple checkouts when you have long-lived working branches that are different enough that switching in place is disruptive.
While you can use Git in the Fossil style, Git's default tie between working directory and repository means the standard method for working with a Git repo is to have one working directory only. Most Git tutorials teach this style, so it is how most people learn to use Git. Because relatively few people use Git with multiple working directories per repository, there are several known problems with that way of working, problems which don't happen in Fossil because of the clear separation between a Fossil repository and each working directory.
This distinction matters because switching branches inside a single working directory loses local context on each switch.
For instance, in any software project where the runnable program must be built from source files, you invalidate build objects on each switch, artificially increasing the time required to switch versions. Most obviously, this affects software written in statically-compiled programming languages such as C, Java, and Haskell, but it can even affect programs written in dynamic languages like JavaScript. A typical SPA build process involves several passes: Browserify to convert Node packages so they'll run in a web browser, SASS to CSS translation, transpilation of Typescript to JavaScript, uglification, etc. Once all that processing work is done for a given input file in a given working directory, why re-do that work just to switch versions? If most of the files that differ between versions don't change very often, you can save substantial time by switching branches with cd rather than swapping versions in-place within a working checkout directory.
For another example, you might have an active long-running test grinding away in a working directory, then get a call from a customer requiring that you switch to a stable branch to answer questions in terms of the version that customer is running. You don't want to stop the test in order to switch your lone working directory to the stable branch.
Disk space is cheap. Having several working directories — each with its own local state — makes switching versions cheap and fast.
Plus, cd is faster to type than git checkout or fossil update.
2.7 What you should have done vs. What you actually did
Git puts a lot of emphasis on maintaining a "clean" check-in history. Extraneous and experimental branches by individual developers often never make it into the main repository. Branches may be rebased before being pushed to make it appear as if development had been linear, or "squashed" to make it appear that multiple commits were made as a single commit. There are other history rewriting mechanisms in Git as well. Git strives to record what the development of a project should have looked like had there been no mistakes.
Fossil, in contrast, puts more emphasis on recording exactly what happened, including all of the messy errors, dead-ends, experimental branches, and so forth. One might argue that this makes the history of a Fossil project "messy," but another point of view is that this makes the history "accurate." In actual practice, the superior reporting tools available in Fossil mean that this incidental mess is not a factor.
Like Git, Fossil has an amend command for modifying prior commits, but unlike in Git, this works not by replacing data in the repository, but by adding a correction record to the repository that affects how later Fossil operations present the corrected data. The old information is still there in the repository, it is just overridden from the amendment point forward.
Fossil lacks almost every other history rewriting mechanism listed on the Git documentation page linked above. There is no rebase in Fossil, on purpose, thus no way to reorder or copy commits around in the commit hash tree. There is no commit squashing, dropping, or interactive patch-based cherry-picking of commit elements in Fossil. There is nothing like Git's filter-branch in Fossil.
The lone exception is deleting commits. Fossil has two methods for doing that, both of which have stringent limitations, on purpose.
The first is shunning. See that document for details, but briefly, you only get mandatory compliance for shun requests within a single repository. Shun requests do not propagate automatically between repository clones. A Fossil repository administrator can cooperatively pull another repo's shun requests across a sync boundary, so that two admins can get together and agree to shun certain committed artifacts, but a person cannot force their local shun requests into another repo without having admin-level control over the receiving repo as well. Fossil's shun feature isn't for fixing up everyday bad commits, it's for dealing with extreme situations: public commits of secret material, ticket/wiki/forum spam, law enforcement takedown demands, etc.
There is also the experimental purge command, which differs from shunning in ways that aren't especially important in the context of this document. At a 30000 foot level, you can think of purging as useful only when you've turned off Fossil's autosync feature and want to pluck artifacts out of its hash tree before they get pushed. In that sense, it's approximately the same as git rebase -i, drop. However, given that Fossil defaults to having autosync enabled for good reason, the purge command isn't very useful in practice: once a commit has been pushed into another repo, shunning is more useful if you need to delete it from history.
If these accommodations strike you as incoherent with respect to Fossil's philosophy of durable, unchanging commits, realize that if shunning and purging were removed from Fossil, you could still remove artifacts from the repository with SQL DELETE statements; the repository database file is, after all, directly modifiable, being writable by your user. Where the Fossil philosophy really takes hold is in making it difficult to violate the integrity of the hash tree. It's somewhat tangential, but the document "Is Fossil a Blockchain?" touches on this and related topics.
One commentator characterized Git as recording history according to the victors, whereas Fossil records history as it actually happened.
2.8 Test Before Commit
One of the things that falls out of Git's default separation of commit from push is that there are several Git sub-commands that jump straight to the commit step before a change could possibly be tested. Fossil, by contrast, makes the equivalent change to the local working check-out only, requiring a separate check-in step to commit the change. This design difference falls naturally out of Fossil's default-enabled autosync feature and its philosophy of not offering history rewriting features.
The prime example in Git is rebasing: the change happens to the local repository immediately if successful, even though you haven't tested the change yet. It's possible to argue for such a design in a tool like Git since it lacks an autosync feature, because you can still test the change before pushing local changes to the parent repo, but in the meantime you've made a durable change to your local Git repository. You must do something drastic like git reset --hard to revert that rebase or rewrite history before pushing it if the rebase causes a problem. If you push your rebased local repo up to the parent without testing first, you cannot fix it without violating the golden rule of rebasing.
Lesser examples are the Git merge, cherry-pick, and revert commands, all of which apply work from one branch onto another, and all of which commit their change to the local repository immediately without giving you an opportunity to test the change first unless you give the --no-commit option. Otherwise, you're back in the same boat: reset the local repository or rewrite history to fix things, then maybe retry.
Fossil cannot sensibly work that way because of its default-enabled autosync feature and its purposeful paucity of commands for modifying commits, as discussed in the prior section.
Instead of jumping straight to the commit step, Fossil applies the proposed merge to the local working directory only, requiring a separate check-in step before the change is committed to the repository. This gives you a chance to test the change first, either manually or by running your software's automatic tests. (Ideally, both!) Thus, Fossil doesn't need rebase, squashing, reset --hard, or other Git commit mutating mechanisms.
Because Fossil requires an explicit commit for a merge, it has the nice side benefit that it makes you give an explicit commit message for each merge, whereas Git writes that commit message itself by default unless you give the optional --edit flag to override it.
We don't look at this difference as a workaround in Fossil for autosync, but instead as a test-first philosophical difference: fossil commit is a commitment. When every commit is pushed to the parent repo by default, it encourages a working style in which every commit is tested first. It encourages thinking before acting. We believe this is an inherently good thing.
Incidentally, this is a good example of Git's messy command design. These three commands:
$ git merge HASH 
$ git cherry-pick HASH 
$ git revert HASH
...are all the same command in Fossil:
$ fossil merge HASH
$ fossil merge --cherrypick HASH
$ fossil merge --backout HASH
If you think about it, they're all the same function: apply work done on one branch to another. All that changes between these commands is how much work gets applied — just one check-in or a whole branch — and the merge direction. This is the sort of thing we mean when we point out that Fossil's command interface is simpler than Git's: there are fewer concepts to keep track of in your mental model of Fossil's internal operation.
Fossil's implementation of the feature is also simpler to describe. The brief online help for fossil merge is currently 41 lines long, to which you want to add the 600 lines of the branching document. The equivalent documentation in Git is the aggregation of the man pages for the above three commands, which is over 1000 lines, much of it mutually redundant. (e.g. Git's --edit and --no-commit options get described three times, each time differently.) Fossil's documentation is not only more concise, it gives a nice split of brief online help and full online documentation.
2.9 Hash Algorithm: SHA-3 vs SHA-2 vs SHA-1
Fossil started out using 160-bit SHA-1 hashes to identify check-ins, just as in Git. That changed in early 2017 when news of the SHAttered attack broke, demonstrating that SHA-1 collisions were now practical to create. Two weeks later, the creator of Fossil delivered a new release allowing a clean migration to 256-bit SHA-3 with full backwards compatibility to old SHA-1 based repositories.
In October 2019, after the last of the major binary package repos offering Fossil upgraded to Fossil 2.x, we switched the default hash mode so that the conversion to SHA-3 is fully automatic. This not only solves the SHAttered problem, it should prevent a reoccurrence of similar problems for the foreseeable future.
Meanwhile, the Git community took until August 2018 to publish their first plan for solving the same problem by moving to SHA-256, a variant of the older SHA-2 algorithm. As of this writing in February 2020, that plan hasn't been implemented, as far as this author is aware, but there is now a competing SHA-256 based plan which requires complete repository conversion from SHA-1 to SHA-256, breaking all public hashes in the repo. One way to characterize such a massive upheaval in Git terms is a whole-project rebase, which violates Git's own Golden Rule of Rebasing.
Regardless of the eventual implementation details, we fully expect Git to move off SHA-1 eventually and for the changes to take years more to percolate through the community.
Almost three years after Fossil solved this problem, the SHAmbles attack was published, further weakening the case for continuing to use SHA-1.
The practical impact of attacks like SHAttered and SHAmbles on the Git and Fossil Merkle trees isn't clear, but you want to have your repositories moved over to a stronger hash algorithm before someone figures out how to make use of the weaknesses in the old one. Fossil has had this covered for years now, so that the solution is now almost universally deployed.
Asides and Digressions
    Many things are lost in making a Git mirror of a Fossil repo due to limitations of Git relative to Fossil. GitHub adds some of these missing features to stock Git, but because they're not part of Git proper, exporting a Fossil repository to GitHub will still not include them; Fossil tickets do not become GitHub issues, for example.
    The fossil-scm.org web site is actually hosted in several parts, so that it is not strictly true that "everything" on it is in the self-hosting Fossil project repo. The web forum is hosted as a separate Fossil repo from the main Fossil self-hosting repo for administration reasons, and the Download page content isn't normally synchronized with a "fossil clone" command unless you add the "-u" option. (See "How the Download Page Works" for details.) Chat history is deliberately not synced as chat messages are intended to be ephemeral. There may also be some purely static elements of the web site served via D. Richard Hipp's own lightweight web server, althttpd, which is configured as a front end to Fossil running in CGI mode on these sites.
    That estimate is based on pricing at Digital Ocean in mid-2019: Fossil will run just fine on the smallest instance they offer, at US $5/month, but the closest match to GitLab's minimum requirements among Digital Ocean's offerings currently costs $40/month.
    This means you can give up waiting for Fossil to be ported to the PDP-11, but we remain hopeful that someone may eventually port it to z/OS.
    "Why is there all this Tcl in and around Fossil?" you may ask. It is because D. Richard Hipp is a long-time Tcl user and contributor. SQLite started out as an embedded database for Tcl specifically. ([Reference]) When he then created Fossil to manage the development of SQLite, it was natural for him to use Tcl-based tools for its scripting, build system, test system, etc. It came full circle in 2011 when the Tcl and Tk projects moved from CVS to Fossil.
    A minority of the pieces of the Git core software suite are written in other languages, primarily Perl, Python, and Tcl. (e.g. git-send-mail, git-p4, and gitk, respectively.) Although these interpreters are quite portable, they aren't installed by default everywhere, and on some platforms you can't count on them at all. (Not just Windows, but also the BSDs and many other non-Linux platforms.) This expands the dependency footprint of Git considerably. It is why the current Git for Windows distribution is 44.7 MiB but the current fossil.exe zip file for Windows is 2.24 MiB. Fossil is much smaller despite using a roughly similar amount of high-level scripting code because its interpreters are compact and built into Fossil itself.
    Both Fossil and Git support patch(1) files — unified diff formatted output — for accepting drive-by contributions, but it's a lossy contribution path for both systems. Unlike Git PRs and Fossil bundles, patch files collapse multiple checkins together, they don't include check-in comments, and they cannot encode changes made above the individual file content layer: you lose branching decisions, tag changes, file renames, and more when using patch files. The fossil patch command also solves these problems, but it is because it works like a Fossil bundle, only for uncommitted changes; it doesn't use Larry Wall's patch tool to apply unified diff output to the receiving Fossil checkout.
This page was generated in about 0.008s by Fossil 2.25 [390e00134e] 2024-06-25 06:30:55 

Welcome to another episode.
My name is Helen Scott.
And today I'm going to be interviewing  Anna.
So  Anna is a creative.
She uses her communication and her storytelling,
and she's used it to tell Git in a simple
way.
So,  Anna, welcome.
 Thanks for having me, Helen.
I'm excited.
I'm excited too.
I'm just gonna see how many stories of my
Git frustration I can weave into this interview.
So  Anna's published her first book, "Learning
Git."
It's on the O'Reilly platform.
You published it June last year,  Anna?
June last year.
June last year.
So, I've got a copy of the book.
I've been very efficient, and put it back
on my bookshelf over here.
For the purposes of this interview, let's
start right at the beginning.
Tell us a little bit more about you and what
you enjoy doing, before we get started into
the book.cv
I think what I enjoy doing is taking a complicated
topic or a topic that confuses people, and
making it simpler and more approachable.
And presenting the information in a way that
it's easier to learn for beginners.
So that's what I did with Git.
And that's what I also do in my day job, because
I work as a technical writer.
So in my day job, I also take various topics
and explain them in a simpler way, and present
information in a simple way, so that people
can consume it better.
Fantastic.
And that's so important.
Having a technical writing background myself
as well, it's just super important that when
a user comes...looks for the documentation,
that it is written in such a way that you
can actually help them to move forward and
get past the problem that's made them go and
look at the documentation in the first place,
right?
Yes.
Okay.
So, I'm going to not derail this interview
completely with how annoyed I can get at Git
sometimes, but I think maybe some of our audience
might share some of these frustrations.
What was your primary motivators behind writing
this book?
Okay.
So, the reason I wrote this book is because
I needed this book.
So I'm just going to backtrack a little and
say that my entryway into the world of tech
was through the world of UX design, so user
experience design.
So, at some point in my life, I did a UX design
bootcamp, and I worked as a UX designer.
And then when I was working as a UX designer,
I'd realized that I knew how to design apps
and websites, so sort of like an architect.
But I didn't know how to actually build those
apps and websites.
I wasn't like the construction company that
gets the blueprints and actually builds them.
I got really curious about how these things
are built.
So I ended up doing a coding bootcamp.
That's kind of a three-to-four-month intensive
program, learned the basics of web development,
and then worked as a front-end developer.
The first time that I Git introduced to get
was in that coding boot camp.
But it was one hour where they just kind of
told us Git add, Git commit, Git push, go.
Off you go.
And obviously, that may have been sort of
enough when you were just working on your
projects in the coding boot camp.
But once I got my first job as a junior front-end
developer, and I had to work with a team of
developers and senior developers, I was terrified
of Git.
I mean, every time I had to do something that
I deemed was complicated, which was almost
everything, I would call on the senior developers,
and ask them to help me.
And I was always worried I was about to destroy
the repository, and take down the entire platform
and the entire website.
And this was like a massive ecommerce platform,
so that would have not been good.
Little did I know that that was not the case.
And that that was never gonna happen.
But anyways, so at some point during that
job, I realized I want to conquer this fear.
I want to learn how to use Git, and I want
to understand how it works, so that I can
be an independent developer, and not have
to ask for help all the time.
So I started learning, looking for online
resources to learn Git.
And what I realized was that there weren't
really any online resources that were designed
for people like me, that were really new to
tech, that had transitioned into tech from
non-technical backgrounds, and that explained
things in a simple way.
Then at some point, this creative idea came
to me of how I could teach Git using colors,
and storytelling, and visuals.
I mean, this was after I'd kind of understood
some of the basics.
So the first thing that I did was actually
make an online course teaching Git.
And that's still available online.
At the moment, it's on Udemy.
Who knows where it will be in the future.
But that journey...
When I was making the online course, I still
wanted to write a book.
But I felt that the barrier to entry to write
the book was higher than to make an online
course.
Because with online courses, you just kind
of record your voice, make some slides, record
them.
So I could do that a lot easier and publish
it online a lot easier.
But once I released that online course, I
started getting reviews, I started getting
feedback.
I realized my way of teaching Git really resonated
with a lot of people.
There were a lot of people that, just like
me, had not been served by the Git teaching
resources out there up until now.
My approach to organizing information and
presenting concepts worked for them.
And then I was like, all right, since it works,
let's write this book.
I am also a writer in my personal time, and
I love to journal.
So, writing is my medium of choice.
That's kind of how this book came about.
This is the book that I wish I had had in
my first week of that coding boot camp.
Or especially in that first week of my new
job as a front-end developer.
A hundred percent.
100%.
And just in hearing that story, there's so
much that resonated with me.
People have talked about, regardless of how
you ended up in the profession, whether you're
coming through a degree, you're coming through
a boot camp, you're self-taught, whatever
it is.
How much you learn about version control,
and, you know, Git is part of that, is really
variable.
In my experience, sometimes 
it's purely conceptual.
It's like, there is this thing that you can
do.
You will learn about it on your job.
And then you turn up at your job and you're
like, "Oh, I'm terrified of going to study
the whole repository."
So I think we've all been there.
And I think we've all had experience of knowing
who or even being at times that expert in
Git on the team, that people go to when they've
gone beyond the Git pull or, you know, Git
update, Git push.
They've gone beyond the basics, and they're
like, "Oh, I'm in trouble now.
Something's not working."
So I think certainly, I identified with a
lot of what you said there, and I expect our
audience did as well.
So much frustration.
The other thing that actually has been very
surprising is that it's not just developers
that use Git, there are so many other people
that work with developers or that do other
jobs that use Git.
And this I've discovered since publishing
the book.
Game artists.
Mechanical engineers also use Git.
Sometimes UX designers have to collaborate
with devs, and share assets or whatever.
Even product managers.
And actually one of the biggest audiences
my book actually got was technical writers,
because they often have this thing that we
call Docs as Code Approach.
And they use Git to manage the repositories
for the documentation websites.
So some technical writers come from a technical
background, but some don't.
And so, technical concepts don't come naturally
to them.
My book has really served various different
audiences, including junior developers and
experienced developers, but also just so many
other professions.
Which, yeah, has been very eye opening.
And again, identified with that, because it
was back in my technical writing career, and
I started using Git.
And I needed that Git expert in the team,
that developer, and I was like, "I've got
it in reverse.
Please help me."
So let's move swiftly on to talking about
the book itself, which is why the majority
of the audience will be here.
Can you give us an overview of the book and
talk about its structure a little bit more,
please?
Definitely.
So, the book is for absolute complete beginners.
If you have a bit of experience, you can maybe
try to skip a chapter.
Normally, you should do it from the beginning
to the end, though, because it's a hands-on
learning experience, where you're working
on a specific repository throughout the entire
book, which is actually called the rainbow
repository.
Because you're listing the colors of the rainbow.
I'll explain that a little bit more later.
But the first chapter actually just starts
off with installing Git and an introduction
to the command line, because some people actually
haven't worked in the command line and aren't
familiar with it.
So, it really is a book for absolute beginners.
Then I build this thing that I call the Git
diagram, which is my way of creating a mental
model of the different areas of Git and how
they fit together.
So, you have your project directory, the working
directory, the local repository.
Then inside the local repository, you have
the staging area and the commit history.
When I was learning Git, I came across diagrams
that tried to kind of depict these different
areas, and how they interact.
They didn't really make sense to me.
So I've actually created my own representation
of these areas.
This is really key to my teaching methodology.
Because the main part of my teaching methodology
is creating a mental model of how things work,
and making things tangible.
So, we build the Git diagram.
Once we have that, we go over the process
of making commits.
We introduce branches and what they are.
And we create visualizations for all of these
things.
So I visualize what branches look like.
They're just pointers to commits.
Then what else?
I have a list here.
I go over merging, and I introduce the two
types of merges, fast forward merges, three-way
merges.
We're at chapter five now.
And there we just go over the experience of
doing a fast-forward merge, not yet a three-way
merge.
That's a bit more spicy, and it comes later
on in the learning journey.
And then in chapter six is when we actually
go from working just in the local repository,
just on your computer, on your own.
We introduce hosting services.
so GitHub, GitLab, Bitbucket, 
and remote repositories, 
basically.
One thing I should mention right now, just
a quick parenthesis, is that, the book is
not prescriptive.
You can use whichever hosting service you
want.
You can use whichever text editor you want.
I didn't want to exclude anyone that uses
maybe a different technology.
And I wanted to make the book accessible to,
yeah, anything.
So yeah, so that's closing parenthesis now.
Moving on, chapter seven, we jump into creating
and pushing to a remote repository.
So we're really into, you know, local repository,
remote repository.
Chapter eight, we go over cloning and fetching
data.
So, in chapter eight, is where the learning
experience, we simulate that you're working
with another person.
So, in the book, we say that a friend of yours
wants to join you on your rainbow project.
So they create a...
Well, they clone your remote repository, and
they create a local repository called Friend
Rainbow.
And I mean, if you have a friend that you
can actually do all the exercises with, then
that's ideal.
But the most realistic thing is that you just
create a second local repository on your computer,
and you just kind of pretend it's on someone
else's computer.
But this is really important, because at the
end of the day, Git is a collaboration tool,
right?
It's version control and collaboration.
So, if you don't have any representations
of how the collaboration happens, then that
leaves out basically more than half of Git.
Chapter eight, you're learning how to clone,
how to fetch data from a remote repository.
And chapter nine, finally, we get into the
spicy topic of...
Well, not that spicy.
Three-way merges are pretty simple.
But then chapter 10, we get into merge conflicts,
which is the spicier topic, and the thing
that a lot of people are afraid of.
Chapter 11, rebasing.
Rebasing, I'd say is the most advanced thing
that I cover in my book.
Like I said, this book is a real basics and
beginner book.
So, rebasing is, yeah, at the end.
And finally, the last chapter is pull requests
or merge requests, whatever terminology you
want to use.
And obviously, pull requests, merge requests,
they're not actually a feature of Git itself.
They're a feature of the hosting services.
So GitHub, GitLab, Bitbucket, and others.
There are others.
I'm just not going to start naming 20 different
hosting services.
But I thought that they were so important
because they really...
Yeah, they're essential, almost for everyone's
workflow.
So I thought, okay, I'll make an exception
and include them, even though this is a book
about Git.
That's kind of an overview.
And like I mentioned, you're working on this
rainbow project, and it's hands on.
You are with your computer, doing the exercises.
So you are supposed to do the book from chapter
1 to chapter 12.
Because if you don't, then you'll miss out,
you won't be able to follow along.
But I have created an appendix, where I've
offered instructions on how someone can start,
like, create the minimum set up for their
project to start off on any chapter.
Because, yeah, maybe you read the book once,
and then you just want to review chapter eight,
or you just want to review chapter nine.
And you don't have to go from chapter one
all the way to that chapter just to be able
to review it.
But yeah, that's the kind of overview of the
book.
Brilliant.
So for my next question, I'm going to use
the book as my demo, so the audience can see
what I'm talking about when I ask this next
question.
For example, you've made extensive use of
color in this book.
And you've mentioned the 
rainbow project repeatedly.
What made you choose that theme?
And why?
When my creative idea of how I could teach
Git in a simple way came to me, it was all
about using color.
Because I thought to myself, one of the really
confusing or difficult things with Git, when
you're teaching it, is that there's commit
hashes.
So every commit...
A commit is a version of your project.
Every commit has a commit hash, so 40 characters,
letters, and numbers, that's unique.
And it's like a name for the commit.
But if you're teaching Git, and you're having
to refer to, well, remember commit, six, nine,
Z, blah, blah, blah, blah, blah.
That is so confusing.
Who wants to learn like that?
So I thought to myself, how can I use color
instead?
And so let me give an example.
In the rainbow project, the very first thing
you add to your project, you create a rainbow.txt
file.
So a txt file, very simple.
I keep everything really simple.
And I'll make a comment about that in a second.
And the first thing you add is just...red
is the first color of the rainbow.
You just add that sentence, first line of
your file, and you add that to the staging
area, and you make a commit.
And then I represent that commit in the diagrams
as a circle, that is red.
And so from then on, I can just say, the red
commits.
And that just simplifies the learning experience.
It makes it a lot more memorable, and also
very much more visual.
Because I'm not having to include, like, a
little commit hash in my diagram to try to
refer to the commit.
That's why I use color in my teaching methodology.
And the rainbow was just a really nice way
to structure it.
You know, we all...well, many of us, or most
of us know that the order of the colors of
the rainbow.
So it's a very familiar thing.
It was easy to then, yeah, structure the whole
book that way.
Although at the end, I ran out of colors.
I just had to add some random colors.
I actually have...
At the end, you add another file to your project
called othercolors.txt, and you start adding,
like, pink is not a color in the rainbow.
And gray is not a color in the rainbow.
Because I literally ran out of colors.
But also because I wanted to show, you know,
how you add new files to your project.
But the other thing I wanted to say about
keeping things simple, is that one of the
decisions I made with this book is that it
would have no code in it.
So, the files in your project are just dot-txt
files, which are just really plain text files.
They're not even markdown files.
Like, it is so simple.
Because I thought if I make the project that
you work on in the book, a web development
project, or a data science project, a Java
project, a Python project, anything, it will
exclude some people for whom that is not familiar.
And let's say, yeah, fine, well, those people
can go and look it up.
It just complicates things.
It's not necessary.
I wanted someone to just be able to focus
on learning the concepts of Git, rather than
having to also learn other tech concepts,
which are not relevant to just learning Git.
So, yeah, that's kind of...that was my way
of approaching how to teach this stuff.
That's great.
And I think what's really helpful and insightful
is, the very deliberate decisions that you
made along the way.
You know, this didn't just happen by accident,
you made a very deliberate choice that I'm
going to represent hashes with blobs of color,
and therefore I'm going to refer to those.
And you made a very deliberate choice to use
txt files, a concept that is going to be familiar
to your entire audience.
So I really liked that you made those conscious
decisions upfront to create the learning journey
that, you know, you said yourself you wanted
when you first started working with Git.
YOne more I can add is screenshots.
I decided not a single screenshot in my book.
Because I thought to myself, the minute I
add a screenshot, the book is out of date.
And since I was able to do with...
So true.
Helen knows this because she wrote a book
with lots of screenshots.
But you have to have screenshots in yours.
Sorry, off topic.
I think that was another really, really conscious
decision of mine, of, since it's not necessary,
don't include screenshots.
Because again, they're not relevant to everyone.
Everyone has a different operating system,
and a different version, and UI changes.
And the minute that the book goes to print,
it would be out of date.
So, that was another really conscious decision
I made for this book.
Good call out.
Good call out.
And yes, the pain is real.
Just ask my co-author, Trisha Gee, who updated
them all.
Okay, so the next question is kind of a double
question.
You can answer it in any order you like.
But it's, who should read this book?
And equally as importantly, who is this book
not for?
So who should read this book?
I think anyone that wants to learn Git.
So they've never used Git, and someone's told
them they have to, or they realize they have
to for their work or for their personal project.
So anyone that wants to learn Git.
Anyone that's confused by Git.
I have talked to developers with 10 years'
experience, that still are afraid of Git and
don't have a mental model that they can reliably,
like, use and feel confident with.
And they even tell me, this book helped me
to put things together.
So, yeah, junior developers, anyone that doesn't
yet really understand how the pieces come
together.
Because what happens is, when you don't have
a good mental model of Git, once you start...
Like, maybe you're okay with doing the Git
add, Git commit, Git push.
But once you start going to the more advanced
topics, you don't really understand how they
work.
And that's where you start getting really
confused and scared.
And it all becomes a bit challenging.
So that's who I think could benefit from this
book.
Also, I would say anyone that's a visual learner,
and anyone that's kind of more like a tactile,
like, wants to like see...kind of make things
tangible type of learner.
I do have to say, you know, this book isn't
for everyone.
Not everyone's a visual learner.
And I totally appreciate that.
And that means that this book will appeal
to a certain type of learner, but not to another.
Now, let's get to the topic of who this book
is not for.
It's not for anyone that uses Git, and really
has their own mental model of how it works,
and it works for them.
And they never really struggle with understanding
things.
I mean, they don't need it.
It's not for anyone that's looking for an
advanced guide to Git, you know, that goes
over advanced features of Git, more niche
commands.
It's not for them.
That stuff is not in the book, so they'll
not get anything from it.
It's also not for anyone that's looking for
a resource that will teach them what their
Git workflow should be, or what best practices
should be.
In the book, I don't teach you, like, oh,
well, the best branching workflow is this,
and this, and this.
Or, yeah, I don't know, this is how you should
set things up.
Like I said, the book is not at all prescriptive.
And actually, to be honest, the rainbow project
is not a really realistic project of a software
project.
I mean, you're listing the colors of the rainbow.
That's not really what you're usually doing
when you're building software.
So for a lot of developers, for example, the
example in the book is not so realistic.
It's more about building that mental model.
Although I do have a second example in the
book, which is called the example book project,
which is a little bit more realistic, because
it uses storytelling to provide a bit more
of a realistic use of Git.
But again, it's not.
And the other thing is, anyone looking for
other best practices, like, how should I be
naming my branches?
What should I be including in a commit?
Let me think, what else?
So those kinds of things, I don't provide
any guidance on that.
Because, like I said, I focus on teaching
a mental model.
And those things are really up to...they're
really kind of dependent on your opinion,
on which company you work in, which sector
you work in, what your background is, what
you personally like in branch names, and in,
yeah...or commit messages.
So, it was not something that I wanted to
confuse people with and clutter up the book
with.
I think there's plenty of other resources
in the world that provide guidance on that.
And the final thing is that this book is not
a reference.
So it's really kind of a learning journey.
It's a hands-on learning journey.
But it's not the kind of book that you would
be like, oh, you know, each chapter...
I don't know, it's not a reference guide.
So, to be honest, the Git website is the best
reference.
I mean, it is a reference.
They have a reference.
So, Git-scm.com, you got a reference there.
And other people have built a reference.
So yeah, I think that's kind of who the book
is for and who the book isn't for.
Okay.
So, we've mentioned previously that the book 
is designed to be a sequential 
learning experience.
Start at the beginning, progress, especially
if you're new to Git.
But there's going to be people out there that
will definitely have the question of, how
much Git experience do I need if I'm going
to buy this book?
And what's the answer to that one?
Zero.
That's an easy answer.
I could just, like, zero.
I have nothing else to say.
No, zero, really, like I mentioned in the
very first chapter, we go over the process
of downloading Git, and kind of setting it
up, setting up like the basics.
And I even introduce the command line.
Like, I tell you, this is the app that is
the command line, open the command line.
This is the command prompt.
This is where you enter commands.
You write a command and you press enter.
And I introduce some, like, very basic commands
like CD, change directory, or LS, like, list
the files, the visible files.
I introduce the concept of visible files and
hidden files.
I introduce, like, I don't know, mkdirs, or
make directory.
Just a couple of super basic commands.
So, yeah, and we go from the very start.
Like, chapter two is, you know, introducing
that Git diagram.
And so, zero, zero, zero.
I user tested.
We'll get into that later.
But I literally gave this book to my brother,
my dad, people that are...well, at least my
brother, not at all in the tech space.
Or at least, you know, not developers of any
kind, at the moment, at least.
So, yeah, it's zero.
Brilliant.
We're gonna get to that now.
So people who get value from this book, no
Git experience is necessarily, none whatsoever.
Road tested with your dad and brother, amongst
other people.
And tells a sequential journey.
Anybody who is looking to understand the mental
model of Git, anybody who perhaps has been
using Git, but is a little bit less confident
around some of the operations.
Whether they're the more advanced ones like
rebase, or the spicy three-way merge, which
is absolutely what I'm always going to call
the three-way merge from this point forward
in my career, always going to prefix it with
spicy.
And anybody who just needs to brush up on
some of those underlying concepts, because
Git is very...
What are the words?
You need to build on top of the basics.
If you don't understand the basics in Git,
then the more advanced stuff, the more advanced
commands tend to be more challenging than
perhaps they would be if you had a good grasp
of the underlying mental model.
It's true.
Awesome.
Okay.
So let's stick with advanced topics.
Is there anything that you really, really,
really wanted to get into the book, but just,
you know, you've got to draw the line somewhere?
Is there anything that you're like, "Oh, I
really wanted to put that in, but I just..."
You know, you had a cut off for it.
That's a really good question.
And I've been asked this before.
But to be honest, I think I am in quite a
unique position, that unlike many other authors,
who had a lot more in their books, and needed
to cut down, or just, yeah, the books got
way too big.
I had a very clear idea of what the basics
were, maybe because I'd already made the online
course, which already had the basics.
And so, I didn't really have that situation.
I didn't have anything that I was like, "Oh,
but I really wish I could fit this in."
The only thing I would say maybe that I was
considering squeezing into one of the chapters
was stashing.
But I mean, it's not like a huge, massive
thing that I really, really, you know, was
like, "Oh, I can't believe this won't fit
in."
Because to be honest, you know, the book is
still pretty lean.
It's very minimalist.
So, if I had ultimately decided that this
is essential, I would have included it.
Actually, in my case, I think the pull request,
merge request chapter was actually not even
part of my original plan.
And I think later on, I realized, no, this
is really important.
I need to add this on.
So actually, my book was like too lean.
And I was, like...
I think you've been rebasing, I was kind of...
No, rebasing, I think I had from the beginning.
But yeah, I was like, super lean.
And I was, like, okay, but maybe I should
add a little bit extra.
So, I think, I felt that the most generous
thing that I could do for my readers, and
for my learners, was to be 
as simple and minimalist 
as possible, and just give the bare basics.
And in that way, just make it less overwhelming.
Because tech is so overwhelming.
There's just so much information, and so much
going on.
So if I could just create one learning experience,
which would not be overwhelming, I was like,
yes, I shall do this.
Fantastic.
Thank you.
So I'm wondering if in our audience today,
we might have some budding authors, other
people out there who perhaps want to author
a book.
I know I've co-authored a book.
So I absolutely appreciate the effort that
goes into the process and then some.
Do you have any advice for anybody who might
be listening, who's thinking, "Oh, yeah, I
know a thing.
I'm gonna write a book about that thing."
So anything I'm about to say is just gonna
come from my own experience.
So you never know, it might not apply to others.
And anything I'm gonna say is probably just
going to refer to technical book authors,
because I have not yet written another kind
of book.
So I don't want to say that I can speak on
that.
But for technical book potential authors,
I would say one of the things that I really
appreciated in my journey was, that I sort
of wrote this book as if it was an app.
Like, I made a prototype and then I user tested
that prototype.
And then I took all the feedback and I iterated.
And then I user tested again.
And then I took all the feedback, and I iterated.
And the first prototype was ugly.
It was very, very ugly.
And it was very rough.
And it was not at all the finished product.
I actually user tested when I just had four
chapters ready, because I thought, well, let
me check if this is making any sense to anyone.
Because if I've done four chapters, and it
doesn't make any sense, there's no point in
writing the other eight chapters.
Or, you know, it's better for me to figure
out what they are, what works for my audience,
before I write those other eight chapters.
So I had up to, like, 30 user testers throughout
the two years that I was working on this book.
And I think that was invaluable.
The experience of having a diverse user testing
audience.
I mean, it went from the ages of 18 to 60.
And from various professions, from all over
the world.
It was all remote user testing.
Wait, actually no, I also did some in person.
But most of it, almost all of it was remote.
So I got people from all over the world.
And it really did make my book a lot better.
There were a lot of things I needed to change.
I think sometimes, yeah, we just want to think
that we're like this genius that, like, can
create the best thing out of the outset.
And, like, oh, my God, my ideas are so good.
But sometimes, our creations need to have
that chemical reaction with the audience in
order to really become what they need.
Just one funny story, since we're at it.
At the beginning, I thought that my book would
actually...people would have, like, a pencil
case with them and paper, and they would actually
draw out the commits.
So in the beginning of the preface, I was
like, "Oh, you have to buy colored pencils,
and you should, like, follow along, and you
should draw the commits."
And when I did that user testing, nobody did
that.
And I had the colored pencils with me, I brought
them, and nobody did it.
So then I was like, okay, well, I guess this
isn't something...
You know, if somebody does want to do it,
they can.
But it wasn't something that made sense.
I mean, that's just a non-technical example.
But there were plenty of other things where,
yeah, I got feedback of, this doesn't make
sense to me, or you forgot about this.
I'm a Mac user.
So there were a lot of Windows users that
told me, like, "Hey, you need to mention this,
you need to mention that because this doesn't
make sense for me, or this doesn't apply to
me."
Or, you know, you need to simplify this.
You know, I'm not aware of this concept.
So, yeah, my monologue about user testing
and how good it is, is over now.
But yeah, I really recommend.
The importance of user testing.
And yeah, colored pencils, or not, in your
case.
Fantastic.
So we've spoken a little bit about your Udemy
course, we've spoken a little...well, a lot,
about your book.
What's next for you?
Is there anything else in the pipeline?
That's a good question, Helen.
I don't know what's next.
I do know that I've started working on a book.
I cannot share anything about it.
It shall remain a mystery.
People can...
You know, at the end, we'll talk about links
where people can find me.
But it may not end up being a technical book.
So I'm not sure yet.
I'm still exploring...
Well, I've started working on something.
But until I commit to a creative idea or a
creative project, I flirt with a lot of different
creative ideas and creative projects.
So, I definitely want to keep creating.
I love the process of creating something that
helps people and that explains things in a
simple way.
But what that next thing is going to be is
still under wraps.
So, we'll see.
For now, I'm just adjusting to my new technical
writer position, and enjoying kind of sharing
the journey I had with this book.
Wonderful.
A mystery.
Yes, a mystery.
I do like a mystery.
Maybe that's how I get people to follow me.
It's kind of self-serving.
If I make it mysterious, people have to come
and follow me to find out what it is when
I'm ready to share it.
I think that is the perfect segue.
So, if people want to find out about this
mystery in time, or learn more about your
book, or your courses, or whatever is coming
next for you, Anna, where should they go?
So the first thing I'll say is that I'm the
only  Anna Skoulikari on this planet.
So, just look me up,  Anna Skoulikari, two
Ns, A-N-N-A.
Last name S-K-O-U-L-I-K-A-R-I.
Just google me.
But other than that, I have a 
website, annaskoulikari.com.
So that is one good place.
The platform that I'm currently most active
on is LinkedIn.
So you can connect with me or follow me there.
And then other than that, you can find my
book all over the place, Amazon, and plenty
of other places.
You can find my online course on Udemy, at
the moment.
It's difficult to tell people where to find
you, because you always think, well, the social
media landscape changes all the time.
So this might not be relevant in a year or
two years from now.
And maybe I'll start using something else.
So I do have a Twitter.
I don't use it much.
Oh, I'm sorry, X.
Anyways, so I'd say my website and LinkedIn
are currently the best places to find out
more about me, and what I'm doing.
And then other than that, I just want to share
with the audience that I do have a link that
for the rest of 2024 is still going to be
active, which we can leave in the notes, which
gives people 30 day free access to the O'Reilly
online learning platform.
You can read my book, basically, in 30 days.
We can leave that in the notes.
And you actually have access to all the resources
on there.
If you want to take a peek at anything else,
feel free.
And it doesn't automatically subscribe, you
just get those 30 days, and then you can choose
whether you want to continue.
I think those are the best places.
Perfect.
And we will, of course, 
put all of that information 
in the show notes, including that link for
30 day access to the writing platform.
So I think that just about brings us to the
end of this interview.
So, Anna, do you have any final words that
you'd like to share today?
Oh, that's a good question.
Well, since the audience, there's going to
be a mix of junior developers, senior developers,
and various other people in the tech profession.
I'd say, if you yourself, maybe understand
Git, but you have a friend or anyone you know
that is struggling with it, feel free to recommend
them to take a peek at the book and see whether
it is the right learning journey and learning
resource for them.
It might be, it might not.
But if you do have anyone that is struggling
with Git, which many of us do, feel free to
kind of just share it with them, in case you
think it can serve them.
Fantastic.
Fantastic.
And I'd second that, especially with the 30
day free access.
I mean, that's a win-win.
You can check out the book.
I am fortunate enough to have this lovely
physical copy of it.
But, Anna, thank you.
Thank you for coming to this interview, for
sharing your knowledge and writing this book.
I've got a lot of value from it.
And I know that our audience will as well.
Thanks to the GOTO platform as well.
And yeah, thank you to you, the audience,
for tuning in and coming on this journey.
All the show notes will be available to you.
And that's it from us.
Thank you very much.
Bye.
Thanks, Helen.

# Document Title
CRDT Survey, Part 3: Algorithmic Techniques
Matthew Weidner | Feb 13th, 2024
Home | RSS Feed
Keywords: CRDTs, optimization, state-based CRDTs
    This blog post is Part 3 of a series.
        Part 1: Introduction
        Part 2: Semantic Techniques
        Part 3: Algorithmic Techniques
        Part 4: Further Topics
# Algorithmic Techniques
Let’s say you have chosen your collaborative app’s semantics in style of Part 2. That is, you’ve chosen a pure function that inputs an operation history and outputs the intended state of a user who is aware of those operations.
Here is a simple protocol to turn those semantics into an actual collaborative app:
    Each user’s state is a literal operation history, i.e., a set of operations, with each operation labeled by a Unique ID (UID).
    When a user performs an operation, they generate a new UID, then add the pair (id, op) to their local operation history.
    To synchronize their states, users share the pairs (id, op) however they like. For example, users could broadcast pairs as soon as they are created, periodically share entire histories peer-to-peer, or run a clever protocol to send a peer only the pairs that it is missing. Recipients always ignore redundant pairs (duplicate UIDs).
    Whenever a user’s local operation history is updated - either by a local operation or a remote message - they apply the semantics (pure function) to their new history, to yield the current app-visible state.
    Technicalities:
        It is the translated operations that get stored in operation histories and sent over the network. E.g., convert list indices to list CRDT positions before storing & sending.
        The history should also include causal ordering metadata - the arrows in Part 2’s operation histories. When sharing an operation, also share its incoming arrows, i.e., the UIDs of its immediate causal predecessors.
        Optionally enforce causal order delivery, by waiting to add a received operation to your local operation history until after you have added all of its immediate causal predecessors.
This post describes CRDT algorithmic techniques that help you implement more efficient versions of the simple protocol above. We start with some Prerequisites that are also useful in general distributed systems. Then Sync Strategies describes the traditional “types” of CRDTs - op-based, state-based, and others - and how they relate to the simple protocol.
The remaining sections describe specific algorithms. These algorithms are largely independent of each other, so you can skip to whatever interests you. Misc Techniques fills in some gaps from Part 2, e.g., how to generate logical timestamps. Optimized CRDTs describes nontrivial optimized algorithms, including classic state-based CRDTs.
# Table of Contents
    Prerequisites
        Replicas and Replica IDs • Unique IDs: Dots • Tracking Operations: Vector Clocks 1
    Sync Strategies
        Op-Based CRDTs • State-Based CRDTs • Other Sync Strategies
    Misc Techniques
        LWW: Lamport Timestamps • LWW: Hybrid Logical Clocks • Querying the Causal Order: Vector Clocks 2
    Optimized CRDTs
        List CRDTs • Formatting Marks (Rich Text) • State-Based Counter • Delta-State Based Counter • State-Based Unique Set • Delta-State Based Unique Set
# Prerequisites
# Replicas and Replica IDs
A replica is a single copy of a collaborative app’s state, in a single thread on a single device. For web-based apps, there is usually one replica per browser tab; when the user (re)loads a tab, a new replica is created.
You can also call a replica a client, session, actor, etc. However, a replica is not synonymous with a device or a user. Indeed, a user can have multiple devices, and a device can have multiple independently-updating replicas - for example, a user may open the same collaborative document in multiple browser tabs.
    In previous posts, I often said “user” out of laziness - e.g., “two users concurrently do X and Y”. But technically, I always meant “replica” in the above sense. Indeed, a single user might perform concurrent operations across different devices.
The importance of a replica is that everything inside a replica happens in a sequential order, without any concurrency between its own operations. This is the fundamental principle behind the next two techniques.
It is usually convenient to assign each replica a unique replica ID (client ID, session ID, actor ID), by generating a random string when the replica is created. The replica ID must be unique among all replicas of the same collaborative state, including replicas created concurrently, which is why they are usually random instead of “the highest replica ID so far plus 1”. Random UUIDs (v4) are a safe choice. You can potentially use fewer random bits (shorter replica IDs) if you are willing to tolerate a higher chance of accidental non-uniqueness (cf. the birthday problem).
    For reference, a UUID v4 is 122 random bits, a Collabs replicaID is 60 random bits (10 base64 chars), and a Yjs clientID is 32 random bits (a uint32).
Avoid the temptation to reuse a replica ID across replicas on the same device, e.g., by storing it in window.localStorage. That can cause problems if the user opens multiple tabs, or if there is a crash failure and the old replica did not record all of its actions to disk.
In Collabs: ReplicaIDs
# Unique IDs: Dots
Recall from Part 2 that to refer to a piece of content, you should assign it an immutable Unique ID (UID). UUIDs work, but they are long (32 chars) and don’t compress well.
Instead, you can use dot IDs: pairs of the form (replicaID, counter), where counter is a local variable that is incremented each time. So a replica with ID "n48BHnsi" uses the dot IDs ("n48BHnsi", 1), ("n48BHnsi", 2), ("n48BHnsi", 3), …
In pseudocode:
// Local replica ID.
const replicaID = <sufficiently long random string>;
// Local counter value (specific to this replica). Integer.
let counter = 0;
function newUID() {
    counter++;
    return (replicaID, counter);
}
The advantage of dot IDs is that they compress well together, either using plain GZIP or a dot-aware encoding. For example, a vector clock (below) represents a sequence of dots ("n48BHnsi", 1), ("n48BHnsi", 2), ..., ("n48BHnsi", 17) as the single map entry { "n48BHnsi": 17 }.
You have some flexibility for how you assign the counter values. For example, you can use a logical clock value instead of a counter, so that your UIDs are also logical timestamps for LWW. Or, you can use a separate counter for each component CRDT in a composed construction, instead of one for the whole replica. The important thing is that you never reuse a UID in the same context, where the two uses could be confused.
Example: An append-only log could choose to use its own counter when assigning events’ dot IDs. That way, it can store its state as a Map<ReplicaID, T[]>, mapping each replica ID to an array of that replica’s events indexed by (counter - 1). If you instead used a counter shared by all component CRDTs, then the arrays could have gaps, making a Map<ReplicaID, Map<number, T>> preferable.
    In previous blog posts, I called these “causal dots”, but I cannot find that name used elsewhere; instead, CRDT papers just use “dot”.
Collabs: Each transaction has an implicit dot ID (senderID, senderCounter).
Refs: Preguiça et al. 2010
# Tracking Operations: Vector Clocks 1
Vector clocks are a theoretical technique with multiple uses. In this section, I’ll focus on the simplest one: tracking a set of operations. (Vector Clocks 2 is later.)
Suppose a replica is aware of the following operations - i.e., this is its current local view of the operation history:
An operation history with labels ("A84nxi", 1), ("A84nxi", 2), ("A84nxi", 3), ("A84nxi", 4), ("bu2nVP", 1), ("bu2nVP", 2).
I’ve labeled each operation with a dot ID, like ("A84nxi", 2).
In the future, the replica might want to know which operations it is already aware of. For example:
    When the replica receives a new operation in a network message, it will look up whether it has already received that operation, and if so, ignore it.
    When a replica syncs with another collaborator (or a storage server), it might first send a description of the operations it’s already aware of, so that the collaborator can skip sending redundant operations.
One way to track the operation history is to store the operations’ unique IDs as a set: { ("A84nxi", 1), ("A84nxi", 2), ("A84nxi", 3), ("A84nxi", 4), ("bu2nVP", 1), ("bu2nVP", 2)}. But it is cheaper to store the “compressed” representation
{
    "A84nxi": 4,
    "bu2nVP": 2
}
This representation is called a vector clock. Formally, a vector clock is a Map<ReplicaID, number> that sends a replica ID to the maximum counter value received from that replica, where each replica assigns counters to its own operations in order starting at 1 (like a dot ID). Missing replica IDs implicitly map to 0: we haven’t received any operations from those replicas. The above example shows that a vector clock efficiently summarizes a set of operation IDs.
    The previous paragraph implicitly assumes that you process operations from each other replica in order: first ("A84nxi", 1), then ("A84nxi", 2), etc. That always holds when you enforce causal-order delivery. If you don’t, then a replica’s counter values might have gaps (1, 2, 4, 7, ...); you can still encode those efficiently, using a run-length encoding, or a vector clock plus a set of “extra” dot IDs (known as a dotted vector clock).
Like dot IDs, vector clocks are flexible. For example, instead of a per-replica counter, you could store the most recent logical timestamp received from each replica. That is a reasonable choice if each operation already contains a logical timestamp for LWW.
Collabs: CausalMessageBuffer
Refs: Baquero and Preguiça 2016; Wikipedia
# Sync Strategies
We now turn to sync strategies: ways to keep collaborators in sync with each other, so that they eventually see the same states.
# Op-Based CRDTs
An operation-based (op-based) CRDT keeps collaborators in sync by broadcasting operations as they happen. This sync strategy is especially useful for live collaboration, where users would like to see each others’ operations quickly.
Current state (op history) + single operation -> new state (op history including operation).
In the simple protocol at the top of this post, a user processes an individual operation by adding it to their operation history, then re-running the semantic function to update their app-visible state. An op-based CRDT instead stores a state that is (usually) smaller than the complete operation history, but it still contains enough information to render the app-visible state, and it can be updated incrementally in response to a received operation.
Example: The op-based counter CRDT from Part 1 has an internal state that is merely the current count. When a user receives (or performs) an inc() operation, they increment the count.
Formally, an op-based CRDT consists of:
    A set of allowed CRDT states that a replica can be in.
    A query that returns the app-visible state. (The CRDT state often includes extra metadata that is not visible to the rest of the app, such as LWW timestamps.)
    For each operation (insert, set, etc.):
        A prepare function that inputs the operation’s parameters and outputs a message describing that operation. An external protocol promises to broadcast this message to all collaborators. (Usually this message is just the translated form of the operation. prepare is allowed to read the current state but not mutate it.)
        An effect function that processes a message, updating the local state. An external protocol promises to call effect:
            Immediately for each locally-prepared message, so that local operations update the state immediately.
            Eventually for each remotely-prepared message, exactly once and (optionally) in causal order.
    In addition to updating their internal state, CRDT libraries’ effect functions usually also emit events that describe how the state changed. Cf. Views in Part 2.
To claim that an op-based CRDT implements a given CRDT semantics, you must prove that the app-visible state always equals the semantics applied to the set of operations effected so far.
    As an example, let’s repeat the op-based unique set CRDT from Part 2.
        Per-user CRDT state: A set of pairs (id, x).
        Query: Return the CRDT state directly, since in this case, it coincides with the app-visible state.
        Operation add:
            prepare(x): Generate a new UID id, then return the message ("add", (id, x)).
            effect("add", (id, x)): Add (id, x) to your local state.
        Operation delete:
            prepare(id): Return the message ("delete", id).
            effect("delete", id): Delete the pair with the given id from your local state, if it is still present.
    It is easy to check that this op-based CRDT has the desired semantics: at any time, the query returns the set of pairs (id, x) such that you have an effected an add(id, x) operation but no delete(id) operations.
    Observe that the CRDT state is a lossy representation of the operation history: we don’t store any info about delete operations or deleted add operations.
How can the “external protocol” (i.e., the rest of the app) guarantee that messages are effected at-most-once and in causal order? Using a history-tracking vector clock:
    On each replica, store a vector clock tracking the operations that have been effected so far.
    When a replica asks to send a prepared message, attach a new dot ID to that message before broadcasting it. Also attach the dot IDs of its immediate causal predecessors.
    When a replica receives a message:
        Check if its dot ID is redundant, according to the local vector clock. If so, stop.
        Check if the immediate causal predecessors’ dot IDs have been effected, according to the local vector clock. If not, block until they are.
        Deliver the message to effect and update the local vector clock. Do the same for any newly-unblocked messages.
To ensure that messages are eventually delivered at-least-once to each replica (the other half of exactly-once), you generally need some help from the network. E.g., have a server store all messages and retry delivery until every client confirms receipt.
As a final note, suppose that two users concurrently perform operations o and p. You are allowed to deliver their op-based messages to effect in either order without violating the causal-order delivery guarantee. Semantically, the two delivery orders must result in equivalent internal states: both results correspond to the same operation history, containing both o and p. Thus for an op-based CRDT, concurrent messages commute.
Conversely, you can prove that if an algorithm has the API of an op-based CRDT and concurrent messages commute, then its behavior corresponds to some CRDT semantics (i.e., some pure function of the operation history). This leads to the traditional definition of an op-based CRDT in terms of commuting concurrent operations. Of course, if you only prove commutativity, there is no guarantee that the corresponding semantics are reasonable in the eyes of your users.
Collabs: sendCRDT and receiveCRDT in PrimitiveCRDT
Refs: Shapiro et al. 2011a
# State-Based CRDTs
A state-based CRDT keeps users in sync by occasionally exchanging entire states, “merging” their operation histories. This sync strategy is useful in peer-to-peer networks (peers occasionally exchange states in order to bring each other up-to-date) and for the initial sync between a client and a server (the client merges its local state with the server’s latest state, and vice-versa).
Current state (op history) + other state (overlapping op history) -> merged state (union of op histories).
In the simple protocol at the top of this post, the “entire state” is the literal operation history, and merging is just the set-union of operations (using the UIDs to filter duplicates). A state-based CRDT instead stores a state that is (usually) smaller than the complete operation history, but it still contains enough information to render the app-visible state, and it can be “merged” with another state.
Formally, a state-based CRDT consists of:
    A set of allowed CRDT states that a replica can be in.
    A query that returns the app-visible state. (The CRDT state often includes extra metadata that is not visible to the rest of the app, such as LWW timestamps.)
    For each operation, a state mutator that updates the local state.
    A merge function that inputs two states and outputs a “merged” state. The app using the CRDT may set local state = merge(local state, other state) at any time, where the other state usually comes from a remote collaborator or storage.
To claim that a state-based CRDT implements a given CRDT semantics, you must prove that the app-visible state always equals the semantics applied to the set of operations that contribute to the current state. Here an operation “contributes” to the output of its state mutator, plus future states resulting from that state (e.g., the merge of that state with another).
    As an example, let’s repeat just the state-based part of the LWW Register from Part 2.
        Per-user state: state = { value, time }, where time is a logical timestamp.
        Query: Return state.value.
        Operation set(newValue): Set state = { value: newValue, time: newTime }, where newTime is the current logical time.
        Merge in other state: Pick the state with the greatest logical timestamp. That is, if other.time > state.time, set state = other.
    It is easy to check that this state-based CRDT has the desired semantics: at any time, the query returns the value corresponding to the set operation with the greatest logical timestamp that contributes to the current state.
As a final note, observe that for any CRDT states s, t, u, the following algebraic rules hold, because the same set of operations contributes to both sides of each equation:
    (Idempotence) merge(s, s) = s.
    (Commutativity) merge(s, t) = merge(t, s).
    (Associativity) merge(s, (merge(t, u))) = merge(merge(s, t), u).
Thus for a state-based CRDT, the merge function is Associative, Commutative, and Idempotent (ACI).
Conversely, you can prove that if an algorithm has the API of a state-based CRDT and it satisfies ACI, then its behavior corresponds to some CRDT semantics (i.e., some pure function of the operation history). This leads to the traditional definition of a state-based CRDT in terms of an ACI merge function. Of course, if you only prove these algebraic rules, there is no guarantee that the corresponding semantics are reasonable in the eyes of your users.
Collabs: saveCRDT and loadCRDT in PrimitiveCRDT
Refs: Shapiro et al. 2011a
# Other Sync Strategies
In a real collaborative app, it is inconvenient to choose op-based or state-based synchronization. Instead, it’s nice to use both, potentially within the same session.
Example: When the user launches your app, first do a state-based sync with a storage server to become in sync. Then use op-based messages over TCP to stay in sync until the connection drops.
Thus hybrid op-based/state-based CRDTs that support both sync strategies are popular in practice. Typically, these look like either state-based CRDTs with op-based messages tacked on (Yjs, Collabs), or they use an op-based CRDT alongside a complete operation history (Automerge).
    To perform a state-based merge in the latter approach, you look through the received state’s history for operations that are not already in your history, and deliver those to the op-based CRDT. This approach is simple, and it comes with a built-in version history, but it requires more effort to make efficient (as Automerge has been pursuing).
Other sync strategies use optimized peer-to-peer synchronization. Traditionally, peer-to-peer synchronization uses state-based CRDTs: each peer sends a copy of its own state to the other peer, then merges in the received state. This is inefficient if the states overlap a lot - e.g., the two peers just synced one minute ago and have only updated their states slightly since then. Optimized protocols like Yjs’s sync potocol or Byzantine causal broadcast instead use back-and-forth messages to determine what info the other peer is missing and send just that.
    For academic work on hybrid or optimized sync strategies, look up delta-state based CRDTs (also called delta CRDTs). These are like hybrid CRDTs, with the added technical requirement that op-based messages are themselves states (in particular, they are input to the state-based merge function instead of a separate effect function). Note that some papers focus on novel sync strategies, while others focus on the orthogonal problem of how to tolerate non-causally-ordered messages.
Collabs: Updates and Sync - Patterns
Refs: Yjs document updates; Almeida, Shoker, and Baquero 2016; Enes et al. 2019
# Misc Techniques
The rest of this post describes specific algorithms. We start with miscellaneous techniques that are needed to implement some of the semantics from Part 2: two kinds of logical timestamps for LWW, and ways to query the causal order. These are all traditional distributed systems techniques that are not specific to CRDTs.
# LWW: Lamport Timestamps
Recall that you should use a logical timestamp instead of wall-clock time for Last-Writer Wins (LWW) values. A Lamport timestamp is a simple and common logical timestamp, defined by:
    Each replica stores a clock value time, an integer that is initially 0.
    Whenever you perform an LWW set operation, increment time and attach its new value to the operation, as part of a pair (time, replicaID). This pair is called a Lamport timestamp.
    Whenever you receive a Lamport timestamp from another replica as part of an operation, set time = max(time, received time).
    The total order on Lamport timestamps is given by: (t1, replica1) < (t2, replica2) if t1 < t2 or (t1 = t2 and replica1 < replica2). That is, the operation with a greater time “wins”, with ties broken using an arbitrary order on replica IDs.
Operations A-F with arrows A to B, A to E, B to C, C to D, C to F. The labels are: (1, "A84nxi"); (2, "A84nxi"); (3, "A84nxi"); (5, "A84nxi"); (2, "bu2nVP"); (4, "bu2nVP").
Figure 1. An operation history with each operation labeled by a Lamport timestamp.
Lamport timestamps have two important properties (mentioned in Part 2):
    If o < p in the causal order, then (o's Lamport timestamp) < (p's Lamport timestamp). Thus a new LWW set always wins over all causally-prior sets.
        Note that the converse does not hold: it’s possible that (q's Lamport timestamp) < (r's Lamport timestamp) but q and r are concurrent.
    Lamport timestamps created by different users are always distinct (because of the replicaID tiebreaker). Thus the winner is never ambiguous.
Collabs: lamportTimestamp
Refs: Lamport 1978; Wikipedia
# LWW: Hybrid Logical Clocks
Hybrid logical clocks are another kind of logical timestamp that combine features of Lamport timestamps and wall-clock time. I am not qualified to write about these, but Jared Forsyth gives a readable description here: https://jaredforsyth.com/posts/hybrid-logical-clocks/.
# Querying the Causal Order: Vector Clocks 2
One of Part 2’s “Other Techniques” was Querying the Causal Order. For example, an access-control CRDT could include a rule like “If Alice performs an operation but an admin banned her concurrently, then treat Alice’s operation as if it had not happened”.
I mentioned in Part 2 that I find this technique too complicated for practical use, except in some special cases. Nevertheless, here are some ways to implement causal-order queries.
Formally, our goal is: given two operations o and p, answer the query “Is o < p in the causal order?”. More narrowly, a CRDT might query whether o and p are concurrent, i.e., neither o < p nor p < o.
Recall from above that a vector clock is a map that sends a replica ID to the maximum counter value received from that replica, where each replica assigns counters to its own operations in order starting at 1 (like a dot ID). Besides storing a vector clock on each replica, we can also attach a vector clock to each operation: namely, the sender’s vector clock at the time of sending. (The sender’s own entry is incremented to account for the operation itself.)
Operations A-F with arrows A to B, A to E, B to C, C to D, C to F. The labels are: ("A84nxi", 1) / { A84nxi: 1 }; ("A84nxi", 2) / { A84nxi: 2 }; ("A84nxi", 3) / { A84nxi: 3 }; ("A84nxi", 4) / { A84nxi: 4, bu2nVP: 2 }; ("bu2nVP", 1) / { A84nxi: 1, bu2nVP: 1 }; ("bu2nVP", 2) / { A84nxi: 3, bu2nVP: 2 }.
Figure 2. An operation history with each operation labeled by its dot ID (blue italics) and vector clock (red normal text).
Define a partial order on vector clocks by: v < w if for every replica ID r, v[r] <= w[r], and for at least one replica ID, v[r] < w[r]. (If r is not present in a map, treat its value as 0.) Then it is a classic result that the causal order on operations matches the partial order on their vector clocks. Thus storing each operation’s vector clock lets you query the causal order later.
Example: In the above diagram, { A84nxi: 1, bu2nVP: 1 } < { A84nxi: 4, bu2nVP: 2 }, matching the causal order on their operations. Meanwhile, { A84nxi: 1, bu2nVP: 1 } and { A84nxi: 2 } are incomparable, matching the fact that their operations are concurrent.
Often you only need to query the causal order on new operations. That is, you just received an operation p, and you want to compare it to an existing operation o. For this, it suffices to know o’s dot ID (replicaID, counter): If counter <= p.vc[replicaID], then o < p, else they are concurrent. Thus in this case, you don’t need to store each operation’s vector clock, just their dot IDs (though you must still send vector clocks over the network).
    The above discussion changes slightly if you do not assume causal order delivery. See Wikipedia’s update rules.
We have a performance problem: The size of a vector clock is proportional to the number of past replicas. In a collaborative app, this number tends to grow without bound: each browser tab creates a new replica, including refreshes. Thus if you attach a vector clock to each op-based message, your network usage also grows without bound.
Some workarounds:
    Instead of attaching the whole vector clock to each op-based message, just attached the UIDs of the operation’s immediate causal predecessors. (You are probably attaching these anyway for causal-order delivery.) Then on the receiver side, look up the predecessors’ vector clocks in your stored state, take their entry-wise max, add one to the sender’s entry, and store that as the operation’s vector clock.
    Same as 1, but instead of storing the whole vector clock for each operation, just store its immediate causal predecessors - the arrows in the operation history. This uses less space, and it still contains enough information to answer causal order queries: o < p if and only if there is a path of arrows from o to p. However, I don’t know of a way to perform those queries quickly.
    Instead of referencing the causal order directly, the sender can list just the “relevant” o < p as part of p’s op-based message. For example, when you set the value of a multi-value register, instead of using a vector clock to indicate which set(x) operations are causally prior, just list the UIDs of the current multi-values (cf. the multi-value register on top of a unique set).
Collabs: vectorClock
Refs: Baquero and Preguiça 2016; Wikipedia; Automerge issue discussing workarounds
# Optimized CRDTs
We now turn to optimizations. I focus on algorithmic optimizations that change what state you store and how you access it, as opposed to low-level code tricks. Usually, the optimizations reduce the amount of metadata that you need to store in memory and on disk, at least in the common case.
These optimizations are the most technical part of the blog series. You may wish to skip them for now and come back only when you are implementing one, or trust someone else to implement them in a library.
# List CRDTs
I assume you’ve understood Lists and Text Editing from Part 2.
There are too many list CRDT algorithms and optimizations to survey here, but I want to briefly introduce one key problem and solution.
When you use a text CRDT to represent a collaborative text document, the easy way to represent the state is as an ordered map (list CRDT position) -> (text character). Concretely, this map could be a tree with one node per list CRDT position, like in Fugue: A Basic List CRDT.
Example of a Fugue tree.
Figure 3. Example of a Fugue tree with corresponding text "abcde". Each node's UID is a dot.
In such a tree, each tree node contains at minimum (1) a UID and (2) a pointer to its parent node. That is a lot of metadata for a single text character! Plus, you often need to store this metadata even for deleted characters (tombstones).
Here is an optimization that dramatically reduces the metadata overhead in practice:
    When a replica inserts a sequence of characters from left to right (the common case), instead of creating a new UID for each character, only create a UID for the leftmost character.
    Store the whole sequence as a single object (id, parentId etc, [char0, char1, ..., charN]). So instead of one tree node per character, your state has one tree node per sequence, storing an array of characters.
    To address individual characters, use list CRDT positions of the form (id, 0), (id, 1), …, (id, N).
It’s possible to later insert characters in the middle of a sequence, e.g., between char1 and char2. That’s fine; the new characters just need to indicate the corresponding list CRDT positions (e.g. “I am a left child of (id, 2)”).
Applying this optimization to Fugue gives you trees like so, where only the filled nodes are stored explicitly (together with their children’s characters):
Example of an optimized Fugue tree.
Figure 4. Example of an optimized Fugue tree with corresponding text "abcdefg".
Collabs: Waypoints in CTotalOrder
Refs: Yu 2012; Jahns 2020 (Yjs blog post)
# Formatting Marks (Rich Text)
Recall the inline formatting CRDT from Part 2. Its internal CRDT state is an append-only log of formatting marks
type Mark = {
    key: string;
    value: any;
    timestamp: LogicalTimestamp;
    start: { pos: Position, type: "before" | "after" }; // type Anchor
    end: { pos: Position, type: "before" | "after" }; // type Anchor
}
Its app-visible state is the view of this log given by: for each character c, for each format key key, find the mark with the largest timestamp satisfying
    mark.key = key, and
    the interval (mark.start, mark.end) contains c’s position.
Then c’s format value at key is mark.value.
For practical use, we would like a view that represents the same state but uses less memory. In particular, instead of storing per-character formatting info, it should look more like a Quill delta. E.g., the Quill delta representing “Quick brown fox” is
{
    ops: [
        { insert: "Quick " },
        { insert: "brow", attributes: { bold: true, italic: true } },
        { insert: "n fox", attributes: { italic: true } }
    ]
}
Here is such a view. Its state is a map: Map<Anchor, Mark[]>, given by:
    For each anchor that appears as the start or end of any mark in the log,
        The value at anchor contains pointers to all marks that start at or strictly contain anchor. That is, { mark in log | mark.start <= anchor < mark.end }.
Given this view, it is easy to look up the format of any particular character. You just need to go left until you reach an anchor that is in map, then interpret map.get(anchor) in the usual way: for each key, find the LWW winner at key and use its value. (If you reach the beginning of the list, the character has no formatting.)
I claim that with sufficient coding effort, you can also do the following tasks efficiently:
    Convert the whole view into a Quill delta or similar rich-text-editor state.
    Update the view to reflect a new mark added to the log.
    After updating the view, emit events describing what changed, in a form like Collabs’s RichTextFormatEvent:
type RichTextFormatEvent = {
    // The formatted range is [startIndex, endIndex).
    startIndex: number;
    endIndex: number;
    key: string;
    value: any; // null if unformatted
    previousValue: any;
    // The range's complete new format.
    format: { [key: string]: any };
}
Let’s briefly discuss Task 2; there’s more detail in the Peritext essay. When a new mark mark is added to the log:
    If mark.start is not present in map, go to the left of it until you reach an anchor prev that is in map, then do map.set(mark.start, copy of map.get(prev)). (If you reach the beginning of the list, do map.set(mark.start, []).)
    If mark.end is not present in map, do likewise.
    For each entry (anchor, array) in map such that mark.start <= anchor < mark.end, append mark to array.
Some variations on this section:
    Collabs represents the Map<Anchor, Mark[]> literally using a LocalList - a local data structure that lets you build an ordered map on top of a separate list CRDT’s positions. Alternatively, you can store each Mark[] inline with the list CRDT, at its anchor’s location; that is how the Peritext essay does it.
    When saving the state to disk, you can choose whether to save the view, or forget it and recompute it from the mark log on next load. Likewise for state-based merging: you can try to merge the views directly, or just process the non-redundant marks one at a time.
    In each map value (a Mark[]), you can safely forget marks that have LWW-lost to another mark in the same array. Once a mark has been deleted from every map value, you can safely forget it from the log.
Collabs: CRichText; its source code shows all three tasks
Refs: Litt et al. 2021 (Peritext)
# State-Based Counter
The easy way to count events in a collaborative app is to store the events in an append-only log or unique set. This uses more space than the count alone, but you often want that extra info anyway - e.g., to display who liked a post, in addition to the like count.
Nonetheless, the optimized state-based counter CRDT is both interesting and traditional, so let’s see it.
The counter’s semantics are as in Part 1’s passenger counting example: its value is the number of +1 operations in the history, regardless of concurrency.
You can obviously achieve this semantics by storing an append-only log of +1 operations. To merge two states, take the union of log entries, skipping duplicate UIDs.
    In other words, store the entire operation history, following the simple protocol from the top of this post.
Suppose the append-only log uses dot IDs as its UIDs. Then the log’s state will always look something like this:
[
    ((a6X7fx, 1), "+1"), ((a6X7fx, 2), "+1"), ((a6X7fx, 3), "+1"), ((a6X7fx, 4), "+1"),
    ((bu91nD, 1), "+1"), ((bu91nD, 2), "+1"), ((bu91nD, 3), "+1"),
    ((yyn898, 1), "+1"), ((yyn898, 2), "+1")
]
You can compress this state by storing, for each replicaID, only the range of dot IDs received from that replica. For example, the above log compresses to
{
    a6X7fx: 4,
    bu91nD: 3,
    yyn898: 2
}
This is the same trick we used in Vector Clocks 1.
Compressing the log in this way leads to the following algorithm, the state-based counter CRDT.
    Per-user state: A Map<ReplicaID, number>, mapping each replicaID to the number of +1 operations received from that replica. (Traditionally, this state is called a vector instead of a map.)
    App-visible state (the count): Sum of the map values.
    Operation +1: Add 1 to your own map entry, treating a missing entry as 0.
    Merge in other state: Take the entry-wise max of values, treating missing entries as 0. That is, for all r, set this.state[r] = max(this.state[r] ?? 0, other.state[r] ?? 0).
For example:
// Starting local state:
{
    a6X7fx: 2, // Implies ops ((a6X7fx, 1), "+1"), ((a6X7fx, 2), "+1")
    bu91nD: 3,
}
// Other state:
{
    a6X7fx: 4, // Implies ops ((a6X7fx, 1), "+1"), ..., ((a6X7fx, 4), "+1")
    bu91nD: 1,
    yyn898: 2
}
// Merged result:
{
    a6X7fx: 4, // Implies ops ((a6X7fx, 1), "+1"), ..., ((a6X7fx, 4), "+1"): union of inputs
    bu91nD: 3,
    yyn898: 2
}
You can generalize the state-based counter to handle +x operations for arbitrary positive values x. However, to handle both positive and negative additions, you need to use two counters: P for positive additions and N for negative additions. The actual value is (P's value) - (N's value). This is the state-based PN-counter.
Collabs: CCounter
Refs: Shapiro et al. 2011a
# Delta-State Based Counter
You can modify the state-based counter CRDT to also support op-based messages:
    When a user performs a +1 operation, broadcast its dot ID (r, c).
    Recipients add this dot their compresed log map, by setting map[r] = max(map[r], c).
This hybrid op-based/state-based CRDT is called the delta-state based counter CRDT.
Technically, the delta-state based counter CRDT assumes causal-order delivery for op-based messages. Without this assumption, a replica’s uncompressed log might contain gaps like
[
    ((a6X7fx, 1), "+1"), ((a6X7fx, 2), "+1"), ((a6X7fx, 3), "+1"), ((a6X7fx, 6), "+1")
]
which we can’t represent as a Map<ReplicaID, number>.
    You could argue that the operation ((a6X7fx, 6), "+1") lets you “infer” the prior operations ((a6X7fx, 4), "+1") and ((a6X7fx, 5), "+1"), hence you can just set the map entry to { a6X7fx: 6 }. However, this will give an unexpected counter value if those prior operations were deliberately undone, or if they’re tied to some other change that can’t be inferred (e.g., a count of comments vs the actual list of comments).
Luckily, you can still compress ranges within the dot IDs that you have received. For example, you could use a run-length encoding:
{
    a6X7fx: [1 through 3, 6 through 6]
}
or a map plus a set of “extra” dot IDs:
{
    map: {
        a6X7fx: 3
    },
    dots: [["a6X7fx", 6]]
}
This idea leads to a second delta-state based counter CRDT. Its state-based merge algorithm is somewhat complicated, but it has a simple spec: decompress both inputs, take the union, and re-compress.
Refs: Almeida, Shoker, and Baquero 2016
# State-Based Unique Set
Here is a straightforward state-based CRDT for the unique set:
    Per-user state:
        A set of elements (id, x), which is the set’s literal (app-visible) state.
        A set of tombstones id, which are the UIDs of all deleted elements.
    App-visible state: Return elements.
    Operation add(x): Generate a new UID id, then add (id, x) to elements.
    Operation delete(id): Delete the pair with the given id from elements, and add id to tombstones.
    State-based merge: To merge in another user’s state other = { elements, tombstones },
        For each (id, x) in other.elements, if it is not already present in this.elements and id is not in this.tombstones, add (id, x) to this.elements.
        For each id in other.tombstones, if it is not already present in this.tombstones, add id to this.tombstones and delete the pair with the given id from this.elements (if present).
For example:
// Starting local state:
{
    elements: [ (("A84nxi", 1), "milk"), (("A84nxi", 3), "eggs") ],
    tombstones: [ ("A84nxi", 2), ("bu2nVP", 1), ("bu2nVP", 2) ]
}
// Other state:
{
    elements: [
        (("A84nxi", 3), "eggs"), (("bu2nVP", 1), "bread"), (("bu2nVP", 2), "butter"),
        (("bu2nVP", 3), "cereal")
    ],
    tombstones: [ ("A84nxi", 1), ("A84nxi", 2) ]
}
// Merged result:
{
    elements: [ (("A84nxi", 3), "eggs"), (("bu2nVP", 3), "cereal") ],
    tombstones: [ ("A84nxi", 1), ("A84nxi", 2), ("bu2nVP", 1), ("bu2nVP", 2) ]
}
The problem with this straightforward algorithm is the tombstone set: it stores a UID for every deleted element, potentially making the CRDT state much larger than the app-visible state.
Luckily, when your UIDs are dot IDs, you can use a “compression” trick similar to the state-based counter CRDT: in place of the tombstone set, store the range of dot IDs received from each replica (deleted or not), as a Map<ReplicaID, number>. That is, store a modified vector clock that only counts add operations. Any dot ID that lies within this range, but is not present in elements, must have been deleted.
For example, the three states above compress to:
// Starting local state:
{
    elements: [ (("A84nxi", 1), "milk"), (("A84nxi", 3), "eggs") ],
    vc: { A84nxi: 3, bu2nVP: 2 }
}
// Other state:
{
    elements: [
        (("A84nxi", 3), "eggs"), (("bu2nVP", 1), "bread"), (("bu2nVP", 2), "butter"),
        (("bu2nVP", 3), "cereal")
    ],
    vc: { A84nxi: 3, bu2nVP: 3 }
}
// Merged result:
{
    elements: [ (("A84nxi", 3), "eggs"), (("bu2nVP", 3), "cereal") ],
    vc: { A84nxi: 3, bu2nVP: 3 }
}
Compressing the tombstone set in this way leads to the following algorithm, the optimized state-based unique set:
    Per-user state:
        A set of elements (id, x) = ((r, c), x).
        A vector clock vc: Map<ReplicaID, number>.
        A local counter counter, used for dot IDs.
    App-visible state: Return elements.
    Operation add(x): Generate a new dot id = (local replicaID, ++counter), then add (id, x) to elements. Also increment vc[local replicaID].
    Operation delete(id): Merely delete the pair with the given id from elements.
    State-based merge: To merge in another user’s state other = { elements, vc },
        For each ((r, c), x) in other.elements, if it is not already present in this.elements and c > this.vc[r], add ((r, c), x) to this.elements. (It’s new and has not been deleted locally.)
        For each entry (r, c) in other.vc, for each pair ((r, c'), x) in this.elements, if c >= c' and the pair is not present in other.elements, delete it from this.elements. (It must have been deleted from the other state.)
        Set this.vc to the entry-wise max of this.vc and other.vc, treating missing entries as 0. That is, for all r, set this.vc[r] = max(this.vc[r] ?? 0, other.vc[r] ?? 0).
    You can re-use the same vector clock that you use for tracking operations, if your unique set’s dot IDs use the same counter. Nitpicks:
        Your unique set might skip over some dot IDs, because they are used for other operations; that is fine.
        If a single operation can add multiple elements at once, consider using UIDs of the form (dot ID, within-op counter) = (replicaID, per-op counter, within-op counter).
The optimized unique set is especially important because you can implement many other CRDTs on top, which are then also optimized (they avoid tombstones). In particular, Part 2 describes unique set algorithms for the multi-value register, multi-value map, and add-wins set (all assuming causal-order delivery). You can also adapt the optimized unique set to manage deletions in the unique set of CRDTs.
Collabs: CMultiValueMap, CSet
Refs: Based on the Optimized OR-Set from Bieniusa et al. 2012
# Delta-State Based Unique Set
Similar to the second delta-state based counter CRDT, you can create a delta-state based unique set that is a hybrid op-based/state-based CRDT and allows non-causal-order message delivery. I’ll leave it as an exercise.
Refs: Causal δ-CRDTs in Almeida, Shoker, and Baquero 2016
# Conclusion
The last two posts surveyed the two “topics” from Part 1:
    Semantics: An abstract description of what a collaborative app’s state should be, given its concurrency-aware operation history.
    Algorithms: Algorithms to efficiently compute the app’s state in specific, practical situations.
Together, they covered much of the CRDT theory that I know and use. I hope that you now know it too!
However, there are additional CRDT ideas outside my focus area. I’ll give a bibliography for those in the next and final post, Part 4: Further Topics.
    This blog post is Part 3 of a series.
        Part 1: Introduction
        Part 2: Semantic Techniques
        Part 3: Algorithmic Techniques
        Part 4: Further Topics
Home • Matthew Weidner • PhD student at CMU CSD • mweidner037 [at] gmail.com • @MatthewWeidner3 • LinkedIn • GitHub

Sym·poly·mathesy
by Chris Krycho
jj init
What if we actually could replace Git? Jujutsu might give us a real shot.
Assumed audience: People who have worked with Git or other modern version control systems like Mercurial, Darcs, Pijul, Bazaar, etc., and have at least a basic idea of how they work.
Jujutsu is a new version control system from a software engineer at Google, where it is on track to replace Google’s existing version control systems (historically: Perforce, Piper, and Mercurial). I find it interesting both for the approach it takes and for its careful design choices in terms of both implementation details and user interface. It offers one possible answer to a question I first started asking most of a decade ago: What might a next-gen version control system look like — one which actually learned from the best parts of all of this generation’s systems, including Mercurial, Git, Darcs, Fossil, etc.?
To answer that question, it is important to have a sense of what those lessons are. This is trickier than it might seem. Git has substantially the most “mind-share” in the current generation; most software developers learn it and use it not because they have done any investigation of the tool and its alternatives but because it is a de facto standard: a situation which arose in no small part because of its “killer app” in the form of GitHub. Developers who have been around for more than a decade or so have likely seen more than one version control system — but there are many, many developers for whom Git was their first and, so far, last VCS.
The problems with Git are many, though. Most of all, its infamously terrible command line interface results in a terrible user experience. In my experience, very few working developers have a good mental model for Git. Instead, they have a handful of commands they have learned over the years: enough to get by, and little more. The common rejoinder is that developers ought to learn how Git works internally — that everything will make more sense that way.
This is nonsense. Git’s internals are interesting on an implementation level, but frankly add up to an incoherent mess in terms of a user mental model. This is a classic mistake for software developers, and one I have fallen prey to myself any number of times. I do not blame the Git developers for it, exactly. No one should have to understand the internals of the system to use it well, though; that is a simple failure of software design. Moreover, even those internals do not particularly cohere. The index, the number of things labeled “-ish” in the glossary, the way that a “detached HEAD” interacts with branches, the distinction between tags and branches, the important distinctions between commits, refs, and objects… It is not that any one of those things is bad in isolation, but as a set they do not amount to a mental model I can describe charitably. Put in programming language terms: One of the reasons the “surface syntax” of Git is so hard is that its semantics are a bit confused, and that inevitably shows up in the interface to users.
Still, a change in a system so deeply embedded in the software development ecosystem is not cheap. Is it worth the cost of adoption? Well, Jujutsu has a trick up its sleeve: there is no adoption cost. You just install it — brew install jj will do the trick on macOS — and run a single command in an existing Git repository, and… that’s it. (“There is no step 3.”) I expect that mode will always work, even though there will be a migration step at some point in the future, when Jujutsu’s own, non-Git backend becomes a viable — and ultimately the recommended — option. I am getting ahead of myself though. The first thing to understand is what Jujutsu is, and is not.
Jujutsu is two things:
    It is a new front-end to Git. This is by far the less interesting of the two things, but in practice it is a substantial part of the experience of using the tool today. In this regard, it sits in the same notional space as something like gitoxide. Jujutsu’s jj is far more usable for day to day work than gitoxide’s gix and ein so far, though, and it also has very different aims. That takes us to:
    It is a new design for distributed version control. This is by far the more interesting part. In particular, Jujutsu brings to the table a few key concepts — none of which are themselves novel, but the combination of which is really nice to use in practice:
        Changes are distinct from revisions: an idea borrowed from Mercurial, but quite different from Git’s model.
        Conflicts are first-class items: an idea borrowed from Pijul and Darcs.
        The user interface is not only reasonable but actually really good: an idea borrowed from… literally every VCS other than Git.
The combo of those means that you can use it today in your existing Git repos, as I have been for the past six months, and that it is a really good experience using it that way. (Better than Git!) Moreover, given it is being actively developed at and by Google for use as a replacement for its current custom VCS setup, it seems like it has a good future ahead of it. Net: at a minimum you get a better experience for using Git with it. At a maximum, you get an incredibly smooth and shallow on-ramp to what I earnestly hope is the future of version control.
Jujutsu is not trying to do every interesting thing that other Git-alternative DVCS systems out there do. Unlike Pijul, for example, it does not work from a theory of patches such that the order changes are applied is irrelevant. However, as I noted above and show in detail below, jj does distinguish between changes and revisions, and has first-class support for conflicts, which means that many of the benefits of Pijul’s handling come along anyway. Unlike Fossil, Jujutsu is also not trying to be an all-in-one tool. Accordingly: It does not come with a replacement for GitHub or other such “forges”. It does not include bug tracking. It does not support chat or a forum or a wiki. Instead, it is currently aimed at just doing the base VCS operations well.
Finally, there is a thing Jujutsu is not yet: a standalone VCS ready to use without Git. It supports its own, “native” backend for the sake of keeping that door open for future capabilities, and the test suite exercises both the Git and the “native” backend, but the “native” one is not remotely ready for regular use. That said, this one I do expect to see change over time!
One of the really interesting bits about picking up Jujutsu is realizing just how weirdly Git has wired your brain, and re-learning how to think about how a version control system can work. It is one thing to believe — very strongly, in my case! — that Git’s UI design is deeply janky (and its underlying model just so-so); it is something else to experience how much better a VCS UI can be (even without replacing the underlying model!).
Yoda saying “You must unlearn what you have learned.”
Time to become a Jedi Knight. Jujutsu Knight? Jujutsu Master? Jujutsu apprentice, at least. Let’s dig in!
Outline
Using Jujutsu
That is all interesting enough philosophically, but for a tool that, if successful, will end up being one of a software developer’s most-used tools, there is an even more important question: What is it actually like to use?
Setup is painless. Running brew install jj did everything I needed. As with most modern Rust-powered CLI tools,1 Jujutsu comes with great completions right out of the box. I did make one post-install tweak, since I am going to be using this on existing Git projects: I updated my ~/.gitignore_global to ignore .jj directories anywhere on disk.2
Using Jujutsu in an existing Git project is also quite easy.3 You just run jj git init --git-repo <path to repo>.4 That’s the entire flow. After that you can use git and jj commands alike on the repository, and everything Just Works™, right down to correctly handling .gitignore files. I have since run jj git init in every Git repository I am actively working on, and have had no issues in many months. It is also possible to initialize a Jujutsu copy of a Git project without having an existing Git repo, using jj git clone, which I have also done, and which works well.
Cloning true-myth and initializing it as a Jujutsu repo
Once a project is initialized, working on it is fairly straightforward, though there are some significant adjustments required if you have deep-seated habits from Git!
Revisions and revsets
One of the first things to wrap your head around when first coming to Jujutsu is its approach to its revisions and revsets, i.e. “sets of revision”. Revisions are the fundamental elements of changes in Jujutsu, not “commits” as in Git. Revsets are then expressions in a functional language for selecting a set of revisions. Both the idea and the terminology are borrowed directly from Mercurial, though the implementation is totally new. (Many things about Jujutsu borrow from Mercurial — a decision which makes me quite happy.) The vast majority of Jujutsu commands take a --revision/-r command to select a revision. So far that might not sound particularly different from Git’s notion of commits and commit ranges, and they are indeed similar at a surface level. However, the differences start showing up pretty quickly, both in terms of working with revisions and in terms of how revisions are a different notion of change than a Git commit.
The first place you are likely to experience how revisions and revsets are different — and neat! — is with the log command, since looking at the commit log is likely to be something you do pretty early in using a new version control tool. (Certainly it was for me.) When you clone a repo and initialize Jujutsu in it and then run jj log, you will see something rather different from what git log would show you — indeed, rather different from anything I even know how to get git log to show you. For example, here’s what I see today when running jj log on the Jujutsu repository, limiting it to show just the last 10 revisions:
> jj log --limit 10
@  ukvtttmt hello@chriskrycho.com 2024-02-03 09:37:24.000 -07:00 1a0b8773
│  (empty) (no description set)
◉  qppsqonm essiene@google.com 2024-02-03 15:06:09.000 +00:00 main* HEAD@git bcdb9beb
·  cli: Move git_init() from init.rs to git.rs
· ◉  rzwovrll ilyagr@users.noreply.github.com 2024-02-01 14:25:17.000 -08:00
┌─┘  ig/contributing@origin 01e0739d
│    Update contributing.md
◉  nxskksop 49699333+dependabot[bot]@users.noreply.github.com 2024-02-01 08:56:08.000
·  -08:00 fb6c834f
·  cargo: bump the cargo-dependencies group with 3 updates
· ◉  tlsouwqs jonathantanmy@google.com 2024-02-02 21:26:23.000 -08:00
· │  jt/missingop@origin missingop@origin 347817c6
· │  workspace: recover from missing operation
· ◉  zpkmktoy jonathantanmy@google.com 2024-02-02 21:16:32.000 -08:00 2d0a444e
· │  workspace: inline is_stale()
· ◉  qkxullnx jonathantanmy@google.com 2024-02-02 20:58:21.000 -08:00 7abf1689
┌─┘  workspace: refactor for_stale_working_copy
◉  yyqlyqtq yuya@tcha.org 2024-01-31 09:40:52.000 +09:00 976b8012
·  index: on reinit(), delete all segment files to save disk space
· ◉  oqnvqzzq martinvonz@google.com 2024-01-23 10:34:16.000 -08:00
┌─┘  push-oznkpsskqyyw@origin 54bd70ad
│    working_copy: make reset() take a commit instead of a tree
◉  rrxuwsqp stephen.g.jennings@gmail.com 2024-01-23 08:59:43.000 -08:00 57d5abab
·  cli: display which file's conflicts are being resolved
Here’s the output for the same basic command in Git — note that I am not trying to get a similar output from Git, just asking what it shows by default (and warning: wall of log output!):
> git log -10
commit: bcdb9beb6ce5ba625ae73d4839e4574db3d9e559     HEAD -> main, origin/main
date:   Mon, 15 Jan 2024 22:31:33 +0000
author: Essien Ita Essien 
    cli: Move git_init() from init.rs to git.rs
    * Move git_init() to cli/src/commands/git.rs and call it from there.
    * Move print_trackable_remote_branches into cli_util since it's not git specific,
      but would apply to any backend that supports remote branches.
    * A no-op change. A follow up PR will make use of this.
commit: 31e4061bab6cfc835e8ac65d263c29e99c937abf
date:   Mon, 8 Jan 2024 10:41:07 +0000
author: Essien Ita Essien 
    cli: Refactor out git_init() to encapsulate all git related work.
    * Create a git_init() function in cli/src/commands/init.rs where all git related work is done.
      This function will be moved to cli/src/commands/git.rs in a subsequent PR.
commit: 8423c63a0465ada99c81f87e06f833568a22cb48
date:   Mon, 8 Jan 2024 10:41:07 +0000
author: Essien Ita Essien 
    cli: Refactor workspace root directory creation
    * Add file_util::create_or_reuse_dir() which is needed by all init
      functionality regardless of the backend.
commit: b3c47953e807bef202d632c4e309b9a8eb814fde
date:   Wed, 31 Jan 2024 20:53:23 -0800
author: Ilya Grigoriev 
    config.md docs: document `jj config edit` and `jj config path`
    This changes the intro section to recommend using `jj config edit` to
    edit the config instead of looking for the files manually.
commit: e9c482c0176d5f0c0c28436f78bd6002aa23a5e2
date:   Wed, 31 Jan 2024 20:53:23 -0800
author: Ilya Grigoriev 
    docs: mention in `jj help config edit` that the command can create a file
commit: 98948554f72d4dc2d5f406da36452acb2868e6d7
date:   Wed, 31 Jan 2024 20:53:23 -0800
author: Ilya Grigoriev 
    cli `jj config`: add `jj config path` command
commit: 8a4b3966a6ff6b9cc1005c575d71bfc7771bced1
date:   Fri, 2 Feb 2024 22:08:00 -0800
author: Ilya Grigoriev 
    test_global_opts: make test_version just a bit nicer when it fails
commit: 42e61327718553fae6b98d7d96dd786b1f050e4c
date:   Fri, 2 Feb 2024 22:03:26 -0800
author: Ilya Grigoriev 
    test_global_opts: extract --version to its own test
commit: 42c85b33c7481efbfec01d68c0a3b1ea857196e0
date:   Fri, 2 Feb 2024 15:23:56 +0000
author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
    cargo: bump the cargo-dependencies group with 1 update
    Bumps the cargo-dependencies group with 1 update: [tokio](https://github.com/tokio-rs/tokio).
    Updates `tokio` from 1.35.1 to 1.36.0
    - [Release notes](https://github.com/tokio-rs/tokio/releases)
    - [Commits](https://github.com/tokio-rs/tokio/compare/tokio-1.35.1...tokio-1.36.0)
    ---
    updated-dependencies:
    - dependency-name: tokio
      dependency-type: direct:production
      update-type: version-update:semver-minor
      dependency-group: cargo-dependencies
    ...
    Signed-off-by: dependabot[bot] 
commit: 32c6406e5f04d2ecb6642433b0faae2c6592c151
date:   Fri, 2 Feb 2024 15:22:21 +0000
author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
    github: bump the github-dependencies group with 1 update
    Bumps the github-dependencies group with 1 update: [DeterminateSystems/magic-nix-cache-action](https://github.com/determinatesystems/magic-nix-cache-action).
    Updates `DeterminateSystems/magic-nix-cache-action` from 1402a2dd8f56a6a6306c015089c5086f5e1ca3ef to eeabdb06718ac63a7021c6132129679a8e22d0c7
    - [Release notes](https://github.com/determinatesystems/magic-nix-cache-action/releases)
    - [Commits](https://github.com/determinatesystems/magic-nix-cache-action/compare/1402a2dd8f56a6a6306c015089c5086f5e1ca3ef...eeabdb06718ac63a7021c6132129679a8e22d0c7)
    ---
    updated-dependencies:
    - dependency-name: DeterminateSystems/magic-nix-cache-action
      dependency-type: direct:production
      dependency-group: github-dependencies
    ...
    Signed-off-by: dependabot[bot] 
What’s happening in the Jujutsu log output? Per the tutorial’s note on the log command specifically:
    By default, jj log lists your local commits, with some remote commits added for context. The ~ indicates that the commit has parents that are not included in the graph. We can use the -r flag to select a different set of revisions to list.
What jj log does show by default was still a bit non-obvious to me, even after that. Which remote commits added for context, and why? The answer is in the help output for jj log’s -r/--revisions option:
    Which revisions to show. Defaults to the ui.default-revset setting, or @ | ancestors(immutable_heads().., 2) | heads(immutable_heads()) if it is not set
I will come back to this revset in a moment to explain it in detail. First, though, this shows a couple other interesting features of Jujutsu’s approach to revsets and thus the log command. First, it treats some of these operations as functions (ancestors(), immutable_heads(), etc.). There is a whole list of these functions! This is not a surprise if you think about what “expressions in a functional language” implies… but it was a surprise to me because I had not yet read that bit of documentation. Second, it makes “operators” a first-class idea. Git has operators, but this goes a fair bit further:
    It includes - for the parent and + for a child, and these stack and compose, so writing @-+-+ is the same as @ as long as the history is linear. (That is an important distinction!)
    It supports union |, intersection &, and difference ~ operators.
    A leading ::, which means “ancestors”. A trailing :: means “descendants”. Using :: between commits gives a view of the directed acyclic graph range between two commits. Notably, <id1>::<id2> is just <id1>:: & ::<id2>.
    There is also a .. operator, which also composes appropriately (and, smartly, is the same as .. in Git when used between two commits, <id1>..<id2>). The trailing version, <id>.., is interesting: it is “revisions that are not ancestors of <id>”. Likewise, the leading version ..<id> is all revisions which are ancestors of <id>
Now, I used <id> here, but throughout these actually operate on revsets, so you could use them with any revset. For example, ..tags() will give you the ancestors of all tags. This strikes me as extremely interesting: I think it will dodge a lot of pain in dealing with Git histories, because it lets you ask questions about the history in a compositional way using normal set logic. To make that concrete: back in October, Jujutsu contributor @aseipp pointed out how easy it is to use this to get a log which excludes gh-pages. (Anyone who has worked on a repo with a gh-pages branch knows how annoying it is to have it cluttering up your view of the rest of your Git history!) First, you define an alias for the revset that only includes the gh-pages branch: 'gh-pages' = 'remote_branches(exact:"gh-pages")'. Then you can exclude it from other queries with the ~ negation operator: jj log -r "all() ~ ancestors(gh-pages)" would give you a log view for every revision with all() and then exclude every ancestor of the gh-pages branch.
Jujutsu also provides a really capable templating system, which uses “a functional language to customize output of commands”. That functional language is built on top of the functional language that the whole language uses for describing revisions (described in brief above!), so you can use the same kinds of operators in templates for output as you do for navigating and manipulating the repository. The template format is still evolving, but you can use it to customize the output today… while being aware that you may have to update it in the future. Keywords include things like description and change_id, and these can be customized in Jujutsu’s config. For example, I made this tweak to mine, overriding the built-in format_short_id alias:
[template-aliases]
'format_short_id(id)' = 'id.shortest()'
This gives me super short names for changes and commits, which makes for a much nicer experience when reading and working with both in the log output: Jujutsu will give me the shortest unique identifier for a given change or commit, which I can then use with commands like jj new. Additionally, there are a number of built-in templates. For example, to see the equivalent of Git’s log --pretty you can use Jujutsu’s log -T builtin_log_detailed (-T for “template”; you can also use the long from --template). You can define your own templates in a [templates] section, or add your own [template-aliases] block, using the template language and any combination of further functions you define yourself.
That’s all well and good, but even with reading the docs for the revset language and the templating language, it still took me a bit to actually quite make sense out of the default output, much less to get a handle on how to customize the output. Right now, the docs have a bit of a flavor of explanations for people who already have a pretty good handle on version control systems, and the description of what you get from jj log is a good example of that. As the project gains momentum, it will need other kinds of more-introductory material, but the current status is totally fair and reasonable for the stage the project is at. And, to be fair to Jujutsu, both the revset language and the templating language are incredibly easier to understand and work with than the corresponding Git materials.
Returning to the difference between the default output from jj log and git log, the key is that unless you pass -r, Jujutsu uses the ui.default-revset selector to provide a much more informative view than git log does. Again, the default is @ | ancestors(immutable_heads().., 2) | heads(immutable_heads()). Walking through that:
    The @ operator selects the current head revision.
    The | union operator says “or this other revset”, so this will show @ itself and the result of the other two queries.
    The immutable_heads() function gets the list of head revisions which are, well, immutable. By default, this is trunk() | tags(), so whatever the trunk branch is (most commonly main or master) and also any tags in the repository.
    Adding .. to the first immutable_heads() function selects revisions which are not ancestors of those immutable heads. This is basically asking for branches which are not the trunk and which do not end at a tag.
    Then ancestors(immutable_heads().., 2) requests the ancestors of those branches, but only two deep.
    Finally, heads() gets the tips of all branches which appear in the revset passed to it: a head is a commit with no children. Thus, heads(immutable_heads()) gets just the branch tips for the list of revisions computed by immutable_heads().5
When you put those all together, your log view will always show your current head change, all the open branches which have not been merged into your trunk branch, and whatever you have configured to be immutable — out of the box, trunk and all tags. That is vastly more informative than git log’s default output, even if it is a bit surprising the first time you see it. Nor is it particularly possible to get that in a single git log command. By contrast, getting the equivalent of git log is trivial.
To show the full history for a given change, you can use the :: ancestors operator. Since jj log always gives you the identifier for a revision, you can follow it up with jj log --revision ::<change id>, or jj log -r ::<change id> for short. For example, in one repo where I am trying this, the most recent commit identifier starts with mwoq (Jujutsu helpfully highlights the segment of the change identifier you need to use), so I could write jj log -r ::mwoq, and this will show all the ancestors of mwoq, or jj log -r ..mwoq to get all the ancestors of the commit except the root. (The root is uninteresting.) Net, the equivalent command for “show me all the history for this commit” is:
$ jj log -r ..@
Revsets are very powerful, very flexible, and yet much easier to use than Git’s operators. That is in part because of the language used to express them. It is also in part because revsets build on a fundamentally different view of the world than Git commits: Jujutsu’s idea of changes.
Changes
In Git, as in Subversion and Mercurial and other version control systems before them, when you finish with a change, you commit it. In Jujutsu, there is no first-class notion of “committing” code. This took me a fair bit to wrap my head around! Instead, Jujutsu has two discrete operations: describe and new. jj describe lets you provide a descriptive message for any change. jj new starts a new change. You can think of git commit --message "something I did" as being equivalent to jj describe --message "some I did" && jj new. This falls out of the fact that jj describe and jj new are orthogonal, and much more capable than git commit as a result.
The describe command works on any commit. It defaults to the commit that is the current working copy. If you want to rewrite a message earlier in your commit history, though, that is not a special operation like it is in Git, where you have to perform an interactive rebase to do it. You just call jj describe with a --revision (or -r for short, as everywhere in Jujutsu) argument. For example:
# long version
$ jj describe --revision abcd --message "An updated message."
# short version
$ jj describe -r abcd -m "An updated message."
That’s it. How you choose to integrate that into your workflow is a matter for you and your team to decide, of course. Jujutsu understands that some branches should not have their history rewritten this way, though, and lets you specify what the “immutable heads” revset should be accordingly. This actually makes it safer than Git, where the tool itself does not understand that kind of immutability and we rely on forges to protect certain branches from being targeted by a force push.
The new command is the core of creating any new change, and it does not require there to be only a single parent. You can create a new change with as many parents as is appropriate! Is a given change logically the child of four other changes, with identifiers a, b, c, and d? jj new a b c d. That’s it. One neat consequence that falls out of this: a merge in Jujutsu is just jj new with the requirement that it have at least two parents. (“At least two parents” because having multiple parents for a merge is not a special case as with Git’s “octopus” merges.) Likewise, you do not need a commit command, because you can describe a given change at any time with describe, and you can create a new change at any time with new. If you already know the next thing you are going to do, you can even describe it by passing -m/--message to new when creating the new change!6
A demo of using jj new to create a three-parent merge
Most of the time with Git, I am doing one of two things when I go to commit a change:
    Committing everything that is in my working copy: git commit --all7 is an extremely common operation for me.
    Committing a subset of it, not by using Git’s -p to do it via that atrocious interface, but instead opening Fork and doing it with Fork’s staging UI.
In the first case, Jujutsu’s choice to skip Git’s “index” looks like a very good one. In the second case, I was initially skeptical. Once I got the hang of working this way, though, I started to come around. My workflow with Fork looks an awful lot like the workflow that Jujutsu pushes you toward with actually using a diff tool. With Jujutsu, though, any diff tool can work. Want to use Vim? Go for it.
What is more, Jujutsu’s approach to the working copy results in a really interesting shift. In every version control system I have worked with previously (including CVS, PVCS, SVN), the workflow has been some variation on:
    Make a bunch of changes.
    Create a commit and write a message to describe it.
With both Mercurial and Git, it also became possible to rewrite history in various ways. I use Git’s rebase --interactive command extensively when working on large sets of changes. (I did the same with Mercurial’s history rewriting when I was using it a decade ago.) That expanded the list of common operations to include two more:
    Possibly directly amend that set of changes and/or its description.
    Possibly restructure history: breaking apart changes, reordering them, rewriting their message, changing what commit they land on top of, and more.
Jujutsu flips all of that on its head. A change, not a commit, is the fundamental element of the mental and working model. That means that you can describe a change that is still “in progress” as it were. I discovered this while working on a little example code for a blog post I plan to publish later this month: you can describe the change you are working on and then keep working on it. The act of describing the change is distinct from the act of “committing” and thus starting a new change. This falls out naturally from the fact that the working copy state is something you can operate on directly: akin to Git’s index, but without its many pitfalls. (This simplification affects a lot of things, as I will discuss further below; but it is especially important for new learners. Getting my head around the index was one of those things I found quite challenging initially with Git a decade ago.)
When you are ready to start a new change, you use either jj commit to “finalize” this commit with a message, or jj new to “Create a new, empty change and edit it in the working copy”. Implied: jj commit is just a convenience for jj describe followed by jj new. And a bonus: this means that rewording a message earlier in history does not involve some kind of rebase operation; you just jj describe --revision <target>.
What is more, jj new lets you create a new commit anywhere in the history of your project, trivially:
-A, --insert-after
      Insert the new change between the target commit(s) and their children
      [aliases: after]
-B, --insert-before
      Insert the new change between the target commit(s) and their parents
      [aliases: before]
You can do this using interactive rebasing with Git (or with history rewriting with Mercurial, though I am afraid my hg is rusty enough that I do not remember the details). What you cannot do in Git specifically is say “Start a new change at point x” unless you are in the middle of a rebase operation, which makes it inherently somewhat fragile. To be extra clear: Git allows you to check out make a new change at any point in your graph, but it creates a branch at that point, and none of the descendants of that original point in your commit graph will come along without explicitly rebasing. Moreover, even once you do an explicit rebase and cherry-pick in the commit, the original commit is still hanging out, so you likely need to delete that branch. With jj new -A <some change ID>, you just insert the change directly into the history. Jujutsu will rebase every child in the history, including any merges if necessary; it “just works”. That does not guarantee you will not have conflicts, of course, but Jujutsu also handles conflicts better — way better — than Git. More on that below.
I never use git reflog so much as when doing interactive rebases. Once I got the hang of Jujutsu’s ability to jj new anywhere, it basically obviates most of the places I have needed Git’s interactive rebase mode, especially when combined with Jujutsu’s aforementioned support for “first-class conflicts”. There is still an escape hatch for mistakes, though: jj op log shows all the operations you have performed on the repo — and frankly, is much more useful and powerful than git reflog, because it logs all the operations, including whenever Jujutsu updates its view of your working copy via jj status, when it fetches new revisions from a remote.
Additionally, Jujutsu allows you to see how any change has evolved over time. This handily solves multiple pain points in Git. For example, if you have made changes in your working copy, and would like to split it into multiple changes, Git only has a binary state to let you tease those apart: staged, or not. As a result, that kind of operation ranges in difficulty from merely painful to outright impossible. With its obslog command,8 Jujutsu allows you to see how a change has evolved over time. Since the working copy is just one more kind of “change”, you can very easily retrieve earlier state — any time you did a jj status check, or any other command which snapshotted the state of the repository (which is most of them). That applies equally to earlier changes. If you just rebased, for example, and realize you moved some changes to code into the wrong revision, you can use the combination of obslog and new and restore (or move) to pull it back apart into the desired sequence of changes. (This one is hard to describe, so I may put up a video of it later!)
Split
This also leads to another significant difference with Git: around breaking up your current set of changes on disk. As I noted above, Jujutsu treats the working copy itself as a commit instead of having an “index” like Git. Git really only lets you break apart a set of changes with the index, using git add --patch. Jujutsu instead has a split command, which launches a diff editor and lets you select what you want to incorporate — rather like git add --patch does. As with all of its commands, though, jj split works exactly the same way on any commit; the working copy commit gets it “for free”.
Philosophically, I really like this. Practically, though, it is a slightly bumpier experience for me than the Git approach at the moment. Recall that I do not use git add --patch directly. Instead, I always stage changes into the Git index using a graphical tool like Fork. That workflow is slightly nicer than editing a diff — at least, as Jujutsu does it today. In Fork (and similar tools), you start with no changes and add what you want to the change set you want. By contrast, jj split launches a diff view with all the changes from a given commit present: splitting the commit involves removing changes from the right side of the diff so that it has only the changes you want to be present in the first of two new commits; whatever is not present in the final version of the right side when you close your diff editor ends up in the second commit.
If this sounds a little complicated, that is because it is — at least for today. That qualifier is important, because a lot of this is down to tooling, and we have about as much dedicated tooling for Jujutsu as Git had in 2007, which is to say: not much. Qualifier notwithstanding, and philosophical elegance notwithstanding, the complexity is still real here in early 2024. There are two big downsides as things stand. First, I find it comes with more cognitive load. It requires thinking in terms of negation rather than addition, and the “second commit” becomes less and less visible over time as you remove it from the first commit. Second, it requires you to repeat the operation when breaking up something into more than two commits. I semi-regularly take a single bucket of changes on disk and chunk it up into many more than just 2 commits, though! That significantly multiplies the cognitive overhead.
Now, since I started working with Jujutsu, the team has switched the default view for working with these kinds of diffs to using scm-diff-editor, a TUI which has a first-class notion of this kind of workflow.9 That TUI works reasonably well, but is much less pleasant to use than something like the nice GUIs of Fork or Tower.
The net is: when I want to break apart changes, at least for the moment I find myself quite tempted to go back to Fork and Git’s index. I do not think this problem is intractable, and I think the idea of jj split is right. It just — “just”! — needs some careful design work. Preferably, the split command would make it straightforward to generate an arbitrary number of commits from one initial commit, and it would allow progressive creation of each commit from a “vs. the previous commit” baseline. This is the upside of the index in Git: it does actually reflect the reality that there are three separate “buckets” in view when splitting apart a change: the baseline before all changes, the set of all the changes, and the set you want to include in the commit. Existing diff tools do not really handle this — other than the integrated index-aware diff tools in Git clients, which then have their own oddities when interacting with Jujutsu, since it ignores the index.
First-class conflicts
Another huge feature of Jujutsu is its support for first-class conflicts. Instead of a conflict resulting in a nightmare that has to be resolved before you can move on, Jujutsu can incorporate both the merge and its resolution (whether manual or automatic) directly into commit history. Just having the conflicts in history does not seem that weird. “Okay, you committed the text conflict markers from git, neat.” But: having the conflict and its resolution in history, especially when Jujutsu figured out how to do that resolution for you, as part of a rebase operation? That is just plain wild.
A while back, I was working on a change to a library I maintain10 and decided to flip the order in which I landed two changes to package.json. Unfortunately, those changes were adjacent to each other in the file and so flipping the order they would land in seemed likely to be painfully difficult. It was actually trivial. First of all, the flow itself was great: instead of launching an editor for interactive rebase, I just explicitly told Jujutsu to do the rebases: jj rebase --revision <source> --destination <target>. I did that for each of the items I wanted to reorder and I was done. (I could also have rebased a whole series of commits; I just did not need to in this case.) Literally, that was it: because Jujutsu had agreed with me that JSON is a terrible format for changes like this and committed a merge conflict, then resolved the merge conflict via the next rebase command, and simply carried on.
At a mechanical level, Jujutsu will add conflict markers to a file, not unlike those Git adds in merge conflicts. However, unlike Git, those are not just markers in a file. They are part of a system which understands what conflicts are semantically, and therefore also what resolving a conflict is semantically. This not only produces nice automatic outcomes like the one I described with my library above; it also means that you have more options for how to accomplish a resolution, and for how to treat a conflict. Git trains you to see a conflict between two branches as a problem. It requires you to solve that problem before moving on. Jujutsu allows you to treat a conflict as a problem which much be resolved, but it does not require it. Resolving conflicts in merges in Git is often quite messy. It is even worse when rebasing. I have spent an incredibly amount of time attempting merges only to give up and git reset --hard <before the merge>, and possibly even more time trying to resolve a conflicting in a rebase only to bail with git rebase --abort. Jujutsu allows you to create a merge, leave the conflict in place, and then introduce a resolution in the next commit, telling the whole story with your change history.
Conflict resolution with merges
Likewise with a rebase: depending on whether you require all your intermediate revisions to be able to be built or would rather show a history including conflicts, you could choose to rebase, leave all the intermediate changes conflicted, and resolve it only at the end.
Conflict resolution with rebases
Conflicts are inevitable when you have enough people working on a repository. Honestly: conflicts happen when I am working alone in a repository, as suggested by my anecdote above. Having this ability to keep working with the repository even in a conflicted state, as well as to resolve the conflicts in a more interactive and iterative way is something I now find difficult to live without.
Changing changes
There are a few other niceties which fall out of Jujutsu’s distinction between changes and commits, especially when combined with first-class conflicts.
First up, jj squash takes all the changes in a given commit and, well, squashes them into the parent of that commit.11 Given a working copy with a bunch of changes, you can move them straight into the parent by just typing jj squash. If you want to squash some change besides the one you are currently editing, you just pass the -r/--revision flag, as with most Jujutsu commands: jj squash -r abc will squash the change identified by abc into its parent. You can also use the --interactive (-i for short) argument to move just a part of a change into its parent. Using that flag will pop up your configured diff editor just like jj split will and allow you to select which items you want to move into the parent and which you want to keep separate. Or, for an even faster option, if you have specific files to move while leaving others alone, and you do not need to handle subsections of those files, you can pass them as the final arguments to the command, like jj squash ./path/a ./path/c.
As it turns out, this ability to move part of one change into a different change is a really useful thing to be able to do in general. I find it particularly handy when building up a set of changes where I want each one to be coherent — say, for the sake of having a commit history which is easy for others to review. You could do that by doing some combination of jj split and jj new --after <some change ID> and then doing jj rebase to move around the changes… but as usual, Jujutsu has a better way. The squash command is actually just a shortcut for Jujutsu’s move command with some arguments filled in. The move command has --from and --to arguments which let you specify which revisions you want to move between. When you run jj squash with no other arguments, that is the equivalent of jj move --from @ --to @-. When you run jj squash -r abc, that is the equivalent of jj move --from abc --to abc-. Since it takes those arguments explicitly, though, move lets you move changes around between any changes. They do not need to be anywhere near each other in history.
A demo of using jj move
This eliminates another entire category of places I have historically had to reach for git rebase --interactive. While there are still a few times where I think Jujutsu could use something akin to Git’s interactive rebase mode, they are legitimately few, and mostly to do with wanting to be able to do batch reordering of commits. To be fair, though, I only want to do that perhaps a few times a year.
Branches
Branches are another of the very significant differences between Jujutsu and Git — another place where Jujutsu acts a bit more like Mercurial, in fact. In Git, everything happens on named branches. You can operate on anonymous branches in Git, but it will yell at you constantly about being on a “detached HEAD”. Jujutsu inverts this. The normal working mode in Jujutsu is just to make a series of changes, which then naturally form “branches” in the change graph, but which do not require a name out of the gate. You can give a branch a name any time, using jj branch create. That name is just a pointer to the change you pointed it at, though; it does not automatically “follow” you as you do jj new to create new changes. (Readers familiar with Mercurial may recognize that this is very similar to its bookmarks), though without the notion of “active” and “inactive” bookmarks.)
To update what a branch name points to, you use the branch set command. To completely get rid of a branch, including removing it from any remotes you have pushed the branch to, you use the branch delete command. Handily, if you want to forget all your local branch operations (though not the changes they apply to), you can use the branch forget command. That can come in useful when your local copy of a branch has diverged from what is on the remote and you don’t want to reconcile the changes and just want to get back to whatever is on the remote for that branch. No need for git reset --hard origin/<branch name>, just jj branch forget <branch name> and then the next time you pull from the remote, you will get back its view of the branch!
It’s not just me who wants this!
Jujutsu’s defaulting to anonymous branches took me a bit to get used to, after a decade of doing all of my work in Git and of necessity having to do my work on named branches. As with so many things about Jujutsu, though, I have very much come to appreciate this default. In particular,I find this approach makes really good sense for all the steps where I am not yet sharing a set of changes with others. Even once I am sharing the changes with others, Git’s requirement of a branch name can start to feel kind of silly at times. Especially for the case where I am making some small and self-contained change, the name of a given branch is often just some short, snake-case-ified version of the commit message. The default log template shows me the current set of branches, and their commit messages are usually sufficiently informative that I do not need anything else.
However, there are some downsides to this approach in practice, at least given today’s ecosystem. First, the lack of a “current branch” makes for some extra friction when working with tools like GitHub, GitLab, Gitea, and so on. The GitHub model (which other tools have copied) treats branches as the basis for all work. GitHub displays warning messages about commits which are not on a branch, and will not allow you to create a pull request from an anonymous branch. In many ways, this is simply because Git itself treats branches as special and important. GitHub is just following Git’s example of loud warnings about being on a “detached HEAD” commit, after all.
What this means in practice, though, is that there is an extra operation required any time you want to push your changes to GitHub or a similar forge. With Git, you simply git push after making your changes. (More on Git interop below.) Since Git keeps the current branch pointing at the current HEAD, Git aliases git push with no arguments to git push <configured remote for current branch> <current branch>. Jujutsu does not do this, and given how its branching model works today, cannot do this, because named branches do not “follow” your operations. Instead, you must first explicitly set the branch to the commit you want to push. In the most common case, where you are pushing your latest set of changes, that is just jj branch set <branch name>; it takes the current change automatically. Only then can you run jj git push to actually get an update. This is only a paper cut, but it is a paper cut. It is one extra command every single time you go to push a change to share with others, or even just to get it off of your machine.12 That might not seem like a lot, but it adds up.
There is a real tension in the design space here, though. On the one hand, the main time I use branches in Jujutsu at this point is for pushing to a Git forge like GitHub. I rarely feel the need for them for just working on a set of changes, where jj log and jj new <some revision> give me everything I need. In that sense, it seems like having the branch “follow along” with my work would be natural: if I have gone to the trouble of creating a name for a branch and pushing it to some remote, then it is very likely I want to keep it up to date as I add changes to the branch I named. On the other hand, there is a big upside to not doing that automatically: pushing changes becomes an intentional act. I cannot count the number of times I have been working on what is essentially just an experiment in a Git repo, forgotten to change from the foo-feature to a new foo-feature-experiment branch, and then done a git push. Especially if I am collaborating with others on foo-feature, now I have to force push back to the previous to reset things, and let others know to wait for that, etc. That never happens with the Jujutsu model. Since updating a named branch is always an intentional act, you can experiment to your heart’s content, and know you will never accidentally push changes to a branch that way. I go back and forth: Maybe the little bit of extra friction when you do want to push a branch is worth it for all the times you do not have to consciously move a branch backwards to avoid pushing changes you are not yet ready to share.
(As you might expect, the default of anonymous branches has some knock-on effects for how it interacts with Git tooling in general; I say more on this below.)
Jujutsu also has a handy little feature for when you have done a bunch of work on an anonymous branch and are ready to push it to a Git forge. The jj git push subcommand takes an optional --change/-c flag, which creates a branch based on your current change ID. It works really well when you only have a single change you are going to push and then continually work on, or any time you are content that your current change will remain the tip of the branch. It works a little less well when you are going to add further changes later, because you need to then actually use the branch name with jj branch set push/<change ID> -r <revision>.
Taking a step back, though, working with branches in Jujutsu is great overall. The branch command is a particularly good lens for seeing what a well-designed CLI is like and how it can make your work easier. Notice that the various commands there are all of the form jj branch <do something>. There are a handful of other branch subcommands not mentioned so far: list, rename, track, and untrack. Git has slowly improved its design here over the past few years, but still lacks the straightforward coherence of Jujutsu’s design. For one thing, all of these are subcommands in Jujutsu, not like Git’s mishmash of flags which can be combined in some cases but not others, and have different meanings depending on where they are deployed. For another, as with the rest of Jujutsu’s CLI structure, they use the same options to mean the same things. If you want to list all the branches which point to a given set of revisions, you use the -r/--revisions flag, exactly like you do with any other command involving revisions in Jujutsu. In general, Jujutsu has a very strong and careful distinction between commands (including subcommands) and options. Git does not. The track and untrack subcommands are a perfect example. In Jujutsu, you track a remote branch by running a command like jj branch track <branch>@<remote>. The corresponding Git command is git branch --set-upstream-to <remote>/<branch>. But to list and filter branches in Git, you also pass flags, e.g. git branch --all is the equivalent of jj branch list --all. The Git one is shorter, but also notably less coherent; there is no way to build a mental model for it. With Jujutsu, the mental model is obvious and consistent: jj <command> <options> or jj <context> <command> <options>, where <context> is something like branch or workspace or op (for operation).
Git interop
Jujutsu’s native backend exists, and every feature has to work with it, so it will some day be a real feature of the VCS. Today, though, the Git backend is the only one you should use. So much so that if you try to run jj init without passing --git, Jujutsu won’t let you by default:
> jj init
Error: The native backend is disallowed by default.
Hint: Did you mean to pass `--git`?
Set `ui.allow-init-native` to allow initializing a repo with the native backend.
In practice, you are going to be using the Git backend. In practice, I have been using the Git backend for the last seven months, full time, on every one of my personal repositories and all the open source projects I have contributed to. With the sole exception of someone watching me while we pair, no one has noticed, because the Git integration is that solid and robust. This interop means that adoption can be very low friction. Any individual can simply run jj git init --git-repo . in a given Git repository, and start doing their work with Jujutsu instead of Git, and all that work gets translated directly into operations on the Git repository.
Interoperating with Git also means that there is a two way-street between Jujutsu and Git. You can do a bunch of work with jj commands, and then if you hit something you don’t know how to do with Jujutsu yet, you can flip over and do it the way you already know with a git command. When you next run a jj command, like jj status, it will (very quickly!) import the updates from Git and go back about its normal business. The same thing happens when you run commands like jj git fetch to get the latest updates from a Git remote. All the explicit Git interop commands live under a git subcommand: jj git push, jj git fetch, etc. There are a handful of these, including the ability to explicitly ask to synchronize with the Git repository, but the only ones I use on a day to day basis are jj git push and jj git fetch. Notably, there is no jj git pull, because Jujutsu keeps a distinction between getting the latest changes from the server and changing your local copy’s state. I have not missed git pull at all.
This clean interop does not mean that Git sees everything Jujutsu sees, though. Initializing a Jujutsu repo adds a .jj directory to your project, which is where it stores its extra metadata. This, for example, is where Jujutsu keeps track of its own representation of changes, including how any given change has evolved, in terms of the underlying revisions. In the case of a Git repository, those revisions just are the Git commits, and although you rarely need to work with or name them directly, they have the same SHAs, so any time you would name a specific Git commit, you can reference it directly as a Jujutsu revision as well. (This is particularly handy when bouncing between jj commands and Git-aware tools which know nothing of Jujutsu’s change identifiers.) The .jj directory also includes the operation log, and in the case of a fresh Jujutsu repo (not one created from an existing Git repository), is where the backing Git repo lives.
This Git integration currently runs on libgit2, so there is effectively no risk of breaking your repo because of a Jujutsu – Git interop issue. To be sure, there can be bugs in Jujutsu itself, and you can do things using Jujutsu that will leave you in a bit of a mess, but the same is true of any tool which works on your Git repository. The risk might be very slightly higher here than with your average GUI Git client, since Jujutsu is mapping different semantics onto the repository, but I have extremely high confidence in the project at this point, and I think you can too.
Is it ready?
Unsurprisingly, given the scale of the problem domain, there are still some rough edges and gaps. For example: commit signing with GPG or SSH does not yet work. There is an open PR for the basics of the feature with GPG support, and SSH support will be straightforward to add once the basics, but landed it has not.13 The list of actual gaps or missing features is getting short, though. When I started using Jujutsu back in July 2023, there was not yet any support for sparse checkouts or for workspaces (analogous to Git worktrees). Both of those landed in the interval, and there is consistent forward motion from both Google and non-Google contributors. In fact, the biggest gap I see as a regular user in Jujutsu itself is the lack of the kinds of capabilities that will hopefully come once work starts in earnest on the native backend.
The real gaps and rough edges at this point are down to the lack of an ecosystem of tools around Jujutsu, and the ways that existing Git tools interact with Jujutsu’s design for Git interop. The lack of tooling is obvious: no one has built the equivalent of Fork or Tower, and there is no native integration in IDEs like IntelliJ or Visual Studio or in editors like VS Code or Vim. Since Jujutsu currently works primarily in terms of Git, you will get some useful feedback. All of those tools expect to be working in terms of Git’s index and not in terms of a Jujutsu-style working copy, though. Moreover, most of them (unsurprisingly!) share Git’s own confusion about why you are working on a detached HEAD nearly all the time. On the upside, viewing the history of a repo generally works well, with the exception that some tools will not show anonymous branches/detached HEADs other than one you have actively checked out. Detached heads also tend to confuse tools like GitHub’s gh; you will often need to do a bit of extra manual argument-passing to get them to work. (gh pr create --web --head <name> is has been showing up in my history a lot for exactly this reason.)
Some of Jujutsu’s very nice features also make other parts of working on mainstream Git forges a bit wonky. For example, notice what each of these operations has in common:
    Inserting changes at arbitrary points.
    Rewording a change description.
    Rebasing a series of changes.
    Splitting apart commits.
    Combining existing commits.
They are all changes to history. If you have pushed a branch to a remote, doing any of these operations with changes on that branch and pushing to a remote again will be a force push. Most mainstream Git forges handle force pushing pretty badly. In particular, GitHub has some support for showing diffs between force pushes, but it is very basic and loses all conversational context. As a result, any workflow which makes heavy use of force pushes will be bumpy. Jujutsu is not to blame for the gaps in those tools, but it certainly does expose them.14 Nor do I not blame GitHub for the quirks in interop, though. It is not JujutsuLab after all, and Jujutsu is doing things which do not perfectly map onto the Git model. Since most open source software development happens on forges like GitHub and GitLab, though, these things do regularly come up and cause some friction.
The biggest place I feel this today is in the lack of tools designed to work with Jujutsu around splitting, moving, and otherwise interactively editing changes. Other than @arxanas’ excellent scm-diff-editor, the TUI, which Jujutsu bundles for editing diffs on the command line, there are zero good tools for those operations. I mean it when I say scm-diff-editor is excellent, but I also do not love working in a TUI for this kind of thing, so I have cajoled both Kaleidoscope and BBEdit into working to some degree. As I noted when describing how jj split works, though, it is not a particularly good experience. These tools are simply not designed for this workflow. They understand an index, and they do not understand splitting apart changes. Net, we are going to want new tooling which actually understands Jujutsu.
There are opportunities here beyond implementing the same kinds of capabilities that many editors, IDEs, and dedicated VCS viewers provide today for Git. Given a tool which makes rebasing, merging, re-describing changes, etc. are all normal and easy operations, GUI tools could make all of those much easier. Any number of the Git GUIs have tried, but Git’s underlying model simply makes it clunky. That does not have to be the case with Jujutsu. Likewise, surfacing things like Jujutsu’s operation and change evolution logs should be much easier than surfacing the Git reflog, and provide easier ways to recover lost work or simply to change one’s mind.
Conclusion
Jujutsu has become my version control tool of choice since I picked it up over the summer. The rough edges and gaps I described throughout this write-up notwithstanding, I much prefer it to working with Git directly. I do not hesitate to recommend that you try it out on personal or open source projects. Indeed, I actively recommend it! I have used Jujutsu almost exclusively for the past seven months, and I am not sure what would make me go back to using Git other than Jujutsu being abandoned entirely. Given its apparently-bright future at Google, that seems unlikely.15 Moreover, because using it in existing Git repositories is transparent, there is no inherent reason individual developers or teams cannot use it today. (Your corporate security policy might have be a different story.)
Is Jujutsu ready for you to roll out at your Fortune 500 company? Probably not. While it is improving at a steady clip — most of the rough edges I hit in mid-2023 are long since fixed — it is still undergoing breaking changes in design here and there, and there is effectively no material out there about how to use it yet. (This essay exists, in part, as an attempt to change that!) Beyond Jujutsu itself, there is a lot of work to be done to build an ecosystem around it. Most of the remaining rough edges are squarely to do with the lack of understanding from other tools. The project is marching steadily toward a 1.0 release… someday. As for when that might be, there are as far as I know no plans: there is still too much to do. Above all, I am very eager to see what a native Jujutsu backend would look like. Today, it is “just” a much better model for working with Git repos. A world where the same level of smarts being applied to the front end goes into the backend too is a world well worth looking forward to.
Thoughts, comments, or questions? Discuss:
    Hacker News
    lobste.rs
    LinkedIn
    Mastodon
    Threads
    Bluesky
    Twitter/X
Appendix: Kaleidoscope setup and tips
As alluded to above, I have done my best to make it possible to use Kaleidoscope, my beloved diff-and-merge tool, with Jujutsu. I have had only mixed success. The appropriate setup that gives the best results so far:
    Add the following to your Jujutsu config (jj config edit --user) to configure Kaleidoscope for the various diff and merge operations:
    [ui]
    diff-editor = ["ksdiff", "--wait", "$left", "--no-snapshot", "$right", "--no-snapshot"]
    merge-editor = ["ksdiff", "--merge", "--output", "$output", "--base", "$base", "--", "$left", "--snapshot", "$right", "--snapshot"]
    I will note, however, that I have still not been 100% successful using Kaleidoscope this way. In particular, jj split does not give me the desired results; it often ends up reporting “Nothing changed” when I close Kaleidoscope.
    When opening a file diff, you must Option⎇-double-click, not do a normal double-click, so that it will preserve the --no-snapshot behavior. That --no-snapshot argument to ksdiff is what makes the resulting diff editable, which is what Jujutsu needs for its just-edit-a-diff workflow. I have been in touch with the Kaleidoscope folks about this, which is how I even know about this workaround; they are evaluating whether it is possible to make the normal double-click flow preserve the --no-snapshot in this case so you do not have to do the workaround.
Notes
    Yes, it is written in Rust, and it is pretty darn fast. But Git is written in C, and is also pretty darn fast. There are of course some safety upsides to using Rust here, but Rust is not particularly core to Jujutsu’s “branding”. It was just a fairly obvious choice for a project like this at this point — which is exactly what I have long hoped Rust would become! ↩︎
    Pro tip for Mac users: add .DS_Store to your ~/.gitignore_global and live a much less annoyed life — whether using Git or Jujutsu. ↩︎
    I did have one odd hiccup along the way due to a bug (already fixed, though not in a released version) in how Jujutsu handles a failure when initializing in a directory. While confusing, the problem was fixed in the next release… and this is what I expected of still-relatively-early software. ↩︎
    The plain jj init command is reserved for initializing with the native backend… which is currently turned off. This is absolutely the right call for now, until the native backend is ready, but it is a mild bit of extra friction (and makes the title of this essay a bit amusing until the native backend comes online…). ↩︎
    This is not quite the same as Git’s HEAD or as Mercurial’s “tip” — there is only one of either of those, and they are not the same as each other! ↩︎
    If you look at the jj help output today, you will notice that Jujutsu has checkout, merge, and commit commands. Each is just an alias for a behavior using new, describe, or both, though:
        checkout is just an alias for new
        commit is just a shortcut for jj describe -m "<some message>" && jj new
        merge is just jj new with an implicit @ as the first argument.
    All of these are going to go away in the medium term with both documentation and output from the CLI that teach people to use new instead. ↩︎
    Actually it is normally git ci -am "<message>" with -a for “all” (--all) and -m for the message, and smashed together to avoid any needless extra typing. ↩︎
    The name is from Mercurial’s evolution feature, where it refers to changes which have become obsolescent, thus obslog is the “obsolescent changes log”. I recently suggested to the Jujutsu maintainers that renaming this might be helpful, because it took me six months of daily use to discover this incredibly helpful tool. ↩︎
    They also enabled support for a three-pane view in Meld, which allegedly makes it somewhat better. However, Meld is pretty janky on macOS (as GTK apps basically always are), and it has a terrible startup time for reasons that are unclear at this point, which means this was not a great experience in the first place… and Meld crashes on launch on the current version of macOS. ↩︎
    Yes, this is what I do for fun on my time off. At least: partially. ↩︎
    For people coming from Git, there is also an amend alias, so you can use jj amend instead, but it does the same thing as squash and in fact the help text for jj amend makes it clear that it just is squash. ↩︎
    If that sounds like paranoia, well, you only have to lose everything on your machine once due to someone spilling a whole cup of water on it at a coffee shop to learn to be a bit paranoid about having off-machine backups of everything. I git push all the time. ↩︎
    I care about about this feature and have some hopes of helping get it across the line myself here in February 2024, but we will see! ↩︎
    There are plenty of interesting arguments out there about the GitHub collaboration design, alternatives represented by the Phabricator or Gerrit review models, and so on. This piece is long enough without them! ↩︎
    Google is famous for killing products, but less so developer tools. ↩︎
Thanks:
Waleed Khan (@arxanas), Joy Reynolds (@joyously), and Isabella Basso (@isinyaaa) all took time to read and comment on earlier drafts of this mammoth essay, and it is substantially better for their feedback!
Posted:
This entry was originally published in Essays on February 2, 2024, and last updated on February 8, 2024 (you can see the full revision history here); it was started on July 1, 2023.
Meaningful changes since creating this page:
    February 8, 2024: Updated to use jj git init instead of plain jj init, to match the 0.14 release.
    February 4, 2024: Filled out the section on Git interop. (How did I miss that before publishing?!?)
    February 3, 2024: Added an example of the log format right up front in that section.
    February 2, 2024: Reworked section on revsets and prepared for publication!
    February 1, 2024: Finished a draft! Added one and updated another asciinema for some of the basics, finished up the tooling section, and made a bunch of small edits.
    January 31, 2024: Finished describing first-class conflicts and added asciinema recordings showing conflicts with merges and rebases.
    January 30, 2024: Added a ton of material on branches and on CLI design.
    January 29, 2024: Wrote up a section on “changing changes”, focused on the squash and move commands.
    January 29, 2024: Added a section on obslog, and made sure the text was consistent on use of “Jujutsu” vs. jj for the name of the tool vs. command-line invocations.
    January 18, 2024: Made some further structural revisions, removing some now-defunct copy about the original plan, expanded on the conclusion, and substantially expanded the conclusion.
    January 16, 2024: jj init is an essay, and I am rewriting it—not a dev journal, but an essay introduction to the tool.
    November 2, 2023: Added a first pass at a conclusion, and started on the restructuring this needs.
    November 1, 2023: Describing a bit about how jj new -A works and integrates with its story for clean rebases.
    October 31, 2023: Filling in what makes jj interesting, and explaining templates a bit.
    August 7, 2023: A first pass at jj describe and jj new.
    August 7, 2023: YODA! And an introduction to the “Rewiring your Git brain” section.
    August 7, 2023: Adding more structure to the piece, and identifying the next pieces to write.
    July 31, 2023: Starting to do some work on the introduction.
    July 24, 2023: Correcting my description of revision behavior per discussion with the maintainer.
    July 24, 2023: Describing my current feelings about the jj split and auto-committed working copy vs. git add --patch (as mediated by a UI).
    July 13, 2023: Elaborated on the development of version control systems (both personally and in general!)… and added a bunch of <abbr> tags.
    July 12, 2023: Added a section on the experience of having first-class merging Just Work™, added an appendix about Kaleidoscope setup and usage, rewrote the paragraph where I previously mentioned the issues about Kaleidoscope, and iterated on the commit-vs.-change distinction.
    July 9, 2023: Rewrote the jj log section to incorporate info about revsets, rewrote a couple of the existing sections now that I have significantly more experience, and added a bunch of notes to myself about what to tackle next in this write-up.
    July 3, 2023: Wrote up some experience notes on actually using jj describe and jj new: this is pretty wild, and I think I like it?
    July 3, 2023: Reorganized and clarified the existing material a bit.
    July 2, 2023: Added some initial notes about initial setup bumps. And a lot of notes on the things I learned in trying to fix those! 
Spotted a typo? Submit a correction!
Topics:
    software development tools version control Jujutsu Git
Respond:
Thoughts, comments, or questions? Shoot me an email (it’s way better than traditional comments), or leave a comment on Hacker News or lobste.rs.
About:
I’m Chris Krycho—a follower of Christ, a husband, and a dad. I’m a software engineer by trade; a theologian by vocation; and a writer, runner and cyclist, composer, and erstwhile podcaster by hobby.
Support:
If you especially like what I’m doing here, you can buy me a book, or click the affiliate links in book reviews!

# Document Title
Steno & PL
About
Patch terminology
Jan 11, 2024
Intended audience 	
    Developers of version control systems, specifically jj.
    Those interested in the version control pedagogy.
Origin 	
    Reprint of research originally published on Google Docs.
    Surveyed five participants from various "big tech" companies (>$1B valuation).
Mood 	Investigative.
    Methodology
    Results
    Remarks
    Conclusions
    Related posts
    Comments
Methodology
Q: I am doing research for a source control project, can you answer what the following nouns mean to you in the context of source control, if anything? (Ordered alphabetically)
    a “change”
    a “commit”
    a “patch”
    a “revision”
Results
P1 (Google, uses Piper + CLs):
    Change: a difference in code. What isn’t committed yet.
    Commit: a cl. Code that is ready to push and has a description along with it
    Patch: a commit number that that someone made that may or may not be pushed yet […] A change that’s not yours
    Revision: a change to a commit?
P2 (big tech, uses GitLab + MRs):
    Change: added/removed/updated files
    Commit: a group of related changes with a description
    Patch: a textual representation of changes between two versions
    Revision: a version of the repository, like the state of all files after a set of commits
P3 (Google, uses Fig + CLs):
    Change: A change to me is any difference in code. Uncommitted to pushed. I’ve heard people say I’ve pushed the change.
    Commit: A commit is a saved code diff with a description.
    Patch: A patch is a diff between any two commits how to turn commit a into into b.
    Revision: Revisions idk. I think at work they are snapshots of a code base so all changes at a point in time.
P4 (Microsoft, uses GitHub + PRs):
    Change: the entire change I want to check into the codebase this can be multiple commits but it’s what I’m putting up for review
    Commit: a portion of my change
    Patch: a group of commits or a change I want to use on another repo/branch
    Revision: An id for a group of commits or a single commit
P5 (big tech, uses GitHub + PRs):
    Change: your update to source files in a repository
    Commit: description of change
    Patch: I don’t really use this but I would think a quick fix (image, imports, other small changes etc)
    Revision: some number or set of numbers corresponding to change
Remarks
Take-aways:
    Change: People largely don’t think of a “change” as an physical object, rather just a diff or abstract object.
        It can potentially range from uncommitted to committed to pushed (P1–P5).
        Unlike others, P4 thinks of it as a larger unit than a commit (more like a “review”), probably due to the GitHub PR workflow.
    Commit: Universally, commits are considered to have messages. However, the interpretation of a commit as a snapshot vs diff appears to be implicit (compare P2’s “commit” vs “revision”).
    Patch: Split between interpretations:
        Either it represents a diff between two versions of the code (P2, P3).
        Or it’s a higher-level interpretation of a patch as a transmissible change. Particularly for getting a change from someone else (P1), but can also refer to a change that you want to use on a different branch (P4).
        P5 merely considers a “patch” to be a “small fix”, which is also a generally accepted meaning, although a little imprecise in terms of source control (refers to the intention of the patch, rather than the mechanics of the patch itself).
    Revision: This is really interesting. The underlying mental models are very different, but the semantic implications end up aligning, more so than for the term “commit”!
        P1: Not a specific source control term, just “the effect of revising”.
        P2, P3: Effect of “applying all commits”. This implies that they consider “commits” as diffs and “revisions” as snapshots.
        P4, P5, Some notions that it’s specifically the identifier of a change/commit. It’s something that you can reference or send to others.
        Surprisingly to me, P2–P5 actually all essentially agree that “revision” means a snapshot of the codebase. The mental models are quite different (“accumulation of diffs” vs “stable identifier”) but they refer to the same ultimate result: a specific state of the codebase (…or a way to refer to it — what’s in a name?). This is essentially the opposite of “commit”, where everyone thinks that they agree on what they are, but they’re actually split — roughly evenly? — into snapshot vs diff mental models.
Conclusions
Conclusions for jj:
    We already knew that “change” is a difficult term, syntactically speaking. It’s also now apparent that it’s semantically unclear. Only P4 thought of it as a “reviewable unit”, which would probably most closely match the jj interpretation. We should switch away from this term.
    People are largely settled on what “commits” are in the ways that we thought.
        There are two main mental models, where participants appear to implicitly consider them to be either snapshots or diffs, as we know.
        They have to have messages according to participants (unlike in jj, where a commit/change may not yet have a message).
            It’s possible this is an artifact of the Git mental model, rather than fundamental. We don’t see a lot of confusion when we tell people “your commits can have empty messages”.
            I think the real implication is that the set of changes is packaged/finalized into one unit, as opposed to “changes”, which might be in flux or not properly packaged into one unit for publishing/sharing.
    Half of respondents think that “patch” primarily refers to a diff, while half think that it refers to a transmissible change.
        In my opinion, the “transmissible change” interpretation aligns most closely with jj changes at present. In particular, you put those up for review and people can download them.
        I also think the “diff” interpretation aligns with jj interpretation (as you can rebase patches around, and the semantic content of the patch doesn’t change); however, there is a great deal of discussion on Discord suggesting that people think of “patches” as immutable, and this doesn’t match the jj semantics where you can rebase them around (IIUC).
        Overall, I think “patch” is still the best term we have as a replacement for jj “changes” (unless somebody can propose a better one), and it’s clear that we should move away from “change” as a term.
    “Revision” is much more semantically clear than I thought it was. This means that we can adopt/coopt the existing term and ascribe the specific “snapshot” meaning that we do today.
        We already do use “revision” in many places, most notably “revsets”. For consistency, we likely want to standardize “revision” instead of “commit” as a term.
Related posts
The following are hand-curated posts which you might find interesting.
Date 		Title
19 Jun 2021 		git undo: We can do better
12 Oct 2021 		Lightning-fast rebases with git-move
19 Oct 2022 		Build-aware sparse checkouts
16 Nov 2022 		Bringing revsets to Git
05 Jan 2023 		Where are my Git UI features from the future?
11 Jan 2024 	(this post) 	Patch terminology
Want to see more of my posts? Follow me on Twitter or subscribe via RSS.
Comments
Steno & PL
subscribe via RSS
    Waleed Khan
    me@waleedkhan.name
arxanas
    arxanas
This is a personal blog. Unless otherwise stated, the opinions expressed here are my own, and not those of my past or present employers.

# Document Title
Mounting git commits as folders with NFS
• git •
Hello! The other day, I started wondering – has anyone ever made a FUSE filesystem for a git repository where all every commit is a folder? It turns out the answer is yes! There’s giblefs, GitMounter, and git9 for Plan 9.
But FUSE is pretty annoying to use on Mac – you need to install a kernel extension, and Mac OS seems to be making it harder and harder to install kernel extensions for security reasons. Also I had a few ideas for how to organize the filesystem differently than those projects.
So I thought it would be fun to experiment with ways to mount filesystems on Mac OS other than FUSE, so I built a project that does that called git-commit-folders. It works (at least on my computer) with both FUSE and NFS, and there’s a broken WebDav implementation too.
It’s pretty experimental (I’m not sure if this is actually a useful piece of software to have or just a fun toy to think about how git works) but it was fun to write and I’ve enjoyed using it myself on small repositories so here are some of the problems I ran into while writing it.
goal: show how commits are like folders
The main reason I wanted to make this was to give folks some intuition for how git works under the hood. After all, git commits really are very similar to folders – every Git commit contains a directory listing of the files in it, and that directory can have subdirectories, etc.
It’s just that git commits aren’t actually implemented as folders to save disk space.
So in git-commit-folders, every commit is actually a folder, and if you want to explore your old commits, you can do it just by exploring the filesystem! For example, if I look at the initial commit for my blog, it looks like this:
$ ls commits/8d/8dc0/8dc0cb0b4b0de3c6f40674198cb2bd44aeee9b86/
README
and a few commits later, it looks like this:
$ ls /tmp/git-homepage/commits/c9/c94e/c94e6f531d02e658d96a3b6255bbf424367765e9/
_config.yml  config.rb  Rakefile  rubypants.rb  source
branches are symlinks
In the filesystem mounted by git-commit-folders, commits are the only real folders – everything else (branches, tags, etc) is a symlink to a commit. This mirrors how git works under the hood.
$ ls -l branches/
lr-xr-xr-x 59 bork bazil-fuse -> ../commits/ff/ff56/ff563b089f9d952cd21ac4d68d8f13c94183dcd8
lr-xr-xr-x 59 bork follow-symlink -> ../commits/7f/7f73/7f73779a8ff79a2a1e21553c6c9cd5d195f33030
lr-xr-xr-x 59 bork go-mod-branch -> ../commits/91/912d/912da3150d9cfa74523b42fae028bbb320b6804f
lr-xr-xr-x 59 bork mac-version -> ../commits/30/3008/30082dcd702b59435f71969cf453828f60753e67
lr-xr-xr-x 59 bork mac-version-debugging -> ../commits/18/18c0/18c0db074ec9b70cb7a28ad9d3f9850082129ce0
lr-xr-xr-x 59 bork main -> ../commits/04/043e/043e90debbeb0fc6b4e28cf8776e874aa5b6e673
$ ls -l tags/
lr-xr-xr-x - bork 31 Dec  1969 test-tag -> ../commits/16/16a3/16a3d776dc163aa8286fb89fde51183ed90c71d0
This definitely doesn’t completely explain how git works (there’s a lot more to it than just “a commit is like a folder!”), but my hope is that it makes thie idea that every commit is like a folder with an old version of your code” feel a little more concrete.
why might this be useful?
Before I get into the implementation, I want to talk about why having a filesystem with a folder for every git commit in it might be useful. A lot of my projects I end up never really using at all (like dnspeep) but I did find myself using this project a little bit while I was working on it.
The main uses I’ve found so far are:
    searching for a function I deleted – I can run grep someFunction branch_histories/main/*/commit.go to find an old version of it
    quickly looking at a file on another branch to copy a line from it, like vim branches/other-branch/go.mod
    searching every branch for a function, like grep someFunction branches/*/commit.go
All of these are through symlinks to commits instead of referencing commits directly.
None of these are the most efficient way to do this (you can use git show and git log -S or maybe git grep to accomplish something similar), but personally I always forget the syntax and navigating a filesystem feels easier to me. git worktree also lets you have multiple branches checked out at the same time, but to me it feels weird to set up an entire worktree just to look at 1 file.
Next I want to talk about some problems I ran into.
problem 1: webdav or NFS?
The two filesystems I could that were natively supported by Mac OS were WebDav and NFS. I couldn’t tell which would be easier to implement so I just tried both.
At first webdav seemed easier and it turns out that golang.org/x/net has a webdav implementation, which was pretty easy to set up.
But that implementation doesn’t support symlinks, I think because it uses the io/fs interface and io/fs doesn’t support symlinks yet. Looks like that’s in progress though. So I gave up on webdav and decided to focus on the NFS implementation, using this go-nfs NFSv3 library.
Someone also mentioned that there’s FileProvider on Mac but I didn’t look into that.
problem 2: how to keep all the implementations in sync?
I was implementing 3 different filesystems (FUSE, NFS, and WebDav), and it wasn’t clear to me how to avoid a lot of duplicated code.
My friend Dave suggested writing one core implementation and then writing adapters (like fuse2nfs and fuse2dav) to translate it into the NFS and WebDav verions. What this looked like in practice is that I needed to implement 3 filesystem interfaces:
    fs.FS for FUSE
    billy.Filesystem for NFS
    webdav.Filesystem for webdav
So I put all the core logic in the fs.FS interface, and then wrote two functions:
    func Fuse2Dav(fs fs.FS) webdav.FileSystem
    func Fuse2NFS(fs fs.FS) billy.Filesystem
All of the filesystems were kind of similar so the translation wasn’t too hard, there were just 1 million annoying bugs to fix.
problem 3: I didn’t want to list every commit
Some git repositories have thousands or millions of commits. My first idea for how to address this was to make commits/ appear empty, so that it works like this:
$ ls commits/
$ ls commits/80210c25a86f75440110e4bc280e388b2c098fbd/
fuse  fuse2nfs  go.mod  go.sum  main.go  README.md
So every commit would be available if you reference it directly, but you can’t list them. This is a weird thing for a filesystem to do but it actually works fine in FUSE. I couldn’t get it to work in NFS though. I assume what’s going on here is that if you tell NFS that a directory is empty, it’ll interpret that the directory is actually empty, which is fair.
I ended up handling this by:
    organizing the commits by their 2-character prefix the way .git/objects does (so that ls commits shows 0b 03 05 06 07 09 1b 1e 3e 4a), but doing 2 levels of this so that a 18d46e76d7c2eedd8577fae67e3f1d4db25018b0 is at commits/18/18df/18d46e76d7c2eedd8577fae67e3f1d4db25018b0
    listing all the packed commits hashes only once at the beginning, caching them in memory, and then only updating the loose objects afterwards. The idea is that almost all of the commits in the repo should be packed and git doesn’t repack its commits very often.
This seems to work okay on the Linux kernel which has ~1 million commits. It takes maybe a minute to do the initial load on my machine and then after that it just needs to do fast incremental updates.
Each commit hash is only 20 bytes so caching 1 million commit hashes isn’t a big deal, it’s just 20MB.
I think a smarter way to do this would be to load the commit listings lazily – Git sorts its packfiles by commit ID, so you can pretty easily do a binary search to find all commits starting with 1b or 1b8c. The git library I was using doesn’t have great support for this though, because listing all commits in a Git repository is a really weird thing to do. I spent maybe a couple of days trying to implement it but I didn’t manage to get the performance I wanted so I gave up.
problem 4: “not a directory”
I kept getting this error:
"/tmp/mnt2/commits/59/59167d7d09fd7a1d64aa1d5be73bc484f6621894/": Not a directory (os error 20)
This really threw me off at first but it turns out that this just means that there was an error while listing the directory, and the way the NFS library handles that error is with “Not a directory”. This happened a bunch of times and I just needed to track the bug down every time.
There were a lot of weird errors like this. I also got cd: system call interrupted which was pretty upsetting but ultimately was just some other bug in my program.
Eventually I realized that I could use Wireshark to look at all the NFS packets being sent back and forth, which made some of this stuff easier to debug.
problem 5: inode numbers
At first I was accidentally setting all my directory inode numbers to 0. This was bad because if if you run find on a directory where the inode number of every directory is 0, it’ll complain about filesystem loops and give up, which is very fair.
I fixed this by defining an inode(string) function which hashed a string to get the inode number, and using the tree ID / blob ID as the string to hash.
problem 6: stale file handles
I kept getting this “Stale NFS file handle” error. The problem is that I need to be able to take an opaque 64-byte NFS “file handle” and map it to the right directory.
The way the NFS library I’m using works is that it generates a file handle for every file and caches those references with a fixed size cache. This works fine for small repositories, but if there are too many files then it’ll overflow the cache and you’ll start getting stale file handle errors.
This is still a problem and I’m not sure how to fix it. I don’t understand how real NFS servers do this, maybe they just have a really big cache?
The NFS file handle is 64 bytes (64 bytes! not bits!) which is pretty big, so it does seem like you could just encode the entire file path in the handle a lot of the time and not cache it at all. Maybe I’ll try to implement that at some point.
problem 7: branch histories
The branch_histories/ directory only lists the latest 100 commits for each branch right now. Not sure what the right move is there – it would be nice to be able to list the full history of the branch somehow. Maybe I could use a similar subfolder trick to the commits/ directory.
problem 8: submodules
Git repositories sometimes have submodules. I don’t understand anything about submodules so right now I’m just ignoring them. So that’s a bug.
problem 9: is NFSv4 better?
I built this with NFSv3 because the only Go library I could find at the time was an NFSv3 library. After I was done I discovered that the buildbarn project has an NFSv4 server in it. Would it be better to use that?
I don’t know if this is actually a problem or how big of an advantage it would be to use NFSv4. I’m also a little unsure about using the buildbarn NFS library because it’s not clear if they expect other people to use it or not.
that’s all!
There are probably more problems I forgot but that’s all I can think of for now. I may or may not fix the NFS stale file handle problem or the “it takes 1 minute to start up on the linux kernel” problem, who knows!
Thanks to my friend vasi who explained one million things about filesystems to me.

# Document Title
Dependencies Belong in Version Control
November 25th, 2023
I believe that all project dependencies belong in version control. Source code, binary assets, third-party libraries, and even compiler toolchains. Everything.
The process of building any project should be trivial. Clone repo, invoke build command, and that's it. It shouldn't require a complex configure script, downloading Strawberry Perl, installing Conda, or any of that bullshit.
Infact I'll go one step further. A user should be able to perform a clean OS install, download a zip of master, disconnect from the internet, and build. The build process shouldn't require installing any extra tools or content. If it's something the build needs then it belongs in version control.
First Instinct
Your gut reaction may be revulsion. That's it not possible. Or that it's unreasonable.
You're not totally wrong. If you're using Git for version control then committing ten gigabytes of cross-platform compiler toolchains is infeasible.
That doesn't change my claim. Dependencies do belong in version control. Even if it's not practical today due to Git's limitations. More on that later.
Why
Why do dependencies belong in version control? I'll give a few reasons.
    Usability
    Reliability
    Reproducibility
    Sustainability
Usability
Committing dependencies makes projects trivial to build and run. I have regularly failed to build open source projects and given up in a fit of frustrated rage.
My background is C++ gamedev. C++ infamously doesn't have a standard build system. Which means every project has it's own bullshit build system, project generator, dependency manager, scripting runtimes, etc.
ML and GenAI projects are a god damned nightmare to build. They're so terrible to build that there are countless meta-projects that exists solely to provide one-click installers (example: EasyDiffusion). These installers are fragile and sometimes need to be run several times to succeed.
Commit your dependencies and everything "just works". My extreme frustration with trying, and failing, to build open source projects is what inspired this post.
Reliability
Have you ever had a build fail because of a network error on some third-party server? Commit your dependencies and that will never happen.
There's a whole class of problems that simply disappear when depdendencies are committed. Builds won't break because of an OS update. Network errors don't exist. You eliminate "works on my machine" issues because someone didn't have the right version of CUDA installed.
Reproducibility
Builds are much easier to reproduce when version control contains everything. Great build systems are hermetic and allow for determistic builds. This is only possible when your build doesn't depend on your system environment.
Lockfiles are only a partial solution to reproducibility. Docker images are a poor man's VCS.
Sustainability
Committing dependencies makes it trivial to recreate old builds. God help you if you try to build a webdev stack from 2013.
In video games it's not uncommon to release old games on new platforms. These games can easily be 10 or 20 years old. How many modern projects will be easy to build in 20 years? Hell, how many will be easy to build in 5?
Commit your dependencies and ancient code bases will be as easy to rebuild as possible. Although new platforms will require new code, of course.
Proof of Life
To prove that this isn't completely crazy I built a proof of life C++ demo. My program is exceedingly simple:
#include <fmt/core.h>
int main() {
  fmt::print("Hello world from C++ 👋\n");
  fmt::print("goodbye cruel world from C++ ☠️\n");
  return 0;
}
The folder structure looks like this:
\root
    \sample_cpp_app
        - main.cpp
    \thirdparty
        \fmt (3 MB)
    \toolchains
        \win
            \cmake (106 MB)
            \LLVM (2.5 GB)
            \mingw64 (577 MB)
            \ninja (570 KB)
            \Python311 (20.5 MB)
    - CMakeLists.txt
    - build.bat
    - build.py
The toolchains folder contains five dependencies - CMake, LLVM, Ming64, Ninja, and Python 3.11. Their combined size is 3.19 gigabytes. No effort was made to trim these folders down in size.
The build.bat file nukes all environment variables and sets PATH=C:\Windows\System32;. This ensures only the included toolchains are used to compile.
The end result is a C++ project that "just works".
But Wait There's More
Here's where it gets fun. I wrote a Python that script that scans the directory for "last file accessed time" to track "touched files". This let's me check how many toolchain files are actually needed by the build. It produces this output:
Checking initial file access times... 🥸👨‍🔬🔬
Building... 👷‍♂️💪🛠️
Compile success! 😁
Checking new file access times... 🥸👨‍🔬🔬
File Access Stats
    Touched 508 files. Total Size: 272.00 MB
    Untouched 23138 files. Total Size: 2.93 GB
    Touched 2.1% of files
    Touched 8.3% of bytes
Running program...
    Target exe: c:\temp\code\toolchain_vcs\bin\main.exe
Hello world from C++ 👋
goodbye cruel world from C++ ☠️
Built and ran successfully! 😍
Well will you look at that!
Despite committing 3 gigabytes of toolchains we only actually needed a mere 272 megabytes. Well under 10%! Even better we touched just 2.0% of repo files.
The largest files touched were:
clang++.exe     [116.04 MB]
ld.lld.exe      [86.05 MB]
llvm-ar.exe     [28.97 MB]
cmake.exe       [11.26 MB]
libgcc.a        [5.79 MB]
libstdc++.dll.a [5.32 MB]
libmsvcrt.a     [2.00 MB]
libstdc++-6.dll [1.93 MB]
libkernel32.a   [1.27 MB]
My key takeaway is this: toolchain file sizes are tractable for version control if you can trim the fat.
This sparks my joy. Imagine cloning a repo, clicking build, and having it just work. What a wonderful and delightful world that would be!
A Vision for the Future
I'd like to paint a small dream for what I will call Next Gen Version Control Software (NGVCS). This is my vision for a Git/Perforce successor. Here are some of the key featurs I want NGVCS to have:
    virtual file system to fetch only files a user touches
    copy-on-write file storage
    system cache for NGVCS files
Let's pretend for a moment that every open source project commits their dependencies. Each one contains a full copy of Python, Cuda, Clang, MSVC, libraries, etc. What would happen?
First, the user clones a random GenAI repo. This is near instantaneous as files are not prefetched. The user then invokes the build script. As files are accessed they're downloaded. The very first build may download a few hundred megabytes of data. Notably it does NOT download the entire repo. If the user is on Linux it won't download any binaries for macOS or Windows.
Second, the user clones another GenAI repo and builds. Does this need to re-download gigabytes of duplicated toolchain content? No! Both projects use NGVCS which has a system wide file cache. Since we're also using a copy-on-write file system these files instantly materialize in the second repo at zero cost.
The end result is beautiful. Every project is trivial to fetch, build, and run. And users only have to download the minimum set of files to do so.
The Real World and Counter Arguments
Hopefully I've convinced some of you that committing dependencies is at least a good idea in an ideal world.
Now let's consider the real world and a few counter arguments.
The Elephant in the Room - Git
Unfortunately I must admit that committing dependencies is not be practical today. The problem is Git. One of my unpopular opinions is that Git isn't very good. Among its many sins is terrible support for large files and large repositories.
The root issue is that Git's architecture and default behavior expects all users to have a full copy of the entire repo history. Which means every version of every binary toolchain for every platform. Yikes!
There are various work arounds - Git LFS, Git Submodules, shallow clones, partial clones, etc. The problem is these aren't first-class features. They are, imho, second-class hacks. 😓
In theory Git could be updated to more properly support large projects. I believe Git should be shallow and partial by default. Almost all software projects are defacto centralized. Needing full history isn't the default, it's an edge case. Users should opt-in to full history only if they need it.
Containers
An alternative to committing dependencies is to use containers. If you build out of a container you get most, if not all, of the benefits. You can even maintain an archive of docker images that reliably re-build tagged releases.
Congrats, you're now using Docker as your VCS!
My snarky opinion is that Docker and friends primarily exist because modern build systems are so god damned fragile that the only way to reliably build and deploy is to create a full OS image. This is insanity!
Containers shouldn't be required simply to build and run projects. It's embarassing that's the world we live in.
Licensing
Not all dependencies are authorized for redistribution. I believe MSVC and XCode both disallow redistribution of compiler toolchains? Game consoles like Sony PlayStation and Nintendo Switch don't publicly release headers, libs, or compilers.
This is mostly ok. If you're working on a console project then you're already working on a closed source project. Developers already use permission controls to gate access.
The lack of redistribution rights for "normal" toolchains is annoying. However permissive options are available. If committing dependencies becomes common practice then I think it's likely that toolchain licenses will update to accomdate.
Updating Dependencies
Committing library dependencies to version control means they need to be updated. If you have lots of repos to update this could be a moderate pain in the ass.
This is also the opposite of how Linux works. In Linux land you use a hot mess of system libraries sprinkled chaotically across the search path. That way when there is a security fix you update a single .so (or three) and your system is safe.
I think this is largely a non-issue. Are you building and running your services out of Docker? Do you have a fleet of machines? Do you have lockfiles? Do you compile any thirdparty libraries from source? If the answer to any of these questions is yes, and it is, then you already have a non-trivial procedure to apply security fixes.
Committing dependencies to VCS doesn't make security updates much harder. In fact, having a monorepo source of truth can make things easier!
DVCS
One of Git's claims to fame is its distributed nature. At long last developers can commit work from an internetless cafe or airplane!
My NGVCS dream implies defacto centralization. Especially for large projects with large histories. Does that mean an internet connection is required? Absolutely not! Even Perforce, the King of centralized VCS, supports offline mode. Git continues to function locally even when working with shallow and partial Git clones.
Offline mode and decentralization are independent concepts. I don't know why so many people get this wrong.
Libraries
Do I really think that every library, such as fmt, should commit gigabytes of compilers to version control?
That's a good question. For languages like Rust which have a universal build system probably not. For languages like C++ and Python maybe yes! It'd be a hell of a lot easier to contribute to open source projects if step 0 wasn't "spend 8 hours configuring environment to build".
For libraries the answer may be "it depends". For executables I think the answer is "yes, commit everything".
Dreams vs Reality
NGVCS is obviously a dream. It doesn't exist today. Actually, that's not quite true. This is exactly how Google and Meta operate today. Infact numerous large companies have custom NGVCS equivalents for internal use. Unfortunately there isn't a good solution in the public sphere.
Is committing dependencies reasonable for Git users today? The answer is... almost? It's at least closer than most people realize! A full Python deployment is merely tens to hundreds of megabytes. Clang is only a few gigabytes. A 2TB SSD is only $100. I would enthusiastically donate a few gigabytes of hard drive space in exchange for builds that "just work".
Committing dependencies to Git might be possible to do cleanly today with shallow, sparse, and LFS clones. Maybe. It'd be great if you could run git clone --depth=1 --sparse=windows. Maybe someday.
Conclusion
I strongly believe that dependencies belong in version control. I believe it is "The Right Thing". There are significant benefits to usability, reliability, reproducibility, sustainability, and more.
Committing all dependencies to a Git repo may be more practical than you realize. The actual file size is very reasonable.
Improvements to VCS software can allow repos to commit cross-platform dependencies while allowing users to download the bare minimum amount of content. It's the best of everything.
I hope that I have convinced you that committing dependencies and toolchains is "The Right Thing". I hope that version control systems evolve to accomodate this as a best practice.
Thank you.
Bonus Section
If you read it this far, thank you! Here are some extra thoughts I wanted to share but couldn't squeeze into the main article.
Sample Project
The sample project can be downloaded via Dropbox as a 636mb .7zip file. It should be trivial to download and build! Linux and macOS toolchains aren't included because I only have a Windows machine to test on. It's not on GitHub because they have an unnecessary file size limit.
Git LFS
My dream NGVCS has first class support for all the features I mentioned and more.
Git LFS is, imho, a hacky, second class citizen. It works and people use it. But it requires a bunch of extra effort and running extra commands.
Deployment
I have a related rant that not only should all dependencies be checked into the build system, but that deployments should also include all dependencies. Yes, deploy 2gb+ of CUDA dlls so your exe will reliably run. No, don't force me to use Docker to run your simple Python project.
Git Alternatives
There are a handful of interesting Git alternatives in the pipeline.
    Jujutsu - Git but better
    Pijul - Somewhat academic patch-based VCS
    Sapling - Open source version of Meta's VCS. Not fully usable outside of Meta infra.
    Xethub - Git at 100Tb scale to support massive ML models
Git isn't going to be replaced anytime soon, unfortunately. But there are a variety of projects exploring different ideas. VCS is far from a solved problem. Be open minded!
Package Managers
Package managers are not necessarily a silver bullet. Rust's Cargo is pretty good. NPM is fine I guess. Meanwhile Python's package ecosystem is an absolute disaster. There may be a compile-time vs run-time distinction here.
A good package manager is a decent solution. However package managers exist on a largely per-language basis. And sometimes per-platform. Committing dependencies is a guaranteed good solution for all languages on all platforms.
Polyglot projects that involve multiple languages need multiple package managers. Yuck.

# Document Title
git branches: intuition & reality
• git •
Hello! I’ve been working on writing a zine about git so I’ve been thinking about git branches a lot. I keep hearing from people that they find the way git branches work to be counterintuitive. It got me thinking: what might an “intuitive” notion of a branch be, and how is it different from how git actually works?
So in this post I want to briefly talk about
    an intuitive mental model I think many people have
    how git actually represents branches internally (“branches are a pointer to a commit” etc)
    how the “intuitive model” and the real way it works are actually pretty closely related
    some limits of the intuitive model and why it might cause problems
Nothing in this post is remotely groundbreaking so I’m going to try to keep it pretty short.
an intuitive model of a branch
Of course, people have many different intuitions about branches. Here’s the one that I think corresponds most closely to the physical “a branch of an apple tree” metaphor.
My guess is that a lot of people think about a git branch like this: the 2 commits in pink in this picture are on a “branch”.
I think there are two important things about this diagram:
    the branch has 2 commits on it
    the branch has a “parent” (main) which it’s an offshoot of
That seems pretty reasonable, but that’s not how git defines a branch – most importantly, git doesn’t have any concept of a branch’s “parent”. So how does git define a branch?
in git, a branch is the full history
In git, a branch is the full history of every previous commit, not just the “offshoot” commits. So in our picture above both branches (main and branch) have 4 commits on them.
I made an example repository at https://github.com/jvns/branch-example which has its branches set up the same way as in the picture above. Let’s look at the 2 branches:
main has 4 commits on it:
$ git log --oneline main
70f727a d
f654888 c
3997a46 b
a74606f a
and mybranch has 4 commits on it too. The bottom two commits are shared between both branches.
$ git log --oneline mybranch
13cb960 y
9554dab x
3997a46 b
a74606f a
So mybranch has 4 commits on it, not just the 2 commits 13cb960 and 9554dab that are “offshoot” commits.
You can get git to draw all the commits on both branches like this:
$ git log --all --oneline --graph
* 70f727a (HEAD -> main, origin/main) d
* f654888 c
| * 13cb960 (origin/mybranch, mybranch) y
| * 9554dab x
|/
* 3997a46 b
* a74606f a
a branch is stored as a commit ID
Internally in git, branches are stored as tiny text files which have a commit ID in them. That commit is the latest commit on the branch. This is the “technically correct” definition I was talking about at the beginning.
Let’s look at the text files for main and mybranch in our example repo:
$ cat .git/refs/heads/main
70f727acbe9ea3e3ed3092605721d2eda8ebb3f4
$ cat .git/refs/heads/mybranch
13cb960ad86c78bfa2a85de21cd54818105692bc
This makes sense: 70f727 is the latest commit on main and 13cb96 is the latest commit on mybranch.
The reason this works is that every commit contains a pointer to its parent(s), so git can follow the chain of pointers to get every commit on the branch.
Like I mentioned before, the thing that’s missing here is any relationship at all between these two branches. There’s no indication that mybranch is an offshoot of main.
Now that we’ve talked about how the intuitive notion of a branch is “wrong”, I want to talk about how it’s also right in some very important ways.
people’s intuition is usually not that wrong
I think it’s pretty popular to tell people that their intuition about git is “wrong”. I find that kind of silly – in general, even if people’s intuition about a topic is technically incorrect in some ways, people usually have the intuition they do for very legitimate reasons! “Wrong” models can be super useful.
So let’s talk about 3 ways the intuitive “offshoot” notion of a branch matches up very closely with how we actually use git in practice.
rebases use the “intuitive” notion of a branch
Now let’s go back to our original picture.
When you rebase mybranch on main, it takes the commits on the “intuitive” branch (just the 2 pink commits) and replays them onto main.
The result is that just the 2 (x and y) get copied. Here’s what that looks like:
$ git switch mybranch
$ git rebase main
$ git log --oneline mybranch
952fa64 (HEAD -> mybranch) y
7d50681 x
70f727a (origin/main, main) d
f654888 c
3997a46 b
a74606f a
Here git rebase has created two new commits (952fa64 and 7d50681) whose information comes from the previous two x and y commits.
So the intuitive model isn’t THAT wrong! It tells you exactly what happens in a rebase.
But because git doesn’t know that mybranch is an offshoot of main, you need to tell it explicitly where to rebase the branch.
merges use the “intuitive” notion of a branch too
Merges don’t copy commits, but they do need a “base” commit: the way merges work is that it looks at two sets of changes (starting from the shared base) and then merges them.
Let’s undo the rebase we just did and then see what the merge base is.
$ git switch mybranch
$ git reset --hard 13cb960  # undo the rebase
$ git merge-base main mybranch
3997a466c50d2618f10d435d36ef12d5c6f62f57
This gives us the “base” commit where our branch branched off, 3997a4. That’s exactly the commit you would think it might be based on our intuitive picture.
github pull requests also use the intuitive idea
If we create a pull request on GitHub to merge mybranch into main, it’ll also show us 2 commits: the commits x and y. That makes sense and also matches our intuitive notion of a branch.
I assume if you make a merge request on GitLab it shows you something similar.
intuition is pretty good, but it has some limits
This leaves our intuitive definition of a branch looking pretty good actually! The “intuitive” idea of what a branch is matches exactly with how merges and rebases and GitHub pull requests work.
You do need to explicitly specify the other branch when merging or rebasing or making a pull request (like git rebase main), because git doesn’t know what branch you think your offshoot is based on.
But the intuitive notion of a branch has one fairly serious problem: the way you intuitively think about main and an offshoot branch are very different, and git doesn’t know that.
So let’s talk about the different kinds of git branches.
trunk and offshoot branches
To a human, main and mybranch are pretty different, and you probably have pretty different intentions around how you want to use them.
I think it’s pretty normal to think of some branches as being “trunk” branches, and some branches as being “offshoots”. Also you can have an offshoot of an offshoot.
Of course, git itself doesn’t make any such distinctions (the term “offshoot” is one I just made up!), but what kind of a branch it is definitely affects how you treat it.
For example:
    you might rebase mybranch onto main but you probably wouldn’t rebase main onto mybranch – that would be weird!
    in general people are much more careful around rewriting the history on “trunk” branches than short-lived offshoot branches
git lets you do rebases “backwards”
One thing I think throws people off about git is – because git doesn’t have any notion of whether a branch is an “offshoot” of another branch, it won’t give you any guidance about if/when it’s appropriate to rebase branch X on branch Y. You just have to know.
for example, you can do either:
$ git checkout main
$ git rebase mybranch
or
$ git checkout mybranch
$ git rebase main
Git will happily let you do either one, even though in this case git rebase main is extremely normal and git rebase mybranch is pretty weird. A lot of people said they found this confusing so here’s a picture of the two kinds of rebases:
Similarly, you can do merges “backwards”, though that’s much more normal than doing a backwards rebase – merging mybranch into main and main into mybranch are both useful things to do for different reasons.
Here’s a diagram of the two ways you can merge:
git’s lack of hierarchy between branches is a little weird
I hear the statement “the main branch is not special” a lot and I’ve been puzzled about it – in most of the repositories I work in, main is pretty special! Why are people saying it’s not?
I think the point is that even though branches do have relationships between them (main is often special!), git doesn’t know anything about those relationships.
You have to tell git explicitly about the relationship between branches every single time you run a git command like git rebase or git merge, and if you make a mistake things can get really weird.
I don’t know whether git’s design here is “right” or “wrong” (it definitely has some pros and cons, and I’m very tired of reading endless arguments about it), but I do think it’s surprising to a lot of people for good reason.
git’s UI around branches is weird too
Let’s say you want to look at just the “offshoot” commits on a branch, which as we’ve discussed is a completely normal thing to want.
Here’s how to see just the 2 offshoot commits on our branch with git log:
$ git switch mybranch
$ git log main..mybranch --oneline
13cb960 (HEAD -> mybranch, origin/mybranch) y
9554dab x
You can look at the combined diff for those same 2 commits with git diff like this:
$ git diff main...mybranch
So to see the 2 commits x and y with git log, you need to use 2 dots (..), but to look at the same commits with git diff, you need to use 3 dots (...).
Personally I can never remember what .. and ... mean so I just avoid them completely even though in principle they seem useful.
in GitHub, the default branch is special
Also, it’s worth mentioning that GitHub does have a “special branch”: every github repo has a “default branch” (in git terms, it’s what HEAD points at), which is special in the following ways:
    it’s what you check out when you git clone the repository
    it’s the default destination for pull requests
    github will suggest that you protect the default branch from force pushes
and probably even more that I’m not thinking of.
that’s all!
This all seems extremely obvious in retrospect, but it took me a long time to figure out what a more “intuitive” idea of a branch even might be because I was so used to the technical “a branch is a reference to a commit” definition.
I also hadn’t really thought about how git makes you tell it about the hierarchy between your branches every time you run a git rebase or git merge command – for me it’s second nature to do that and it’s not a big deal, but now that I’m thinking about it, it’s pretty easy to see how somebody could get mixed up.

# Document Title
  Login / Register
all pages   recent changes  
    viewedithistorydiscuss
RosettaStone
    Translations with other distributed VCS
        Basic distributed version control
        Branching
        Adding, moving, removing files
        Inspecting the working directory
        Committing
        Inspecting the repository history
        Undoing
        Collaborating with others
        Advanced usage
    Translations from Subversion
    Discrepencies between DVCS
    See also
Translations with other distributed VCS
Basic distributed version control
The following commands have the same name in darcs, git and hg, with minor differences due to difference in concepts:
    init
    clone
    pull
    push
    log
Branching
concept 	darcs 	git 	hg
branch 	na 	branch 	branch
switch branch 	na [1] 	checkout 	update
    [1] No in-repo branching yet, see issue555
Adding, moving, removing files
concept 	darcs 	git 	hg
track file 	add 	add 	add
copy file 	na 	na 	copy
move/rename file 	move 	mv 	rename
Inspecting the working directory
concept 	darcs 	git 	hg
working dir status 	whatsnew -s 	status 	status
high-level local diff 	whatsnew 	na 	na
diff local 	diff [1] 	diff 	diff
    [1] we tend to use the high-level local diff (darcs whatsnew) instead. This displays the patches themselves (eg ‘mv foo bar’) and not just their effects (eg ‘rm foo’ followed by “add bar”)
Committing
concept 	darcs 	git 	hg
commit locally 	record 	commit 	commit
amend commit 	amend 	commit –amend 	commit –amend
tag changes/revisions 	tag 	tag 	tag
Inspecting the repository history
concept 	darcs 	git 	hg
log 	log 	log 	log
log with diffs 	log -v 	log -p 	log -p
manifest 	show files 	ls-files 	manifest
summarise outgoing changes 	push –dry-run 	log origin/master .. 	outgoing
summarise incoming changes 	pull –dry-run 	log ..origin/mast er 	incoming
diff repos or versions 	diff 	diff 	incoming /outgoing/dif f -r
blame/annotate 	annotate 	blame 	annotate
Undoing
concept 	darcs 	git 	hg
revert a file 	revert foo 	checkout foo 	revert foo
revert full working copy 	revert 	reset –hard 	revert -a
undo commit (leaving working copy untouched) 	unrecord 	reset –soft 	rollback
amend commit 	amend 	commit –amend 	commit –amend
destroy last patch/ changeset 	obliterate 	delete the commit 	strip [1]
destroy any patch/ changeset 	obliterate 	rebase -i, delete the commit 	strip [1]
create anti-changeset 	rollback 	revert 	backout
    [1] requires extension (mq for strip)
Collaborating with others
concept 	darcs 	git 	hg
send by mail 	send 	send-email 	email [1]
    [1] requires extension (patchbomb for email)
Advanced usage
concept 	darcs 	git 	hg
port commit to X 	rebase 	rebase/cherry -pick 	transplant
Translations from Subversion
Subversion idiom 	Similar darcs idiom
svn checkout 	darcs clone
svn update 	darcs pull
svn status -u 	darcs pull –dry-run (summarize remote changes)
svn status 	darcs whatsnew –summary (summarize local changes)
svn status | grep ‘?’ 	darcs whatsnew -ls | grep ^a (list potential files to add)
svn revert foo.txt 	darcs revert foo.txt (revert to foo.txt from repo)
svn diff 	darcs whatsnew (for local changes)
svn diff 	darcs diff (for local and recorded changes)
svn commit 	darcs record + darcs push
svn diff | mail 	darcs send
svn add 	darcs add
svn log 	darcs log
Discrepencies between DVCS
Git has the notion of an index (which affects the meanings of some of the commands), Darcs just has its simple branch-is-repo-is-workspace model.
See also
    Features
    Differences from Git
    Differences from Subversion
    Wikipedia’s comparison of revision control systems
Wiki source: darcs get --lazy http://darcs.net/darcs-wiki
Powered by: gitit + darcs

# Document Title
How git cherry-pick and revert use 3-way merge
• git •
Hello! I was trying to explain to someone how git cherry-pick works the other day, and I found myself getting confused.
What went wrong was: I thought that git cherry-pick was basically applying a patch, but when I tried to actually do it that way, it didn’t work!
Let’s talk about what I thought cherry-pick did (applying a patch), why that’s not quite true, and what it actually does instead (a “3-way merge”).
This post is extremely in the weeds and you definitely don’t need to understand this stuff to use git effectively. But if you (like me) are curious about git’s internals, let’s talk about it!
cherry-pick isn’t applying a patch
The way I previously understood git cherry-pick COMMIT_ID is:
    calculate the diff for COMMIT_ID, like git show COMMIT_ID --patch > out.patch
    Apply the patch to the current branch, like git apply out.patch
Before we get into this – I want to be clear that this model is mostly right, and if that’s your mental model that’s fine. But it’s wrong in some subtle ways and I think that’s kind of interesting, so let’s see how it works.
If I try to do the “calculate the diff and apply the patch” thing in a case where there’s a merge conflict, here’s what happens:
$ git show 10e96e46 --patch > out.patch
$ git apply out.patch
error: patch failed: content/post/2023-07-28-why-is-dns-still-hard-to-learn-.markdown:17
error: content/post/2023-07-28-why-is-dns-still-hard-to-learn-.markdown: patch does not apply
This just fails – it doesn’t give me any way to resolve the conflict or figure out how to solve the problem.
This is quite different from what actually happens when run git cherry-pick, which is that I get a merge conflict:
$ git cherry-pick 10e96e46
error: could not apply 10e96e46... wip
hint: After resolving the conflicts, mark them with
hint: "git add/rm <pathspec>", then run
hint: "git cherry-pick --continue".
So it seems like the “git is applying a patch” model isn’t quite right. But the error message literally does say “could not apply 10e96e46”, so it’s not quite wrong either. What’s going on?
so what is cherry-pick doing?
I went digging through git’s source code to see how cherry-pick works, and ended up at this line of code:
res = do_recursive_merge(r, base, next, base_label, next_label, &head, &msgbuf, opts);
So a cherry-pick is a… merge? What? How? What is it even merging? And how does merging even work in the first place?
I realized that I didn’t really know how git’s merge worked, so I googled it and found out that git does a thing called “3-way merge”. What’s that?
how git merges files: the 3-way merge
Let’s say I want to merge these 2 files. We’ll call them v1.py and v2.py.
def greet():
    greeting = "hello"
    name = "julia"
    return greeting + " " + name
def say_hello():
    greeting = "hello"
    name = "aanya"
    return greeting + " " + name
There are two lines that differ: we have
    def greet() and def say_hello
    name = "aanya" and name = "julia"
How do we know what to pick? It seems impossible!
But what if I told you that the original function was this (base.py)?
def say_hello():
    greeting = "hello"
    name = "julia"
    return greeting + " " + name
Suddenly it seems a lot clearer! v1 changed the function’s name to greet and v2 set name = "aanya". So to merge, we should make both those changes:
def greet():
    greeting = "hello"
    name = "aanya"
    return greeting + " " + name
We can ask git to do this merge with git merge-file, and it gives us exactly the result we expected: it picks def greet() and name = "aanya".
$ git merge-file v1.py base.py v2.py -p
def greet():
    greeting = "hello"
    name = "aanya"
    return greeting + " " + name⏎
This way of merging where you merge 2 files + their original version is called a 3-way merge.
If you want to try it out yourself in a browser, I made a little playground at jvns.ca/3-way-merge/. I made it very quickly so it’s not mobile friendly.
git merges changes, not files
The way I think about the 3-way merge is – git merges changes, not files. We have an original file and 2 possible changes to it, and git tries to combine both of those changes in a reasonable way. Sometimes it can’t (for example if both changes change the same line), and then you get a merge conflict.
Git can also merge more than 2 possible changes: you can have an original file and 8 possible changes, and it can try to reconcile all of them. That’s called an octopus merge but I don’t know much more than that, I’ve never done one.
how git uses 3-way merge to apply a patch
Now let’s get a little weird! When we talk about git “applying a patch” (as you do in a rebase or revert or cherry-pick), it’s not actually creating a patch file and applying it. Instead, it’s doing a 3-way merge.
Here’s how applying commit X as a patch to your current commit corresponds to this v1, v2, and base setup from before:
    The version of the file in your current commit is v1.
    The version of the file before commit X is base
    The version of the file in commit X. Call that v2
    Run git merge-file v1 base v2 to combine them (technically git does not actually run git merge-file, it runs a C function that does it)
Together, you can think of base and v2 as being the “patch”: the diff between them is the change that you want to apply to v1.
how cherry-pick works
Let’s say we have this commit graph, and we want to cherry-pick Y on to main:
A - B (main)
 \
  \
   X - Y - Z
How do we turn that into a 3-way merge? Here’s how it translates into our v1, v2 and base from earlier:
    B is v1
    X is the base, Y is v2
So together X and Y are the “patch”.
And git rebase is just like git cherry-pick, but repeated a bunch of times.
how revert works
Now let’s say we want to run git revert Y on this commit graph
X - Y - Z - A - B
    B is v1
    Y is the base, X is v2
This is exactly like a cherry-pick, but with X and Y reversed. We have to flip them because we want to apply a “reverse patch”.
Revert and cherry-pick are so closely related in git that they’re actually implemented in the same file: revert.c.
this “3-way patch” is a really cool trick
This trick of using a 3-way merge to apply a commit as a patch seems really clever and cool and I’m surprised that I’d never heard of it before! I don’t know of a name for it, but I kind of want to call it a “3-way patch”.
The idea is that with a 3-way patch, you specify the patch as 2 files: the file before the patch and after (base and v2 in our language in this post).
So there are 3 files involved: 1 for the original and 2 for the patch.
The point is that the 3-way patch is a much better way to patch than a normal patch, because you have a lot more context for merging when you have both full files.
Here’s more or less what a normal patch for our example looks like:
@@ -1,1 +1,1 @@:
- def greet():
+ def say_hello():
    greeting = "hello"
and a 3-way patch. This “3-way patch” is not a real file format, it’s just something I made up.
BEFORE: (the full file)
def greet():
    greeting = "hello"
    name = "julia"
    return greeting + " " + name
AFTER: (the full file)
def say_hello():
    greeting = "hello"
    name = "julia"
    return greeting + " " + name
“Building Git” talks about this
The book Building Git by James Coglan is the only place I could find other than the git source code explaining how git cherry-pick actually uses 3-way merge under the hood (I thought Pro Git might talk about it, but it didn’t seem to as far as I could tell).
I actually went to buy it and it turned out that I’d already bought it in 2019 so it was a good reference to have here :)
merging is actually much more complicated than this
There’s more to merging in git than the 3-way merge – there’s something called a “recursive merge” that I don’t understand, and there are a bunch of details about how to deal with handling file deletions and moves, and there are also multiple merge algorithms.
My best idea for where to learn more about this stuff is Building Git, though I haven’t read the whole thing.
so what does git apply do?
I also went looking through git’s source to find out what git apply does, and it seems to (unsurprisingly) be in apply.c. That code parses a patch file, and then hunts through the target file to figure out where to apply it. The core logic seems to be around here: I think the idea is to start at the line number that the patch suggested and then hunt forwards and backwards from there to try to find it:
	/*
	 * There's probably some smart way to do this, but I'll leave
	 * that to the smart and beautiful people. I'm simple and stupid.
	 */
	backwards = current;
	backwards_lno = line;
	forwards = current;
	forwards_lno = line;
	current_lno = line;
  for (i = 0; ; i++) {
     ...
That all seems pretty intuitive and about what I’d naively expect.
how git apply --3way works
git apply also has a --3way flag that does a 3-way merge. So we actually could have more or less implemented git cherry-pick with git apply like this:
$ git show 10e96e46 --patch > out.patch
$ git apply out.patch --3way
Applied patch to 'content/post/2023-07-28-why-is-dns-still-hard-to-learn-.markdown' with conflicts.
U content/post/2023-07-28-why-is-dns-still-hard-to-learn-.markdown
--3way doesn’t just use the contents of the patch file though! The patch file starts with:
index d63ade04..65778fc0 100644
d63ade04 and 65778fc0 are the IDs of the old/new versions of that file in git’s object database, so git can retrieve them to do a 3-way patch application. This won’t work if someone emails you a patch and you don’t have the files for the new/old versions of the file though: if you’re missing the blobs you’ll get this error:
$ git apply out.patch
error: repository lacks the necessary blob to perform 3-way merge.
3-way merge is old
A couple of people pointed out that 3-way merge is much older than git, it’s from the late 70s or something. Here’s a paper from 2007 talking about it
that’s all!
I was pretty surprised to learn that I didn’t actually understand the core way that git applies patches internally – it was really cool to learn about!
I have lots of issues with git’s UI but I think this particular thing is not one of them. The 3-way merge seems like a nice unified way to solve a bunch of different problems, it’s pretty intuitive for people (the idea of “applying a patch” is one that a lot of programmers are used to thinking about, and the fact that it’s implemented as a 3-way merge under the hood is an implementation detail that nobody actually ever needs to think about).
Also a very quick plug: I’m working on writing a zine about git, if you’re interested in getting an email when it comes out you can sign up to my very infrequent announcements mailing list.

# Document Title
git rebase: what can go wrong?
Hello! While talking with folks about Git, I’ve been seeing a comment over and over to the effect of “I hate rebase”. People seemed to feel pretty strongly about this, and I was really surprised because I don’t run into a lot of problems with rebase and I use it all the time.
I’ve found that if many people have a very strong opinion that’s different from mine, usually it’s because they have different experiences around that thing from me.
So I asked on Mastodon:
    today I’m thinking about the tradeoffs of using git rebase a bit. I think the goal of rebase is to have a nice linear commit history, which is something I like.
    but what are the costs of using rebase? what problems has it caused for you in practice? I’m really only interested in specific bad experiences you’ve had here – not opinions or general statements like “rewriting history is bad”
I got a huge number of incredible answers to this, and I’m going to do my best to summarize them here. I’ll also mention solutions or workarounds to those problems in cases where I know of a solution. Here’s the list:
    fixing the same conflict repeatedly is annoying
    rebasing a lot of commits is hard
    undoing a rebase is hard
    force pushing to shared branches can cause lost work
    force pushing makes code reviews harder
    losing commit metadata
    more difficult reverts
    rebasing can break intermediate commits
    accidentally run git commit –amend instead of git rebase –continue
    splitting commits in an interactive rebase is hard
    complex rebases are hard
    rebasing long lived branches can be annoying
    rebase and commit discipline
    a “squash and merge” workflow
    miscellaneous problems
My goal with this isn’t to convince anyone that rebase is bad and you shouldn’t use it (I’m certainly going to keep using rebase!). But seeing all these problems made me want to be more cautious about recommending rebase to newcomers without explaining how to use it safely. It also makes me wonder if there’s an easier workflow for cleaning up your commit history that’s harder to accidentally mess up.
my git workflow assumptions
First, I know that people use a lot of different Git workflows. I’m going to be talking about the workflow I’m used to when working on a team, which is:
    the team uses a central Github/Gitlab repo to coordinate
    there’s one central main branch. It’s protected from force pushes.
    people write code in feature branches and make pull requests to main
    The web service is deployed from main every time a pull request is merged.
    the only way to make a change to main is by making a pull request on Github/Gitlab and merging it
This is not the only “correct” git workflow (it’s a very “we run a web service” workflow and open source project or desktop software with releases generally use a slightly different workflow). But it’s what I know so that’s what I’ll talk about.
two kinds of rebase
Also before we start: one big thing I noticed is that there were 2 different kinds of rebase that kept coming up, and only one of them requires you to deal with merge conflicts.
    rebasing on an ancestor, like git rebase -i HEAD^^^^^^^ to squash many small commits into one. As long as you’re just squashing commits, you’ll never have to resolve a merge conflict while doing this.
    rebasing onto a branch that has diverged, like git rebase main. This can cause merge conflicts.
I think it’s useful to make this distinction because sometimes I’m thinking about rebase type 1 (which is a lot less likely to cause problems), but people who are struggling with it are thinking about rebase type 2.
Now let’s move on to all the problems!
fixing the same conflict repeatedly is annoying
If you make many tiny commits, sometimes you end up in a hellish loop where you have to fix the same merge conflict 10 times. You can also end up fixing merge conflicts totally unnecessarily (like dealing with a merge conflict in code that a future commit deletes).
There are a few ways to make this better:
    first do a git rebase -i HEAD^^^^^^^^^^^ to squash all of the tiny commits into 1 big commit and then a git rebase main to rebase onto a different branch. Then you only have to fix the conflicts once.
    use git rerere to automate repeatedly resolving the same merge conflicts (“rerere” stands for “reuse recorded resolution”, it’ll record your previous merge conflict resolutions and replay them). I’ve never tried this but I think you need to set git config rerere.enabled true and then it’ll automatically help you.
Also if I find myself resolving merge conflicts more than once in a rebase, I’ll usually run git rebase --abort to stop it and then squash my commits into one and try again.
rebasing a lot of commits is hard
Generally when I’m doing a rebase onto a different branch, I’m rebasing 1-2 commits. Maybe sometimes 5! Usually there are no conflicts and it works fine.
Some people described rebasing hundreds of commits by many different people onto a different branch. That sounds really difficult and I don’t envy that task.
undoing a rebase is hard
I heard from several people that when they were new to rebase, they messed up a rebase and permanently lost a week of work that they then had to redo.
The problem here is that undoing a rebase that went wrong is much more complicated than undoing a merge that went wrong (you can undo a bad merge with something like git reset --hard HEAD^). Many newcomers to rebase don’t even realize that undoing a rebase is even possible, and I think it’s pretty easy to understand why.
That said, it is possible to undo a rebase that went wrong. Here’s an example of how to undo a rebase using git reflog.
step 1: Do a bad rebase (for example run git rebase -I HEAD^^^^^ and just delete 3 commits)
step 2: Run git reflog. You should see something like this:
ee244c4 (HEAD -> main) HEAD@{0}: rebase (finish): returning to refs/heads/main
ee244c4 (HEAD -> main) HEAD@{1}: rebase (pick): test
fdb8d73 HEAD@{2}: rebase (start): checkout HEAD^^^^^^^
ca7fe25 HEAD@{3}: commit: 16 bits by default
073bc72 HEAD@{4}: commit: only show tooltips on desktop
step 3: Find the entry immediately before rebase (start). In my case that’s ca7fe25
step 4: Run git reset --hard ca7fe25
A couple of other ways to undo a rebase:
    Apparently @ always refers to your current branch in git, so you can run git reset --hard @{1} to reset your branch to its previous location.
    Another solution folks mentioned that avoids having to use the reflog is to make a “backup branch” with git switch -c backup before rebasing, so you can easily get back to the old commit.
force pushing to shared branches can cause lost work
A few people mentioned the following situation:
    You’re collaborating on a branch with someone
    You push some changes
    They rebase the branch and run git push --force (maybe by accident)
    Now when you run git pull, it’s a mess – you get the a fatal: Need to specify how to reconcile divergent branches error
    While trying to deal with the fallout you might lose some commits, especially if some of the people are involved aren’t very comfortable with git
This is an even worse situation than the “undoing a rebase is hard” situation because the missing commits might be split across many different people’s and the only worse thing than having to hunt through the reflog is multiple different people having to hunt through the reflog.
This has never happened to me because the only branch I’ve ever collaborated on is main, and main has always been protected from force pushing (in my experience the only way you can get something into main is through a pull request). So I’ve never even really been in a situation where this could happen. But I can definitely see how this would cause problems.
The main tools I know to avoid this are:
    don’t rebase on shared branches
    use --force-with-lease when force pushing, to make sure that nobody else has pushed to the branch since your last fetch
Apparently the “since your last fetch” is important here – if you run git fetch immediately before running git push --force-with-lease, the --force-with-lease won’t protect you at all.
I was curious about why people would run git push --force on a shared branch. Some reasons people gave were:
    they’re working on a collaborative feature branch, and the feature branch needs to be rebased onto main. The idea here is that you’re just really careful about coordinating the rebase so nothing gets lost.
    as an open source maintainer, sometimes they need to rebase a contributor’s branch to fix a merge conflict
    they’re new to git, read some instructions online that suggested git rebase and git push --force as a solution, and followed them without understanding the consequences
    they’re used to doing git push --force on a personal branch and ran it on a shared branch by accident
force pushing makes code reviews harder
The situation here is:
    You make a pull request on GitHub
    People leave some comments
    You update the code to address the comments, rebase to clean up your commits, and force push
    Now when the reviewer comes back, it’s hard for them to tell what you changed since the last time you saw it – all the commits show up as “new”.
One way to avoid this is to push new commits addressing the review comments, and then after the PR is approved do a rebase to reorganize everything.
I think some reviewers are more annoyed by this problem than others, it’s kind of a personal preference. Also this might be a Github-specific issue, other code review tools might have better tools for managing this.
losing commit metadata
If you’re rebasing to squash commits, you can lose important commit metadata like Co-Authored-By. Also if you GPG sign your commits, rebase loses the signatures.
There’s probably other commit metadata that you can lose that I’m not thinking of.
I haven’t run into this one so I’m not sure how to avoid it. I think GPG signing commits isn’t as popular as it used to be.
more difficult reverts
Someone mentioned that it’s important for them to be able to easily revert merging any branch (in case the branch broke something), and if the branch contains multiple commits and was merged with rebase, then you need to do multiple reverts to undo the commits.
In a merge workflow, I think you can revert merging any branch just by reverting the merge commit.
rebasing can break intermediate commits
If you’re trying to have a very clean commit history where the tests pass on every commit (very admirable!), rebasing can result in some intermediate commits that are broken and don’t pass the tests, even if the final commit passes the tests.
Apparently you can avoid this by using git rebase -x to run the test suite at every step of the rebase and make sure that the tests are still passing. I’ve never done that though.
accidentally run git commit --amend instead of git rebase --continue
A couple of people mentioned issues with running git commit --amend instead of git rebase --continue when resolving a merge conflict.
The reason this is confusing is that there are two reasons when you might want to edit files during a rebase:
    editing a commit (by using edit in git rebase -i), where you need to write git commit --amend when you’re done
    a merge conflict, where you need to run git rebase --continue when you’re done
It’s very easy to get these two cases mixed up because they feel very similar. I think what goes wrong here is that you:
    Start a rebase
    Run into a merge conflict
    Resolve the merge conflict, and run git add file.txt
    Run git commit because that’s what you’re used to doing after you run git add
    But you were supposed to run git rebase --continue! Now you have a weird extra commit, and maybe it has the wrong commit message and/or author
splitting commits in an interactive rebase is hard
The whole point of rebase is to clean up your commit history, and combining commits with rebase is pretty easy. But what if you want to split up a commit into 2 smaller commits? It’s not as easy, especially if the commit you want to split is a few commits back! I actually don’t really know how to do it even though I feel very comfortable with rebase. I’d probably just do git reset HEAD^^^ or something and use git add -p to redo all my commits from scratch.
One person shared their workflow for splitting commits with rebase.
complex rebases are hard
If you try to do too many things in a single git rebase -i (reorder commits AND combine commits AND modify a commit), it can get really confusing.
To avoid this, I personally prefer to only do 1 thing per rebase, and if I want to do 2 different things I’ll do 2 rebases.
rebasing long lived branches can be annoying
If your branch is long-lived (like for 1 month), having to rebase repeatedly gets painful. It might be easier to just do 1 merge at the end and only resolve the conflicts once.
The dream is to avoid this problem by not having long-lived branches but it doesn’t always work out that way in practice.
miscellaneous problems
A few more issues that I think are not that common:
    Stopping a rebase wrong: If you try to abort a rebase that’s going badly with git reset --hard instead of git rebase --abort, things will behave weirdly until you stop it properly
    Weird interactions with merge commits: A couple of quotes about this: “If you rebase your working copy to keep a clean history for a branch, but the underlying project uses merges, the result can be ugly. If you do rebase -i HEAD~4 and the fourth commit back is a merge, you can see dozens of commits in the interactive editor.“, “I’ve learned the hard way to never rebase if I’ve merged anything from another branch”
rebase and commit discipline
I’ve seen a lot of people arguing about rebase. I’ve been thinking about why this is and I’ve noticed that people work at a few different levels of “commit discipline”:
    Literally anything goes, “wip”, “fix”, “idk”, “add thing”
    When you make a pull request (on github/gitlab), squash all of your crappy commits into a single commit with a reasonable message (usually the PR title)
    Atomic Beautiful Commits – every change is split into the appropriate number of commits, where each one has a nice commit message and where they all tell a story around the change you’re making
Often I think different people inside the same company have different levels of commit discipline, and I’ve seen people argue about this a lot. Personally I’m mostly a Level 2 person. I think Level 3 might be what people mean when they say “clean commit history”.
I think Level 1 and Level 2 are pretty easy to achieve without rebase – for level 1, you don’t have to do anything, and for level 2, you can either press “squash and merge” in github or run git switch main; git merge --squash mybranch on the command line.
But for Level 3, you either need rebase or some other tool (like GitUp) to help you organize your commits to tell a nice story.
I’ve been wondering if when people argue about whether people “should” use rebase or not, they’re really arguing about which minimum level of commit discipline should be required.
I think how this plays out also depends on how big the changes folks are making – if folks are usually making pretty small pull requests anyway, squashing them into 1 commit isn’t a big deal, but if you’re making a 6000-line change you probably want to split it up into multiple commits.
a “squash and merge” workflow
A couple of people mentioned using this workflow that doesn’t use rebase:
    make commits
    Run git merge main to merge main into the branch periodically (and fix conflicts if necessary)
    When you’re done, use GitHub’s “squash and merge” feature (which is the equivalent of running git checkout main; git merge --squash mybranch) to squash all of the changes into 1 commit. This gets rid of all the “ugly” merge commits.
I originally thought this would make the log of commits on my branch too ugly, but apparently git log main..mybranch will just show you the changes on your branch, like this:
$ git log main..mybranch
756d4af (HEAD -> mybranch) Merge branch 'main' into mybranch
20106fd Merge branch 'main' into mybranch
d7da423 some commit on my branch
85a5d7d some other commit on my branch
Of course, the goal here isn’t to force people who have made beautiful atomic commits to squash their commits – it’s just to provide an easy option for folks to clean up a messy commit history (“add new feature; wip; wip; fix; fix; fix; fix; fix;“) without having to use rebase.
I’d be curious to hear about other people who use a workflow like this and if it works well.
there are more problems than I expected
I went into this really feeling like “rebase is fine, what could go wrong?” But many of these problems actually have happened to me in the past, it’s just that over the years I’ve learned how to avoid or fix all of them.
And I’ve never really seen anyone share best practices for rebase, other than “never force push to a shared branch”. All of these honestly make me a lot more reluctant to recommend using rebase.
To recap, I think these are my personal rebase rules I follow:
    stop a rebase if it’s going badly instead of letting it finish (with git rebase --abort)
    know how to use git reflog to undo a bad rebase
    don’t rebase a million tiny commits (instead do it in 2 steps: git rebase -i HEAD^^^^ and then git rebase main)
    don’t do more than one thing in a git rebase -i. Keep it simple.
    never force push to a shared branch
    never rebase commits that have already been pushed to main
Thanks to Marco Rogers for encouraging me to think about the problems people have with rebase, and to everyone on Mastodon who helped with this.

# Document Title
Confusing git terminology
• git •
Hello! I’m slowly working on explaining git. One of my biggest problems is that after almost 15 years of using git, I’ve become very used to git’s idiosyncracies and it’s easy for me to forget what’s confusing about it.
So I asked people on Mastodon:
    what git jargon do you find confusing? thinking of writing a blog post that explains some of git’s weirder terminology: “detached HEAD state”, “fast-forward”, “index/staging area/staged”, “ahead of ‘origin/main’ by 1 commit”, etc
I got a lot of GREAT answers and I’ll try to summarize some of them here. Here’s a list of the terms:
    HEAD and “heads”
    “detached HEAD state”
    “ours” and “theirs” while merging or rebasing
    “Your branch is up to date with ‘origin/main’”
    HEAD^, HEAD~ HEAD^^, HEAD~~, HEAD^2, HEAD~2
    .. and …
    “can be fast-forwarded”
    “reference”, “symbolic reference”
    refspecs
    “tree-ish”
    “index”, “staged”, “cached”
    “reset”, “revert”, “restore”
    “untracked files”, “remote-tracking branch”, “track remote branch”
    checkout
    reflog
    merge vs rebase vs cherry-pick
    rebase –onto
    commit
    more confusing terms
I’ve done my best to explain what’s going on with these terms, but they cover basically every single major feature of git which is definitely too much for a single blog post so it’s pretty patchy in some places.
HEAD and “heads”
A few people said they were confused by the terms HEAD and refs/heads/main, because it sounds like it’s some complicated technical internal thing.
Here’s a quick summary:
    “heads” are “branches”. Internally in git, branches are stored in a directory called .git/refs/heads. (technically the official git glossary says that the branch is all the commits on it and the head is just the most recent commit, but they’re 2 different ways to think about the same thing)
    HEAD is the current branch. It’s stored in .git/HEAD.
I think that “a head is a branch, HEAD is the current branch” is a good candidate for the weirdest terminology choice in git, but it’s definitely too late for a clearer naming scheme so let’s move on.
There are some important exceptions to “HEAD is the current branch”, which we’ll talk about next.
“detached HEAD state”
You’ve probably seen this message:
$ git checkout v0.1
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
[...]
Here’s the deal with this message:
    In Git, usually you have a “current branch” checked out, for example main.
    The place the current branch is stored is called HEAD.
    Any new commits you make will get added to your current branch, and if you run git merge other_branch, that will also affect your current branch
    But HEAD doesn’t have to be a branch! Instead it can be a commit ID.
    Git calls this state (where HEAD is a commit ID instead of a branch) “detached HEAD state”
    For example, you can get into detached HEAD state by checking out a tag, because a tag isn’t a branch
    if you don’t have a current branch, a bunch of things break:
        git pull doesn’t work at all (since the whole point of it is to update your current branch)
        neither does git push unless you use it in a special way
        git commit, git merge, git rebase, and git cherry-pick do still work, but they’ll leave you with “orphaned” commits that aren’t connected to any branch, so those commits will be hard to find
    You can get out of detached HEAD state by either creating a new branch or switching to an existing branch
“ours” and “theirs” while merging or rebasing
If you have a merge conflict, you can run git checkout --ours file.txt to pick the version of file.txt from the “ours” side. But which side is “ours” and which side is “theirs”?
I always find this confusing and I never use git checkout --ours because of that, but I looked it up to see which is which.
For merges, here’s how it works: the current branch is “ours” and the branch you’re merging in is “theirs”, like this. Seems reasonable.
$ git checkout merge-into-ours # current branch is "ours"
$ git merge from-theirs # branch we're merging in is "theirs"
For rebases it’s the opposite – the current branch is “theirs” and the target branch we’re rebasing onto is “ours”, like this:
$ git checkout theirs # current branch is "theirs"
$ git rebase ours # branch we're rebasing onto is "ours"
I think the reason for this is that under the hood git rebase main is repeatedly merging commits from the current branch into a copy of the main branch (you can see what I mean by that in this weird shell script the implements git rebase using git merge. But I still find it confusing.
This nice tiny site explains the “ours” and “theirs” terms.
A couple of people also mentioned that VSCode calls “ours”/“theirs” “current change”/“incoming change”, and that it’s confusing in the exact same way.
“Your branch is up to date with ‘origin/main’”
This message seems straightforward – it’s saying that your main branch is up to date with the origin!
But it’s actually a little misleading. You might think that this means that your main branch is up to date. It doesn’t. What it actually means is – if you last ran git fetch or git pull 5 days ago, then your main branch is up to date with all the changes as of 5 days ago.
So if you don’t realize that, it can give you a false sense of security.
I think git could theoretically give you a more useful message like “is up to date with the origin’s main as of your last fetch 5 days ago” because the time that the most recent fetch happened is stored in the reflog, but it doesn’t.
HEAD^, HEAD~ HEAD^^, HEAD~~, HEAD^2, HEAD~2
I’ve known for a long time that HEAD^ refers to the previous commit, but I’ve been confused for a long time about the difference between HEAD~ and HEAD^.
I looked it up, and here’s how these relate to each other:
    HEAD^ and HEAD~ are the same thing (1 commit ago)
    HEAD^^^ and HEAD~~~ and HEAD~3 are the same thing (3 commits ago)
    HEAD^3 refers the the third parent of a commit, and is different from HEAD~3
This seems weird – why are HEAD~ and HEAD^ the same thing? And what’s the “third parent”? Is that the same thing as the parent’s parent’s parent? (spoiler: it isn’t) Let’s talk about it!
Most commits have only one parent. But merge commits have multiple parents – they’re merging together 2 or more commits. In Git HEAD^ means “the parent of the HEAD commit”. But what if HEAD is a merge commit? What does HEAD^ refer to?
The answer is that HEAD^ refers to the the first parent of the merge, HEAD^2 is the second parent, HEAD^3 is the third parent, etc.
But I guess they also wanted a way to refer to “3 commits ago”, so HEAD^3 is the third parent of the current commit (which may have many parents if it’s a merge commit), and HEAD~3 is the parent’s parent’s parent.
I think in the context of the merge commit ours/theirs discussion earlier, HEAD^ is “ours” and HEAD^2 is “theirs”.
.. and ...
Here are two commands:
    git log main..test
    git log main...test
What’s the difference between .. and ...? I never use these so I had to look it up in man git-range-diff. It seems like the answer is that in this case:
A - B main
  \ 
    C - D test
    main..test is commits C and D
    test..main is commit B
    main...test is commits B, C, and D
But it gets worse: apparently git diff also supports .. and ..., but they do something completely different than they do with git log? I think the summary is:
    git log test..main shows changes on main that aren’t on test, whereas git log test...main shows changes on both sides.
    git diff test..main shows test changes and main changes (it diffs B and D) whereas git diff test...main diffs A and D (it only shows you the diff on one side).
this blog post talks about it a bit more.
“can be fast-forwarded”
Here’s a very common message you’ll see in git status:
$ git status
On branch main
Your branch is behind 'origin/main' by 2 commits, and can be fast-forwarded.
  (use "git pull" to update your local branch)
What does “fast-forwarded” mean? Basically it’s trying to say that the two branches look something like this: (newest commits are on the right)
main:        A - B - C
origin/main: A - B - C - D - E
or visualized another way:
A - B - C - D - E (origin/main)
        |
       main
Here origin/main just has 2 extra commits that main doesn’t have, so it’s easy to bring main up to date – we just need to add those 2 commits. Literally nothing can possibly go wrong – there’s no possibility of merge conflicts. A fast forward merge is a very good thing! It’s the easiest way to combine 2 branches.
After running git pull, you’ll end up this state:
main:        A - B - C - D - E
origin/main: A - B - C - D - E
Here’s an example of a state which can’t be fast-forwarded.
             A - B - C - X  (main)
                     |
                     - - D - E  (origin/main)
Here main has a commit that origin/main doesn’t have (X). So you can’t do a fast forward. In that case, git status would say:
$ git status
Your branch and 'origin/main' have diverged,
and have 1 and 2 different commits each, respectively.
“reference”, “symbolic reference”
I’ve always found the term “reference” kind of confusing. There are at least 3 things that get called “references” in git
    branches and tags like main and v0.2
    HEAD, which is the current branch
    things like HEAD^^^ which git will resolve to a commit ID. Technically these are probably not “references”, I guess git calls them “revision parameters” but I’ve never used that term.
“symbolic reference” is a very weird term to me because personally I think the only symbolic reference I’ve ever used is HEAD (the current branch), and HEAD has a very central place in git (most of git’s core commands’ behaviour depends on the value of HEAD), so I’m not sure what the point of having it as a generic concept is.
refspecs
When you configure a git remote in .git/config, there’s this +refs/heads/main:refs/remotes/origin/main thing.
[remote "origin"]
	url = git@github.com:jvns/pandas-cookbook
	fetch = +refs/heads/main:refs/remotes/origin/main
I don’t really know what this means, I’ve always just used whatever the default is when you do a git clone or git remote add, and I’ve never felt any motivation to learn about it or change it from the default.
“tree-ish”
The man page for git checkout says:
 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...
What’s tree-ish??? What git is trying to say here is when you run git checkout THING ., THING can be either:
    a commit ID (like 182cd3f)
    a reference to a commit ID (like main or HEAD^^ or v0.3.2)
    a subdirectory inside a commit (like main:./docs)
    I think that’s it????
Personally I’ve never used the “directory inside a commit” thing and from my perspective “tree-ish” might as well just mean “commit or reference to commit”.
“index”, “staged”, “cached”
All of these refer to the exact same thing (the file .git/index, which is where your changes are staged when you run git add):
    git diff --cached
    git rm --cached
    git diff --staged
    the file .git/index
Even though they all ultimately refer to the same file, there’s some variation in how those terms are used in practice:
    Apparently the flags --index and --cached do not generally mean the same thing. I have personally never used the --index flag so I’m not going to get into it, but this blog post by Junio Hamano (git’s lead maintainer) explains all the gnarly details
    the “index” lists untracked files (I guess for performance reasons) but you don’t usually think of the “staging area” as including untracked files”
“reset”, “revert”, “restore”
A bunch of people mentioned that “reset”, “revert” and “restore” are very similar words and it’s hard to differentiate them.
I think it’s made worse because
    git reset --hard and git restore . on their own do basically the same thing. (though git reset --hard COMMIT and git restore --source COMMIT . are completely different from each other)
    the respective man pages don’t give very helpful descriptions:
        git reset: “Reset current HEAD to the specified state”
        git revert: “Revert some existing commits”
        git restore: “Restore working tree files”
Those short descriptions do give you a better sense for which noun is being affected (“current HEAD”, “some commits”, “working tree files”) but they assume you know what “reset”, “revert” and “restore” mean in this context.
Here are some short descriptions of what they each do:
    git revert COMMIT: Create a new commit that’s the “opposite” of COMMIT on your current branch (if COMMIT added 3 lines, the new commit will delete those 3 lines)
    git reset --hard COMMIT: Force your current branch back to the state it was at COMMIT, erasing any new changes since COMMIT. Very dangerous operation.
    git restore --source=COMMIT PATH: Take all the files in PATH back to how they were at COMMIT, without changing any other files or commit history.
“untracked files”, “remote-tracking branch”, “track remote branch”
Git uses the word “track” in 3 different related ways:
    Untracked files: in the output of git status. This means those files aren’t managed by Git and won’t be included in commits.
    a “remote tracking branch” like origin/main. This is a local reference, and it’s the commit ID that main pointed to on the remote origin the last time you ran git pull or git fetch.
    “branch foo set up to track remote branch bar from origin”
The “untracked files” and “remote tracking branch” thing is not too bad – they both use “track”, but the context is very different. No big deal. But I think the other two uses of “track” are actually quite confusing:
    main is a branch that tracks a remote
    origin/main is a remote-tracking branch
But a “branch that tracks a remote” and a “remote-tracking branch” are different things in Git and the distinction is pretty important! Here’s a quick summary of the differences:
    main is a branch. You can make commits to it, merge into it, etc. It’s often configured to “track” the remote main in .git/config, which means that you can use git pull and git push to push/pull changes.
    origin/main is not a branch. It’s a “remote-tracking branch”, which is not a kind of branch (I’m sorry). You can’t make commits to it. The only way you can update it is by running git pull or git fetch to get the latest state of main from the remote.
I’d never really thought about this ambiguity before but I think it’s pretty easy to see why folks are confused by it.
checkout
Checkout does two totally unrelated things:
    git checkout BRANCH switches branches
    git checkout file.txt discards your unstaged changes to file.txt
This is well known to be confusing and git has actually split those two functions into git switch and git restore (though you can still use checkout if, like me, you have 15 years of muscle memory around git checkout that you don’t feel like unlearning)
Also personally after 15 years I still can’t remember the order of the arguments to git checkout main file.txt for restoring the version of file.txt from the main branch.
I think sometimes you need to pass -- to checkout as an argument somewhere to help it figure out which argument is a branch and which ones are paths but I never do that and I’m not sure when it’s needed.
reflog
Lots of people mentioning reading reflog as re-flog and not ref-log. I won’t get deep into the reflog here because this post is REALLY long but:
    “reference” is an umbrella term git uses for branches, tags, and HEAD
    the reference log (“reflog”) gives you the history of everything a reference has ever pointed to
    It can help get you out of some VERY bad git situations, like if you accidentally delete an important branch
    I find it one of the most confusing parts of git’s UI and I try to avoid needing to use it.
merge vs rebase vs cherry-pick
A bunch of people mentioned being confused about the difference between merge and rebase and not understanding what the “base” in rebase was supposed to be.
I’ll try to summarize them very briefly here, but I don’t think these 1-line explanations are that useful because people structure their workflows around merge / rebase in pretty different ways and to really understand merge/rebase you need to understand the workflows. Also pictures really help. That could really be its whole own blog post though so I’m not going to get into it.
    merge creates a single new commit that merges the 2 branches
    rebase copies commits on the current branch to the target branch, one at a time.
    cherry-pick is similar to rebase, but with a totally different syntax (one big difference is that rebase copies commits FROM the current branch, cherry-pick copies commits TO the current branch)
rebase --onto
git rebase has an flag called onto. This has always seemed confusing to me because the whole point of git rebase main is to rebase the current branch onto main. So what’s the extra onto argument about?
I looked it up, and --onto definitely solves a problem that I’ve rarely/never actually had, but I guess I’ll write down my understanding of it anyway.
A - B - C (main)
     \
      D - E - F - G (mybranch)
          | 
          otherbranch
Imagine that for some reason I just want to move commits F and G to be rebased on top of main. I think there’s probably some git workflow where this comes up a lot.
Apparently you can run git rebase --onto main otherbranch mybranch to do that. It seems impossible to me to remember the syntax for this (there are 3 different branch names involved, which for me is too many), but I heard about it from a bunch of people so I guess it must be useful.
commit
Someone mentioned that they found it confusing that commit is used both as a verb and a noun in git.
for example:
    verb: “Remember to commit often”
    noun: “the most recent commit on main“
My guess is that most folks get used to this relatively quickly, but this use of “commit” is different from how it’s used in SQL databases, where I think “commit” is just a verb (you “COMMIT” to end a transaction) and not a noun.
Also in git you can think of a Git commit in 3 different ways:
    a snapshot of the current state of every file
    a diff from the parent commit
    a history of every previous commit
None of those are wrong: different commands use commits in all of these ways. For example git show treats a commit as a diff, git log treats it as a history, and git restore treats it as a snapshot.
But git’s terminology doesn’t do much to help you understand in which sense a commit is being used by a given command.
more confusing terms
Here are a bunch more confusing terms. I don’t know what a lot of these mean.
things I don’t really understand myself:
    “the git pickaxe” (maybe this is git log -S and git log -G, for searching the diffs of previous commits?)
    submodules (all I know is that they don’t work the way I want them to work)
    “cone mode” in git sparse checkout (no idea what this is but someone mentioned it)
things that people mentioned finding confusing but that I left out of this post because it was already 3000 words:
    blob, tree
    the direction of “merge”
    “origin”, “upstream”, “downstream”
    that push and pull aren’t opposites
    the relationship between fetch and pull (pull = fetch + merge)
    git porcelain
    subtrees
    worktrees
    the stash
    “master” or “main” (it sounds like it has a special meaning inside git but it doesn’t)
    when you need to use origin main (like git push origin main) vs origin/main
github terms people mentioned being confused by:
    “pull request” (vs “merge request” in gitlab which folks seemed to think was clearer)
    what “squash and merge” and “rebase and merge” do (I’d never actually heard of git merge --squash until yesterday, I thought “squash and merge” was a special github feature)
it’s genuinely “every git term”
I was surprised that basically every other core feature of git was mentioned by at least one person as being confusing in some way. I’d be interested in hearing more examples of confusing git terms that I missed too.
There’s another great post about this from 2012 called the most confusing git terminology. It talks more about how git’s terminology relates to CVS and Subversion’s terminology.
If I had to pick the 3 most confusing git terms, I think right now I’d pick:
    a head is a branch, HEAD is the current branch
    “remote tracking branch” and “branch that tracks a remote” being different things
    how “index”, “staged”, “cached” all refer to the same thing
that’s all!
I learned a lot from writing this – I learned a few new facts about git, but more importantly I feel like I have a slightly better sense now for what someone might mean when they say that everything in git is confusing.
I really hadn’t thought about a lot of these issues before – like I’d never realized how “tracking” is used in such a weird way when discussing branches.
Also as usual I might have made some mistakes, especially since I ended up in a bunch of corners of git that I hadn’t visited before.
Also a very quick plug: I’m working on writing a zine about git, if you’re interested in getting an email when it comes out you can sign up to my very infrequent announcements mailing list.

# Document Title
Unified Versus Split Diff
Oct 23, 2023
Which is better for code reviews, a unified diff or a split diff?
A split diff looks like this for me:
And this is a unified one:
If the changes are simple and small, both views are good. But for larger, more complex changes neither works for me.
For a large change, I don’t want to do a “diff review”, I want to do a proper code review of a codebase at a particular instant in time, paying specific attention to the recently changed areas, but mostly just doing general review, as if I am writing the code. I need to run tests, use goto definition and other editor navigation features, apply local changes to check if some things could have been written differently, look at the wider context to notice things that should have been changed, and in general notice anything that might be not quite right with the codebase, irrespective of the historical path to the current state of the code.
So, for me, the ideal diff view would look rather like this:
On the left, the current state of the code (which is also the on-disk state), with changes subtly highlighted in the margins. On the right, the unified diff for the portion of the codebase currently visible on the left.
Sadly, this format of review isn’t well supported by the tools — everyone seems to be happy reviewing diffs, rather than the actual code?
I have a low-tech and pretty inefficient workflow for this style of review. A gpr script for checking out a pull request locally:
$ gpr 1234 --review
Internally, it does roughly
$ git fetch upstream refs/pull/1234/head
$ git switch --detach FETCH_HEAD
$ git reset $(git merge-base HEAD main)
The last line is the key — it erases all the commits from the pull request, but keeps all of the changes. This lets me abuse my workflow for staging&committing to do a code review — edamagit shows the list of changed files, I get “go to next/previous change” shortcuts in the editor, I can even use the staging area to mark hunks I have reviewed.
The only thing I don’t get is automatic synchronization between magit status buffer, and the file that’s currently open in the editor. That is, to view the current file and the diff on the side, I have to manually open the diff and scroll it to the point I am currently looking at.
I wish it was easier to get this close to the code without building custom ad-hoc tools!
P.S. This post talks about how to review code, but reviewing the code is not necessary the primary goal of code review. See this related post: Two Kinds of Code Review.