Sapling SCM and git-branchless

[arxanas]

Announced today, Sapling (formerly Eden) is Meta's open-source Mercurial-descended version control system. I recommend trying it out — it's pretty good!

Adopting Sapling in your workflows

Sapling seems ready to use today on Git repositories. Some notes from trying it out:

• Sapling does not co-locate with your Git repository!
  • You have to create a separate Sapling repository. If you want to share changes between a Git repository and a Sapling repository, you'll have to push/pull them.
  • That being said, Sapling is a battle-tested solution for patch stack workflows, so I wouldn't anticipate you having to fall back to Git for purely local development.
• I struggled to work with remotes and open a pull request in Sapling, so try that out early if you plan to use PRs as part of your workflow.
  • The sl paths remote-management command doesn't seem to be publicly documented? Furthermore, some of the --help text refers to Mercurial commands which don't seem to exist in Sapling.
  • See Adjust git reset --hard in Git cheat sheet facebook/sapling#152 (comment) for my PR trouble.
• I recommend you check out the sl split and sl absorb commands in particular. I used them a lot at Facebook, and git-branchless doesn't have equivalents.
• Separately, I recommend that you try sl web or the VS Code interactive smartlog extension. In my opinion, this is paradigm-shifting for patch-stack users: it's one of very few Git UI clients which focuses on the commit graph rather than linear branches.
  • Unfortunately, it's a clean-room implementation of their internal interactive smartlog, so it doesn't have all the features yet, such as the commit split GUI (which was perhaps my favorite feature).
  • cc @pokey, since you mentioned working on a GUI tool like this.

The future of git-branchless

git-branchless was created after I left Facebook to recreate a lot of those workflows. So now that Sapling has been open-sourced, what does this mean for git-branchless?

Quite a lot of the work in git-branchless was just to get to parity with Mercurial/Sapling, such as anonymous branching, commit evolution, and in-memory rebases. These weren't quite the main goal of git-branchless except insofar as they supported adopting Mercurial patch-stack workflows.

Once that foundation was usable, we could start on the real work, to experiment with and improve VCS workflows. For example, here's some workflows that git-branchless supports, but not Sapling:

• Speculative merging: operations never start merge conflict resolution unless explicitly requested.
• Working copy snapshotting: you can undo even uncommitted operations to the working copy. This also helps in implementing other commands.
• Surgical rebasing: git move can move exact ranges, reorder commits, and insert between other commits.
• Syncing remote work: git sync is a fast way to update local draft work but skip over any conflicting stacks.
  • This is different from sl rebase -s 'draft()' -d 'main()' in that each stack is synced separately, so that stacks which don't merge cleanly are deferred while still updating the rest.
• Alternative smartlog rendering: we render omitted commits, and choose to render merge conflicts differently to reduce the number of crossing branches in the output.
  • Also, the smartlog is rendered upside down, which is a killer feature for me, but maybe not others 🙃.

And here's some random ideas off of the top of my head that could be implemented in the future, which would advance the state of the art in version control systems:

• Revsets:
  • Piping or variable binding.
  • Imperative commands.
• git test
  • Binary search, including in parallel.
  • Change minimization.
  • Applying formatting/linting changes.
• git record:
  • A commit split TUI which can split into multiple commits directly.
  • An --insert flag to move sibling commits.
• git submit:
  • Better GitHub, etc. integration using the fact that we can create synthetic commits in-memory.
  • Automatic commit sync to share commit history across devices, without having to manually push.
• git sync:
  • Better detection of squashed commits during rebases.

We should consider git-branchless to be an experimental playground moving forward, which is to say that it won't reach 1.0. Instead, we can try out lots of cool features and see 1) whether they're good ideas, and 2) what the best UI is, without committing to supporting them indefinitely.

