jj – the CLI for Jujutsu

i apologize if my comment came across as accusing you of claiming superiority and failing your intention. it was not meant to do that. if there is any accusation then it is the general assumption that jj is better that can be felt in the overall tone of this discussion thread.

your examples show a particular aspect of jj, and to me they demonstrate that jj isn't better across the board for a certain group of users at least.

i'd be interested to know if i got the impression right that jj provides more commands for specific actions that don't require you to understand how the system works underneath. that is significant because i like to understand how things work underneath. more commands then means that i have to learn more to understand each one of them.

in a sense it is like high level languages vs low level languages. don't get me wrong, i like high level languages. i prefer them actually, but i also like minimalistic syntax, so i prefer smalltalk and lisp over, say scala which has a reputation for being complex. but scala is starting to make more sense once i learn what lower level primitives the syntax translates to.

same goes for jj. i want to understand the primitives that the commands translate to. git puts me closer to those primitives, which makes it harder to learn but possibly easier to use or understand once you get it. since jj is built on top of the same primitives it should be possible to reach the same understanding. jj uses those primitives differently, and that's the part that i find interesting. the more i understand how jj works with git primitives the more i like it. but it also shows that git primitives are not bad if they enable such different approaches. (i wonder how different git primitives are from other approaches such as pijul which is based on a theory of patches).

i guess what would help me would be a guide to jj for those who are familiar with how git works underneath.

the examples in your second to last paragraph sound very interesting. please show. of link to references if you know any.

Did you mean inherent complexity instead of incidental complexity?

I think the inherently complex things in git are (1) the content-accessible object store, snapshots, plus the merkel tree approach to keeping track of commits and parenthood, (2) merges, rebases, and resolving conflicts between two different changes with a common ancestor, (3) possibly syncing commits between different remotes, although I think Git's approach adds accidental complexity to the problem as well.

Everything else is a question of the user interface: how you choose to show a commit, how you choose to update the project files, how you choose to let people create new commits, etc. And I think the Git CLI is a poor user interface in a lot of places. There are a lot of features which are really powerful but difficult to use, whereas actually they could be just as powerful but far more intuitive to use.

In fairness, this is no slight to the Git developers - they are improving a lot of that interface all of the time. And finding a simpler interface is often a lot more hard work than finding the complicated interface, and I don't think I would have figured out how to create something like jj until I'd seen it before.

Heh, sorry, I guess you triggered my defensive "book-length response" reaction. Here's the next book:

As you say, jj uses git primives so the core data model is the same. I say "core" because jj subtracts out the staging area and stash and adds in "changes" and the operations log. But otherwise, your understanding of the git data model translates seamlessly, with one exception: git-style branches aren't really a thing, they can only be emulated. What I mean is that in git, the topological head that is associated with a branch ref (apologies if I'm getting terminology wrong), when accessed through a branch name, is taken to represent not just that commit but all ancestors of it as well. So "merging a branch" or "checking out a branch" are natural things to do.

jj prefers to be grounded in the commit DAG. Since you're always "updating" a commit (really replacing it with new ones), the only other state is the location of that commit in the DAG. You specify that before that change exists, with the default being the same as in git: the single descendant of the last thing you were working on (the branch tip in git, the @ change in jj). `jj new` (or `jj commit`) creates a single child change of your current change, unless you pass flags putting it elsewhere in the graph -- and it is very common to put it elsewhere if that's the thing you want to do.

An example: say you have a sequence of changes (and thus commits) where you're working on a feature: A->B->C, with C being what you're editing now (the @ change). You realize that your latest change, C, might not be the best approach and decide to try another. You do `jj new B` to create an alternate descendant and implement a C2 approach. Now you have A->B->{C,C2}. Which of C or C2 is the tip of your "feature branch"? Answer: who cares? At least until you want to push it somewhere. My default log command will show the whole DAG rooted at A, the first change off of "trunk" commits. I might do further work by creating descendants of C2 and thus have A->B->C and B->C2->D->E, and I might rebase or duplicate ->D->E on top of C if I want to try it out with that approach. Or I might inject or modify things earlier in the graph like A->X->B'->Y->{C,C2} (where B' is an updated B). If I push part of that DAG up to a server that I have declared to be shared with other people, then jj will know what parts of the graph should no longer be mutated and prevent me from doing that (by default).

All of this follows the core git model, it's just that mutating the graph structure is expected and common with jj and only restricted modifications seem to be common with git. You can do any and all of it with git, but rebase, undo, and conflicts are better-supported and feel less exceptional with jj. And you can jump to anywhere in the graph, or move around pieces of the graph, anytime and without necessarily changing the @ (working change) you're looking at.

