jj/docs/sapling-comparison.md

Comparison with Sapling

Introduction

This document attempts to describe how jj is different from Sapling. Sapling is a VCS developed by Meta. It is a heavily modified fork of Mercurial. Because jj has copied many ideas from Mercurial, there are many similarities between the two tools, such as:

• A user-friendly CLI
• A "revset" language for selecting revisions
• Good support for working with stacked commits, including tracking "anonymous heads" (no "detached HEAD" state like in Git) and split commands, and automatically rebasing descendant commits when you amend a commit.
• Flexible customization of output using templates

Differences

Here is a list of some differences between jj and Sapling.

• Working copy: When using Sapling (like most VCSs), the user explicitly tells the tool when to create a commit and which files to include. When using jj, the working copy is automatically snapshotted by every command. New files are automatically tracked and deleted files are automatically untracked. This has several advantages:
  • The working copy is effectively backed up every time you run a command.
  • No commands fail because you have changes in the working copy ("abort: 1 conflicting file changes: ..."). No need for sl shelve.
  • Simpler and more consistent CLI because the working copy is treated like any other commit.
• Conflicts: Like most VCSs, Sapling requires the user to resolve conflicts before committing. jj lets you commit conflicts. Note that it's a representation of the conflict that's committed, not conflict markers (<<<<<<< etc.). This also has several advantages:
  • Merge conflicts won't prevent you from checking out another commit.
  • You can resolve the conflicts when you feel like it.
  • Rebasing descendants always succeeds. Like jj, Sapling automatically rebases, but it will fail if there are conflicts.
  • Merge commits can be rebased correctly (Sapling sometimes fails).
  • You can rebase conflicts and conflict resolutions.
• Undo: jj's undo is powered by the operation log, which records how the repo has changed over time. Sapling has a similar feature with its MetaLog. They seem to provide similar functionality, but jj also exposes the log to the user via jj op log, so you can tell how far back you want to go back. Sapling has sl debugmetalog, but that seems to show the history of a single commit, not the whole repo's history. Thanks to jj snapshotting the working copy, it's possible to undo changes to the working copy. For example, if you jj undo a jj commit, jj diff will show the same changes as before jj commit, but if you sl undo a sl commit, the working copy will be clean.
• Git interop: Sapling supports cloning, pushing, and pulling from a remote Git repo. jj also does, and it also supports sharing a working copy with a Git repo, so you can use jj and git interchangeably in the same repo.
• Polish: Sapling is much more polished and feature-complete. For example, jj has no blame/annotate or bisect commands, and also no copy/rename support. Sapling also has very nice web UI called Interactive Smartlog, which lets you drag and drop commits to rebase them, among other things.
• Forge workflow: Sapling has sl pr submit --stack, which lets you push a stack of commits as separate GitHub PRs, including setting the base branch. It only supports GitHub. jj doesn't have any direct integration with GitHub or any other forge. However, it has jj git push --change for automatically creating branches for specified commits. You have to specify each commit you want to create a branch for by using jj git push --change X --change Y ..., and you have to manually set up any base branches in GitHub's UI (or GitLab's or ...). On subsequent pushes, you can update all at once by specifying something like jj git push -r main..@ (to push all branches on the current stack of commits from where it forked from main).