But this also means that I'll deprioritize reimplementing more of the Sapling/Mercurial workflows directly in git-branchless, such as sl absorb, if there's nothing in particular to improve on. And, frankly, some of the git-branchless foundation is shaky, such as the implementation of the event log (doesn't form a CRDT and can't be easily propagated across machines; events don't have natural inverses; reference updates should have been tracked via snapshots, not diffs; etc.), and it would be easier to throw it away and use someone else's implementation.

Where will the new features go?

I don't personally anticipate contributing to Sapling directly:

• Being a newly open-sourced project, it's unclear how much outside contribution they'll accept, or how much outsiders can influence the design of the project.
• It's possible that they won't be interested in maintaining features that are only useful for small repositories or which don't scale to large repositories. For example, git test today can spawn lots of Git worktrees to run commands out-of-tree, but Meta might not be interested in maintaining that, since their repository might be too big to afford extra worktrees.
• Sapling at present doesn't add client-side functionality which advances the current version control state of the art (although a lot of the alternatives may be scattered around different version control systems, programs, or libraries). To considerably improve client-side workflows, we might have to take more dramatic changes to the version control model.

Ideally, we'll be able to build new features and workflows by publishing libraries and standalone programs. For example, a superior git record command could be used standalone as a merge-tool, or as a library in many different version control projects (Sapling, Jujutsu, Stacked Git, Pijul, Game of Trees, gitoxide, gitui, etc.). In the same way, Sapling itself provides its version control libraries for others to use, such as the segmented changelog, which git-branchless uses today.

For features which are tied more closely to the version control system, I expect to contribute to Jujutsu. They've tried to make significant conceptual changes to advance the state of version control, such as working copy commits and first-class conflicts, which I think git-branchless is more philosophically aligned with. Their implementations of the operation log and working copy snapshots are already more robust than those of git-branchless.

They've also shown themselves to be open to outside influence and direction. We already expect some of the ideas from git-branchless to be implemented in Jujutsu, such as git move --exact. On a pragmatic note, they also attempt to be backend-agnostic, and can co-locate with Git, which are both serious concerns in terms of widespread adoption.

Either way, it's settled that, in the long term, we won't have to use a confusing name like "git-branchless"!

[quark-zju]

Thanks for this discussion! It is very well written.

Sorry for your bad experience on remote paths/names. We are making changes to address related issues (non-main branches should be draft and visible) soon.

I think it's fortunate that git-branchless, jj and sl are in the Rust eco-system. This makes library sharing easy. I'd like to mention a few less known libraries in Sapling that might be interesting:

• MetaLog is Sapling's solution to "operation log".
• DrawDag might be interesting to create test cases.
• ZstDelta might be interesting if you are exploring low-level delta-chain and compression logic.
• IndexedLog is Sapling's database-like layer that provides data integrity and O(log N) lookups.
• Let me know if you want a Rust port of LineLog for absorb or related features.

I believe many in the Sapling team are interested in novel ideas. In fact, Sapling's server-side snapshot data model was already designed with check-in conflicts in mind. On the other hand, many people that Sapling serves do not have an expert level of knowledge on source control. If the novel ideas turn out to be useful and easy for average people, I believe Sapling would be interested in adopting too.

[gregwebs]

With git-branchless I can just do the git I know and learn to use the new features gradually.
Sapling requires learning new commands upfront. I think this is true of jujitsu as well although I haven't tried it yet. Sapling also places restrictions that aren't in git (not allowing a force push to a remote).

I think it is amazing that we have this situation with three great projects able to share code and git-compatible. It really seems like the best of all worlds

• git-branchless: gradual UX
• jujitsu: new UX, community driven
• sapling: new UX, corporate driven

[quark-zju]

Sapling also places restrictions that aren't in git (not allowing a force push to a remote)

This is not well documented right now, but push -f can be used for force push.

[martinvonz]

Sapling requires learning new commands upfront. I think this is true of jujitsu as well although I haven't tried it yet.

You can use jj in an existing git repo, switching between git and jj commands as you like. That should mostly work well, except for a bug that typically happens on undo. I know that bug is quite annoying for many users, so I'm trying to prioritize fixing that.

[Kimeiga]

wait any plans for a git split à la sl split

[arxanas]

I don't have my own plans to implement it, but now that we have git record -i, it should be doable if you want to try. Tracking issue is #180