This also means that jj doesn't need a `git switch` or `git checkout` command. That notion is replaced by making your current change (there's always a current change, it's the one that will be associated with any edits you make) be the child of wherever in the DAG you want, probably with `jj new `. As with git, there's a snapshot associated with it, so the other purpose of `git checkout` (to make your on-disk copy of a file match the contents of a given commit) is `jj restore filename`. In `git help checkout`, it says "Switch branches or restore working tree files". The "switch branches" part is `jj new`, the "restore working tree files" part is `jj restore`. `jj new` is equivalent to `git checkout --detach` or `git checkout ` (or plain `git checkout `). If you only consider the "make (part or all of) the working tree match that of this commit", then all of the different variants `git checkout` being in one command makes sense. But jj distinguishes things that operate on the DAG vs trees (file contents). And it doesn't need different flags or modes for the index/stage vs a commit; everything is a commit. `git stash` is unnecessary, the equivalent is `jj new ` (you're just moving your working directory to be based on a different commit; the previous patches aren't lost or anything, they stay where they were in the DAG. Grab them from there if you want them and put them anywhere else in the graph, with or without changing your working directory as you wish.) `git reset` is redundant with `jj restore` -- well, mostly; the other part of what it does is handled by `jj abandon`. (Again, `restore` for tree contents, `abandon` for the graph node.) `git merge` is `jj new` with multiple parents instead of one so a command isn't needed.

One way to say it: with jj, `new` + `describe` + `rebase` + `abandon`, you can do all the graph manipulation. Add in `squash` + `restore` and you can do all content manipulation too. That's it for local operation. Well, maybe `jj file track/untrack`. The flags are pretty consistent across commands and don't fundamentally change what they do. Everything else is either for working with servers and other repositories, convenience utilities for specific situations, details like configuration, or jj-specific functionality like the operation log.

The other major difference is that jj adds in the notion of persistent "changes" (I wish we'd come up with a better name) that in normal operation correspond to a single "visible" commit, but which commit that is changes over time. A change has a single semantic purpose and doesn't lose its identity when rebased or merged or the contents of its files are changed. This difference is actually starting to diminish, because git (or rather, the git forges and tooling) has started preserving the footers that identify these change IDs over various operations. So if you're using git in connection with gitbutler or gerrit or whatever, you'll be getting the benefit of these persistent identifiers even if you continue using the git cli.

Sorry, that's a lot, but it'd be my attempt at "jj fundamentals for someone who understands git primitives well".

> https://github.com/jj-vcs/jj/issues/5596 doesn't seem to be the oldest instance of this problem, but does seem to be the current discussion, and there seems to be no consensus on how to fix.

Ahh, sorry - I didn't understand the issue. Yes, that is going to catch you unawares.

I can't see a better solution than a warning. It looks to be an unavoidable negative side effect of jj's auto-commit behaviour, but auto-commits bring so many positives I'll wear the occasional stray add. Usually they are harmless and trivial to reverse - but I've made a mental note to revise my jj workflow. When I change .gitignore, do it in the oldest mutable commit.

> Oh, and ISTR submodules were a pain to work with.

Yes, they are, although that's no different to git. JJ's tracking of submodule hashes in the parent repository behaves exactly as you would expect. What jj doesn't have is a command to bring the submodule into sync with the parent repository, like git's submodule command.

However, I find git's submodule command behaviour borders on inexplicable at times. I wrote my own `jj submodule` alias that does one simple job - it checks out every submodule the parent repository owns, at the hash recorded by the parent. I find that far better than the git command, which follows the usual git pattern of being a complex mess of sub-sub-commands with a plethora of options.

If jj automatically recursively updated submodules when you moved to a different change-id, it would be most of the way there. If it added commands to add and remove submodule directories, it would be there, and the reasons people dislike git's submodules would be gone.

I'm the moderator who changed the title, which is a routine action. That doesn't mean the post itself is inappropriate for HN.

> allowing this kind of posting only works against the HN

HN is for curious conversation between good hackers. We can't and won't ever disallow a post about a software project that someone has built and that others find interesting. That would be way too interventionist and completely against the ethos of HN.

If you have a substantive critique of the project, you're most welcome to share it in the spirit of curious conversation that this site strives to cultivate. Your original comment and your reply to me reek of just the kind of curmudgeonliness and snarkiness we're trying avoid here.