ok/jj
1
0
Fork 0
forked from mirrors/jj
Code Pull requests Activity

docs: add doc comparing jj to Sapling (#1708)

Browse source
This commit is contained in:
Martin von Zweigbergk 2023-06-19 12:29:06 -07:00 committed by Martin von Zweigbergk
parent 779b8ba318
commit e6d5df1010
2 changed files with 75 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/related-work.md
View file

@ -9,7 +9,8 @@ Similar tools:
* [Sapling](https://sapling-scm.com/): A heavily modified fork of
[Mercurial](https://www.mercurial-scm.org/) developed and used at Meta. It
is compatible with Git, has undo functionality, and
[a graphical interface](https://sapling-scm.com/docs/addons/isl).
[a graphical interface](https://sapling-scm.com/docs/addons/isl).
See [how it is different from Jujutsu](sapling-comparison.md).
* [GitUp](https://gitup.co/): A Mac-only GUI for Git. Like Jujutsu, supports
undo and restoring the repo to an earlier snapshot. Backed by its
[GitUpKit library](https://github.com/git-up/GitUp#gitupkit).

73
docs/sapling-comparison.md Normal file
View file

@ -0,0 +1,73 @@
# Comparison with Sapling
## Introduction
This document attempts to describe how jj is different
from [Sapling](sapling-scm.com). Sapling is a VCS developed by Meta. It is a
heavily modified fork of [Mercurial](https://www.mercurial-scm.org/). Because
jj has copied many ideas from Mercurial, there are many similarities between the
two tools, such as:
* A user-friendly CLI
* A "[revset](revsets.md)" 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](templates.md)
## 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](working-copy.md). 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](conflicts.md). 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](operation-log.md), which
records how the repo has changed over time. Sapling has a similar feature
with its [MetaLog](https://sapling-scm.com/docs/internals/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](https://sapling-scm.com/docs/addons/isl), 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`).