JJ Cheat Sheet

Ah, I use `jj` on WSL every day, so I was confused at first, but that's because I don't share the drive there any more. That absolutely makes sense as a blocker. The autocrlf bit is a bit of a bummer on Windows, too.

> Another relatively minor inconvenience is its inability to use your SSH configs.

This should be much better as of last week's release, when you can say "please use git as a subprocess rather than libgit2/gix".

jj is truly its own VCS, so to deeply understand it, it's more than short. But it does map to git, and so you can sorta explain it in git terms. It's really kind of like "what if you tried to build hg on top of git?"

jj is kind of hard to really explain because a bunch of the design decisions have subtle but important impacts on other decisions, so your first impression of a feature may be slightly wrong because you don't get the implications yet.

jj is sort of the same as git: you have a DAG of snapshots of your project. The differences are in how you interact with those things. To try and put it in git terms:

1. Commits are mutable, not immutable (but we'll talk about is more later)

2. You're always working in the context of some commit

3. When you modify a file, it becomes part of that commit (we'll talk about the index in a minute)

4. You don't need to care about branches at all, the "detached head" state is the nrom.

5. commits are immutable in the "immutable data structures" sense, in that whenever you modify them, it's almost like you're adding a commit to them. this is why jj calls its "commits" "changes", change IDs stay stable as you edit them, and they produce new git commits for every edit.

6. Because of how this all fits together, you don't need an explicit index; if you want one, you can just `jj new` twice to get two changes on top of each other, and then edit your files. When you have what you want, `jj squash` will move the diff into the parent commit, and now it's "part of that feature" or whatever. If you want `git add -p`, that's `jj squash -i`.

That is kind of it on some level, but in reality, it's kind of hard to convey how a few, smaller, more orthogonal primitives let you do everything you can do in git, but easier. (I tried to actively think of cases last night and only came up with two or three that were easier in git than jj, and jj will have fixes for most of those soonish.)

stashing is another great example of a feature of git that's just a workflow pattern in jj.

There's just... it's a lot. It's hard to know what the best thing really is. Other than `jj undo` :)

(I've got this on the brain since I am literally working on my tutorial right now)

This might be what you're looking for: https://jj-vcs.github.io/jj/latest/git-comparison/

I’ve been using it for a bit. It is magical. I had some merge conflicts in a GitHub PR. I pulled everything down with jj, and the conflicts were gone. Pushed and presto.

I do end up with descriptionless bookmarks that won’t push without a flag. So, I’m still doing something wrong.

But it’s already saved me a few times this week during some gnarly refactoring and merges.

If you truly miss bookmarks moving like branches, you can give this configuration option a try: https://github.com/jj-vcs/jj/discussions/3549

You may be interested in the semi-standard `jj tug` alias [1], that moves "the most recent" bookmark up to `@-`

[1]: https://github.com/jj-vcs/jj/discussions/5568

Thanks for the kind word!

Unfortunately the arrows are kind of confusing regardless of which way they go. You're suggesting they point forward in time, from the old commit to the new commit. The way they're drawn is the direction of the reference: a commit points at its parent. The argument in favor of each way the arrows could go feel about equally strong to me, and my understanding is that the convention in repo diagrams is for arrows to go in the direction of the reference, so that's what I went with.

It's trying to point out the common argument that's passed to each command: `jj restore` with no arguments is virtually the same as `jj abandon`, but in practice that means that `jj restore` tends to be called with a file as an argument, and `jj abandon` gets called with a revision (which he's calling edit here). It is in fact a node. The arrows are still just relationships between nodes.

> if I'm understanding it right, turns r --[edit3]--> q --[edit2]--> p into r --[edit3]--> p.

You are right with the outcome but wrong about why. `jj abandon -r q` would turn `r --> q --> p` into `r --> p`, but you're passing the node as the argument (r is for revision) not the edge.

Hilariously, I am literally working on writing version 2 of my tutorial right now, and I'm literally talking about `jj abandon`. What do you think about this? It cuts off where I literally am right now: https://gist.github.com/steveklabnik/71165f9ff5e13b1e95902c4...

Yes, I think you understand perfectly. `abandon` was the diagram I struggled the most to draw.

I like the idea of putting the edits on the arrows, but there are a couple senses in which the edit is associated with the change itself rather than an edge between two changes:

1. A change with two parents starts out by merging them, and then it can make edits on top of that merge. If the edits go on an edge instead of on a node, which of the two edges do those changes belong on?

2. If you move a change (e.g. by rebasing it), its diff comes with it. I guess you could say that when you rebase, you're not moving just the node but also the edge from it to its parent?

Even so, diffs on edges feels very right. I may update that diagram.

EDIT: Updated!

Many jj commands share names with git commands, yes. That doesn't always mean they do the same exact thing. There's lots that are different too.