jj/docs/git-comparison.md

Comparison with Git

Introduction

This document attempts to describe how Jujutsu is different from Git. See the Git-compatibility doc for information about how the jj command interoperates with Git repos.

Overview

Here is a list of conceptual differences between Jujutsu and Git, along with links to more details where applicable and available. There's a table further down explaining how to achieve various use cases.

• The working copy is automatically committed. That results in a simpler and more consistent CLI because the working copy is now treated like any other commit. Details.
• There's no index (staging area). Because the working copy is automatically committed, an index-like concept doesn't make sense. The index is very similar to an intermediate commit between HEAD and the working copy, so workflows that depend on it can be modeled using proper commits instead. Jujutsu has excellent support for moving changes between commits. Details.
• No need for bookmark names (but they are supported). Git lets you check out a commit without attaching a bookmark. It calls this state "detached HEAD". This is the normal state in Jujutsu (there's actually no way -- yet, at least -- to have an active bookmark). However, Jujutsu keeps track of all visible heads (leaves) of the commit graph, so the commits won't get lost or garbage-collected.
• No current bookmark. Git lets you check out a bookmark, making it the 'current bookmark', and new commits will automatically update the bookmark. This is necessary in Git because Git might otherwise lose track of the new commits. Jujutsu does not have a 'current bookmark'; instead, you update bookmarks manually. For example, if you start work on top of a commit with a bookmark, new commits are created on top of the bookmark, then you issue a later command to update the bookmark.
• Conflicts can be committed. No commands fail because of merge conflicts. The conflicts are instead recorded in commits and you can resolve them later. Details.
• Descendant commits are automatically rebased. Whenever you rewrite a commit (e.g. by running jj rebase), all its descendants commits will automatically be rebased on top. Branches pointing to it will also get updated, and so will the working copy if it points to any of the rebased commits.
• Branches are identified by their names (across remotes). For example, if you pull from a remote that has a main bookmark, you'll get a bookmark by that name in your local repo as well. If you then move it and push back to the remote, the main bookmark on the remote will be updated. Details.
• The operation log replaces reflogs. The operation log is similar to reflogs, but is much more powerful. It keeps track of atomic updates to all refs at once (Jujutsu thus improves on Git's per-ref history much in the same way that Subversion improved on RCS's per-file history). The operation log powers e.g. the undo functionality. Details
• There's a single, virtual root commit. Like Mercurial, Jujutsu has a virtual commit (with a hash consisting of only zeros) called the "root commit" (called the "null revision" in Mercurial). This commit is a common ancestor of all commits. That removes the awkward state Git calls the "unborn bookmark" state (which is the state a newly initialized Git repo is in), and related command-line flags (e.g. git rebase --root, git checkout --orphan).

The index

Git's "index" has multiple roles. One role is as a cache of file system information. Jujutsu has something similar. Unfortunately, Git exposes the index to the user, which makes the CLI unnecessarily complicated (learning what the different flavors of git reset do, especially when combined with commits and/or paths, usually takes a while). Jujutsu, like Mercurial, doesn't make that mistake.

As a Git power-user, you may think that you need the power of the index to commit only part of the working copy. However, Jujutsu provides commands for more directly achieving most use cases you're used to using Git's index for. For example, to create a commit from part of the changes in the working copy, you might be used to using git add -p; git commit. With Jujutsu, you'd instead use jj split to split the working-copy commit into two commits. To add more changes into the parent commit, which you might normally use git add -p; git commit --amend for, you can instead use jj squash -i to choose which changes to move into the parent commit, or jj squash <file> to move a specific file.

Command equivalence table

Note that all jj commands can be run on any commit (not just the working-copy commit), but that's left out of the table to keep it simple. For example, jj squash/amend -r <revision> will move the diff from that revision into its parent.

Use case	Jujutsu command	Git command
Create a new repo	jj git init [--colocate]	git init
Clone an existing repo	jj git clone <source> <destination> [--remote <remote name>] (there is no support for cloning non-Git repos yet)	git clone <source> <destination> [--origin <remote name>]
Update the local repo with all bookmarks from a remote	jj git fetch [--remote <remote>] (there is no support for fetching into non-Git repos yet)	git fetch [<remote>]
Update a remote repo with all bookmarks from the local repo	jj git push --all [--remote <remote>] (there is no support for pushing from non-Git repos yet)	git push --all [<remote>]
Update a remote repo with a single bookmark from the local repo	jj git push --bookmark <bookmark name> [--remote <remote>] (there is no support for pushing from non-Git repos yet)	git push <remote> <bookmark name>
Show summary of current work and repo status	jj st	git status
Show diff of the current change	jj diff	git diff HEAD
Show diff of another change	jj diff -r <revision>	git diff <revision>^ <revision>
Show diff from another change to the current change	jj diff --from <revision>	git diff <revision>
Show diff from change A to change B	jj diff --from A --to B	git diff A B
Show description and diff of a change	jj show <revision>	git show <revision>
Add a file to the current change	touch filename	touch filename; git add filename
Remove a file from the current change	rm filename	git rm filename
Modify a file in the current change	echo stuff >> filename	echo stuff >> filename
Finish work on the current change and start a new change	jj commit	git commit -a
See log of ancestors of the current commit	jj log -r ::@	git log --oneline --graph --decorate
See log of all reachable commits	jj log -r 'all()' or jj log -r ::	git log --oneline --graph --decorate --bookmarks
Show log of commits not on the main bookmark	jj log	(TODO)
List versioned files in the working copy	jj file list	git ls-files --cached
Search among files versioned in the repository	grep foo $(jj file list), or rg --no-require-git foo	git grep foo
Abandon the current change and start a new change	jj abandon	git reset --hard (cannot be undone)
Make the current change empty	jj restore	git reset --hard (same as abandoning a change since Git has no concept of a "change")
Abandon the parent of the working copy, but keep its diff in the working copy	jj squash --from @-	git reset --soft HEAD~
Discard working copy changes in some files	jj restore <paths>...	git restore <paths>... or git checkout HEAD -- <paths>...
Edit description (commit message) of the current change	jj describe	Not supported
Edit description (commit message) of the previous change	jj describe @-	git commit --amend (first make sure that nothing is staged)
Temporarily put away the current change	jj new @- (the old working-copy commit remains as a sibling commit) (the old working-copy commit X can be restored with jj edit X)	git stash
Start working on a new change based on the <main> bookmark	jj new main	git switch -c topic main or git checkout -b topic main (may need to stash or commit first)
Move bookmark A onto bookmark B	jj rebase -b A -d B	git rebase B A (may need to rebase other descendant bookmarks separately)
Move change A and its descendants onto change B	jj rebase -s A -d B	git rebase --onto B A^ <some descendant bookmark> (may need to rebase other descendant bookmarks separately)
Reorder changes from A-B-C-D to A-C-B-D	jj rebase -r C --before B	git rebase -i A
Move the diff in the current change into the parent change	jj squash/amend	git commit --amend -a
Interactively move part of the diff in the current change into the parent change	jj squash/amend -i	git add -p; git commit --amend
Move the diff in the working copy into an ancestor	jj squash --into X	git commit --fixup=X; git rebase -i --autosquash X^
Interactively move part of the diff in an arbitrary change to another arbitrary change	jj squash -i --from X --into Y	Not supported
Interactively split the changes in the working copy in two	jj split	git commit -p
Interactively split an arbitrary change in two	jj split -r <revision>	Not supported (can be emulated with the "edit" action in git rebase -i)
Interactively edit the diff in a given change	jj diffedit -r <revision>	Not supported (can be emulated with the "edit" action in git rebase -i)
Resolve conflicts and continue interrupted operation	echo resolved > filename; jj squash/amend (operations don't get interrupted, so no need to continue)	echo resolved > filename; git add filename; git rebase/merge/cherry-pick --continue
Create a copy of a commit on top of another commit	jj duplicate <source>; jj rebase -r <duplicate commit> -d <destination> (there's no single command for it yet)	git co <destination>; git cherry-pick <source>
Find the root of the working copy (or check if in a repo)	jj workspace root	git rev-parse --show-toplevel
List bookmarks	jj bookmark list	git bookmark
Create a bookmark	jj bookmark create <name> -r <revision>	git bookmark <name> <revision>
Move a bookmark forward	jj bookmark set <name> -r <revision>	git bookmark -f <name> <revision>
Move a bookmark backward or sideways	jj bookmark set <name> -r <revision> --allow-backwards	git bookmark -f <name> <revision>
Delete a bookmark	jj bookmark delete <name>	git bookmark --delete <name>
See log of operations performed on the repo	jj op log	Not supported
Undo an earlier operation	jj [op] undo <operation ID> (jj undo is an alias for jj op undo)	Not supported
Create a commit that cancels out a previous commit	jj backout -r <revision>	git revert <revision>