Steve's Jujutsu Tutorial

Original Article ↗ Hacker News Discussion ↗

A new tutorial for the Jujutsu (jj) version-control system is drawing interest from developers who are frustrated with Git’s UX but still need Git compatibility and GitHub workflows. Commenters highlight jj’s always-committed working model, powerful support for stacked changes, and first-class conflict handling as major advantages, while noting gaps in editor integrations and review tooling compared with mature Git ecosystems. The thread also touches on alternatives like Sapling, Pijul, and Fossil, as well as broader questions about naming, workflow design, and why Git prevailed largely through GitHub’s dominance rather than technical merit.

Reception of the Tutorial and of jj

  • Many readers found the tutorial unusually clear and approachable, helping them finally “get” what jj is about.
  • Several people reported being excited to try jj, especially because it can work on top of existing git repos.
  • Some note the tutorial is slightly out of date (e.g., “branches” now called “bookmarks”), with a revised version in progress.

Core jj Concepts: Changes, Commits, Auto-Snapshots

  • A key mental model:
    • A change is a stable identifier for one conceptual modification.
    • Multiple underlying commits (snapshots) can represent successive iterations of that change.
  • The working copy is always committed: every jj command implicitly snapshots the state; optional integration with a file-watcher can make this fully automatic.
  • Older snapshots remain accessible via logs, including an operation log for the whole repo.

Workflow vs Git: Index, Branches, Stacks

  • Some dislike jj for lacking git’s index, using the index to stage “done but not ready to push” work.
  • Others argue jj offers a more powerful analog: treat the current change as an evolving “index,” and work on parent/child changes instead of staging.
  • Concern about accidentally pushing “garbage” from the working-copy commit is countered: jj’s push only sends explicitly named branches/bookmarks, not arbitrary commits like @.
  • Branch names/bookmarks do not auto-follow new commits; you’re “on” a change, and branches are pointers to changes. This simplifies stacked work that must merge in discrete pieces.

Conflict Handling and History Editing

  • jj stores conflicts as first-class objects in commits.
  • Benefits mentioned:
    • No “interrupted rebase” or orphan/obsolete states.
    • Descendants can always be rebased, even through conflicts.
    • Conflicts can be resolved later, possibly collaboratively.
  • Users report that complex reorderings or mistakes during rebases are easier to undo and fix than in git.

Git Interop, Tooling, and Alternatives

  • Git interoperability is highlighted as a “killer feature”: contributors can keep using git and GitHub while an individual uses jj locally.
  • Some stay on git solely for ecosystem reasons (GitHub, existing tooling, contributors’ expectations).
  • Lack of a rich jj plugin for Neovim and other editors is a blocker for some, especially compared to tools like Fugitive, Neogit, or magit.
  • Comparisons arise with Sapling (good but less general, weaker conflict model), Mercurial, Fossil, Pijul, Perforce, and monorepo setups; opinions are mixed, but several see jj and Sapling as “leagues ahead” of git’s UX.

Naming and Miscellaneous Concerns

  • Multiple comments criticize “Jujutsu/jj” as an opaque, hard-to-search name; others note even older tools (git, CVS, Subversion) aren’t exactly descriptive either.
  • Some mention friction with Nix flakes and jj, but details remain unclear.