4 ms·

The JJ VCS workshop: A zero-to-hero speedrun

178 points by todsacerdoti 1y ago

notnmeyer 1y ago
this looks great. excited to give it a go!
vlovich123 1y ago
Shoutout to graphite.dev that gives you a stacked workflow on top of git/github - everything actually stays git, it just auto-updates the stack of branches and manages updating the PRs accordingly + will auto-merge PRs for you once they’re ready.
- mpalmer 1y ago
  The point of jj is to improve on the git interface. It's kind of weird to imply that jj's purpose is a drawback. I don't want git to stay git. Nor do I want SAAS solving stacked PRs for me, "free option" or not. jj is explicitly not for teams - there's no way to share jj-proprietary stuff between checkouts of a repo, because it's a frontend for interacting with a git repo.
  - nulld3v 1y ago
    Ehhh, when I explain jj to people I like to say that it is "a tool to edit git repos", and that "the repo is still a git repo" because people have so many misconceptions of how jj works. When they see how different jj's interface is from git, they think it's a whole new VCS and are worried that it will break compatibility with other git tools. That said, I only do this to avoid overwhelming beginners, when actually learning/using jj it is definitely more useful to think of it as a different VCS.
    - mpalmer 1y ago
      Telling people it's a tool to edit git repos makes it sound hackier than it is; not surprising they're nervous it'll break something. Just tell them git makes mistakes easy, and jj makes them difficult.
      - nulld3v 1y ago
        I've tried that but it isn't very effective because usually if they are not a git wizard, they are already using some sort of git interface or GUI that prevents them from making catastrophic mistakes. So they don't see the appeal in relearning all their git knowledge and terminology. Hence why I initially try to sell it as an addition to their toolbox, instead of as a replacement for their entire workflow.
        nchmy 1y ago
        I agree with you both. Jj makes mistakes hard, but also makes it easy to just focus on your code and easily sort out anything git-related later as an after-thought.
  - vlovich123 1y ago
    Graphite also improves on the interface if you want that. I personally have no issues with git anymore having spent nearly two decades working with it.
sastraxi 1y ago
Looks good! I might have missed it but it would be helpful to have a link to the jujutsu home page in your README.md.
- Darmani 1y ago
  Creator here. Done.
sn9 1y ago
My understanding of jj is that's it's meant to be compatible with git. Does that mean that working through this will also improve your git usage? Or could be used to teach someone git workflows?
- baq 1y ago
  Haven’t reviewed the material, but compatible is a weak word - jj is also compatible with a plain filesystem. The point is that it makes some workflows easy and accessible which are hard and cumbersome in git, so they become the new normal instead of things to avoid.
- nchmy 1y ago
  You'd only really learn anything if you know nothing. The underlying git is largely invisible, and the workflows are vastly different - for the better. It is constantly making new git commits any time you use a jj command. (I even have it set up to use watchman to create commits any time any file changes - this is unimportant for this discussion). But the commits are completely hidden - we instead interact with jj "changes", which are more like a constantly evolving, auto-adding, auto-committing, stash-free, movable git commit. Git branches are even a 2nd class citizen. We can create endless "branches" by adding new changes on top of any existing change, and then merge that with an arbitrary amount of other changes by specifying them when creating a new change. We can also rebase/move changes around all over the place, and the changes get automatically propagated through any descendents. We can also split and squash commits very easily, and even do so on a granular level - easily and interactively select lines or sections of changed code within one change to be split or squashed into a different change. This allows you to just work, and then tidy the history up later when you have a clue. Conflicts that arise from merge/rebase/split/squash/etc do not require immediate intervention - fix them when you want to, and the fix will also propagate through. You can use jj resolve to open the conflicts in your merge conflict editor of choice (I use vs code). We use git branches when we apply/update a jj bookmark to any change. This essentially creates/changes a git branch, which can then be pushed to Github. When bookmarks are pushed, the ancestor changes become "immutable" by default, which prevents things like editing, rebasing etc, so as to facilitate collaboration. But it can be override, and I presume it does things like a force push for you. One thing to note is that your jj "branches" etc are not shared as it just stays local. You could, in theory, sync your .jj folder remotely, but I don't see that being particularly feasible unless it's just to sync with another device for your own use (or back it up in case of data loss). It's really just a local interface for individual use, and collaboration still happens via git branches and pull requests. If you were to lose your jj folder, you could clone the git repo again and you'd just start with the existing git branches etc. I'll mention one particularly powerful/useful jj workflow - the megamerge. There's a few detailed articles out there if you search for it, and they've been discussed on hn as well (I'm on phone so can't be bothered). It allows you to merge numerous feature "branches" (again, jj branches, which are optionally also git branches if you use bookmarks) into a new branch, which lets you easily work on top of the combined functionality of various branches that are in progress. You can then interactive squash changes into their respective feature branches prior to the empty megamerge commit/change. There's also jj absorb, which does this interactive squash in a sort of magical, automatic way (though I find that sometimes it just doesn't do anything) There's so much more to say about it, but overall you just don't need to think about git at all and instead just think about your code, and then tidy up the history etc as-needed, without much cognitive overhead or friction. This is all made even easier by the absolutely fantastic https://github.com/idursun/jjui https://github.com/idursun/jjui TUI. It's largely "just" a wrapper with shortcuts over jj commands and their resulting output. But it makes what's already simple absolutely seamless. I hope this helps. Jj and jjui are absolutely beautiful. Ignore all the luddites who try to say "if it's just git under the hood, then I'll just keep using that myself, thank you very much". I never intend to "raw dog" (as the kids say) git again. I do use some git mechanisms in vscode though - merge conflict resolution, diff visualization (it shows whatever has changed in the current jj change)
penguin_booze 1y ago
[flagged]
myst 1y ago
I was under impression, JJ is simple and is a UX step up over Git.
- 8n4vidtmkvmk 1y ago
  I found it pretty simple to get started with, but I also have a mercurial background, which I think is more closely aligned with jj.
Jenk 1y ago
The one paragraph that helped jj begin to click for me was this one from Steve's Jujutsu Tutorial[0]: > If you want to replicate git's behavior, typing an additional command after each change is done feels like overkill. But I would argue this is not the right way to use jj; as you'll see, we'll be either re-writing commits at the tip of branches, or doing multiple steps of work before updating where a branch points. In practice, it means I check the branch status before pushing code, rather than as I work. That is, the branch name tends to sit at the same change as the remote server, and when it's time to update the remote, that's when I update things locally. [0]: https://steveklabnik.github.io/jujutsu-tutorial/sharing-code/named-branches.html https://steveklabnik.github.io/jujutsu-tutorial/sharing-code... (emphasis mine) That, as I interpreted it, is to mean one should begin to "forget" git in order to appreciate jj with a sense of new beginning. Previously, I was continuously translating jj to git, and vice-versa. After reading this paragraph, I now mentally model the jj-git relationship as a kind of 3rd stage of the workflow, rather than previously assuming jj as an abstraction on top of git.
- steveklabnik 1y ago
  I'm glad that helped you!
  - Darmani 1y ago
    I like it too and just added it to the slides, as an interlude after Exercise 5.
    - steveklabnik 1y ago
      Cool cool, thanks for making good jj content :) We need more of it!
oakashes 1y ago
Something I ran into during exercise 2 (and from watching the solution video[0] closely I see the author did as well): There were four consecutive changed lines in my original commit. When I split it, I selected the deletion and addition for the first two lines. In the resulting newly created commit, those two lines had been moved to below the other two lines, so the order was now 3 -> 4 -> 1 -> 2, with the second commit moving 3 and 4 back to their original places. I didn't figure out a clean way to fix this - when I edited the commit which changed lines 1 and 2 to put them back at the top, it made a conflict with the second commit which I had to repair. Anybody know what I should have done differently to split the commit and keep the edited lines in their original places? [0]: https://www.loom.com/share/e3e148f07fb9420180ebb047f5ca94b3 https://www.loom.com/share/e3e148f07fb9420180ebb047f5ca94b3
- Darmani 1y ago
  Wow, good catch! I had not noticed. I don't know if there is a fix for this. It seems to be a fundamental issue of the delete-and-add way of representing change hunks.
  - palata 1y ago
    Is there a way to do something similar to `git add -p`? I am used to editing the patch manually, but jj forces me to use their TUI and I get into the same issue.
- deleted 1y ago
  [deleted]
- kinghajj 1y ago
  It seems to work correctly if you include the last two lines in the first commit. jj-workshop on  HEAD (2cab0f1) [!] > jj @ unwquwxk samfredrickson@gmail.com 2025-07-29 18:47:18 f7db7c8a │ Part 2 first ○ wskswvnt samfredrickson@gmail.com 2025-07-29 18:47:13 git_head() 2cab0f16 │ Part 2 second ◆ pnxpmvpz jkoppel@users.noreply.github.com 2025-07-27 21:54:50 main 4d04bcef │ Update README.md with link to JJ homepage ~ jj-workshop on  HEAD (2cab0f1) [!] > jj show w --git Commit ID: 2cab0f167c64cea1d23407e12196fa6d1b8aab25 Change ID: wskswvntlvtwzqutoowyqltsouklzmqr Author : Sam Fredrickson <samfredrickson@gmail.com> (2025-07-29 18:34:52) Committer: Sam Fredrickson <samfredrickson@gmail.com> (2025-07-29 18:47:13) Part 2 second diff --git a/part1/foo.txt b/part1/foo.txt index 067f76475a..56c99c9cc3 100644 --- a/part1/foo.txt +++ b/part1/foo.txt @@ -6,5 +6,5 @@ * The best operating system is ______ * The best text editor is ______ -* The best kind of phone is _______ -* The best superhero is ___________ +* The best kind of phone is nothing +* The best superhero is nobody jj-workshop on  HEAD (2cab0f1) [!] > jj show u --git Commit ID: f7db7c8a5f37df8c29e08a6697ca6cd59c2313c4 Change ID: unwquwxklkprlqoksmxzvoumspnmnknk Author : Sam Fredrickson <samfredrickson@gmail.com> (2025-07-29 18:34:52) Committer: Sam Fredrickson <samfredrickson@gmail.com> (2025-07-29 18:47:18) Part 2 first diff --git a/part1/foo.txt b/part1/foo.txt index 56c99c9cc3..f48ae9b3f9 100644 --- a/part1/foo.txt +++ b/part1/foo.txt @@ -4,7 +4,7 @@ Maybe fill this out? -* The best operating system is ______ -* The best text editor is ______ +* The best operating system is Linux +* The best text editor is neovim * The best kind of phone is nothing * The best superhero is nobody

178 points by todsacerdoti 1y ago

this looks great. excited to give it a go!

Shoutout to graphite.dev that gives you a stacked workflow on top of git/github - everything actually stays git, it just auto-updates the stack of branches and manages updating the PRs accordingly + will auto-merge PRs for you once they’re ready.

mpalmer 1y ago
The point of jj is to improve on the git interface. It's kind of weird to imply that jj's purpose is a drawback. I don't want git to stay git. Nor do I want SAAS solving stacked PRs for me, "free option" or not. jj is explicitly not for teams - there's no way to share jj-proprietary stuff between checkouts of a repo, because it's a frontend for interacting with a git repo.
- nulld3v 1y ago
  Ehhh, when I explain jj to people I like to say that it is "a tool to edit git repos", and that "the repo is still a git repo" because people have so many misconceptions of how jj works. When they see how different jj's interface is from git, they think it's a whole new VCS and are worried that it will break compatibility with other git tools. That said, I only do this to avoid overwhelming beginners, when actually learning/using jj it is definitely more useful to think of it as a different VCS.
  - mpalmer 1y ago
    Telling people it's a tool to edit git repos makes it sound hackier than it is; not surprising they're nervous it'll break something. Just tell them git makes mistakes easy, and jj makes them difficult.
    - nulld3v 1y ago
      I've tried that but it isn't very effective because usually if they are not a git wizard, they are already using some sort of git interface or GUI that prevents them from making catastrophic mistakes. So they don't see the appeal in relearning all their git knowledge and terminology. Hence why I initially try to sell it as an addition to their toolbox, instead of as a replacement for their entire workflow.
      - nchmy 1y ago
        I agree with you both. Jj makes mistakes hard, but also makes it easy to just focus on your code and easily sort out anything git-related later as an after-thought.
- vlovich123 1y ago
  Graphite also improves on the interface if you want that. I personally have no issues with git anymore having spent nearly two decades working with it.

sastraxi 1y ago

Looks good! I might have missed it but it would be helpful to have a link to the jujutsu home page in your README.md.

Darmani 1y ago
Creator here. Done.

sn9 1y ago

My understanding of jj is that's it's meant to be compatible with git. Does that mean that working through this will also improve your git usage? Or could be used to teach someone git workflows?

baq 1y ago
Haven’t reviewed the material, but compatible is a weak word - jj is also compatible with a plain filesystem. The point is that it makes some workflows easy and accessible which are hard and cumbersome in git, so they become the new normal instead of things to avoid.
nchmy 1y ago
You'd only really learn anything if you know nothing. The underlying git is largely invisible, and the workflows are vastly different - for the better. It is constantly making new git commits any time you use a jj command. (I even have it set up to use watchman to create commits any time any file changes - this is unimportant for this discussion). But the commits are completely hidden - we instead interact with jj "changes", which are more like a constantly evolving, auto-adding, auto-committing, stash-free, movable git commit. Git branches are even a 2nd class citizen. We can create endless "branches" by adding new changes on top of any existing change, and then merge that with an arbitrary amount of other changes by specifying them when creating a new change. We can also rebase/move changes around all over the place, and the changes get automatically propagated through any descendents. We can also split and squash commits very easily, and even do so on a granular level - easily and interactively select lines or sections of changed code within one change to be split or squashed into a different change. This allows you to just work, and then tidy the history up later when you have a clue. Conflicts that arise from merge/rebase/split/squash/etc do not require immediate intervention - fix them when you want to, and the fix will also propagate through. You can use jj resolve to open the conflicts in your merge conflict editor of choice (I use vs code). We use git branches when we apply/update a jj bookmark to any change. This essentially creates/changes a git branch, which can then be pushed to Github. When bookmarks are pushed, the ancestor changes become "immutable" by default, which prevents things like editing, rebasing etc, so as to facilitate collaboration. But it can be override, and I presume it does things like a force push for you. One thing to note is that your jj "branches" etc are not shared as it just stays local. You could, in theory, sync your .jj folder remotely, but I don't see that being particularly feasible unless it's just to sync with another device for your own use (or back it up in case of data loss). It's really just a local interface for individual use, and collaboration still happens via git branches and pull requests. If you were to lose your jj folder, you could clone the git repo again and you'd just start with the existing git branches etc. I'll mention one particularly powerful/useful jj workflow - the megamerge. There's a few detailed articles out there if you search for it, and they've been discussed on hn as well (I'm on phone so can't be bothered). It allows you to merge numerous feature "branches" (again, jj branches, which are optionally also git branches if you use bookmarks) into a new branch, which lets you easily work on top of the combined functionality of various branches that are in progress. You can then interactive squash changes into their respective feature branches prior to the empty megamerge commit/change. There's also jj absorb, which does this interactive squash in a sort of magical, automatic way (though I find that sometimes it just doesn't do anything) There's so much more to say about it, but overall you just don't need to think about git at all and instead just think about your code, and then tidy up the history etc as-needed, without much cognitive overhead or friction. This is all made even easier by the absolutely fantastic https://github.com/idursun/jjui https://github.com/idursun/jjui TUI. It's largely "just" a wrapper with shortcuts over jj commands and their resulting output. But it makes what's already simple absolutely seamless. I hope this helps. Jj and jjui are absolutely beautiful. Ignore all the luddites who try to say "if it's just git under the hood, then I'll just keep using that myself, thank you very much". I never intend to "raw dog" (as the kids say) git again. I do use some git mechanisms in vscode though - merge conflict resolution, diff visualization (it shows whatever has changed in the current jj change)

penguin_booze 1y ago

[flagged]

myst 1y ago

I was under impression, JJ is simple and is a UX step up over Git.

8n4vidtmkvmk 1y ago
I found it pretty simple to get started with, but I also have a mercurial background, which I think is more closely aligned with jj.

Jenk 1y ago

The one paragraph that helped jj begin to click for me was this one from Steve's Jujutsu Tutorial[0]: > If you want to replicate git's behavior, typing an additional command after each change is done feels like overkill. But I would argue this is not the right way to use jj; as you'll see, we'll be either re-writing commits at the tip of branches, or doing multiple steps of work before updating where a branch points. In practice, it means I check the branch status before pushing code, rather than as I work. That is, the branch name tends to sit at the same change as the remote server, and when it's time to update the remote, that's when I update things locally. [0]: https://steveklabnik.github.io/jujutsu-tutorial/sharing-code/named-branches.html https://steveklabnik.github.io/jujutsu-tutorial/sharing-code... (emphasis mine) That, as I interpreted it, is to mean one should begin to "forget" git in order to appreciate jj with a sense of new beginning. Previously, I was continuously translating jj to git, and vice-versa. After reading this paragraph, I now mentally model the jj-git relationship as a kind of 3rd stage of the workflow, rather than previously assuming jj as an abstraction on top of git.

steveklabnik 1y ago
I'm glad that helped you!
- Darmani 1y ago
  I like it too and just added it to the slides, as an interlude after Exercise 5.
  - steveklabnik 1y ago
    Cool cool, thanks for making good jj content :) We need more of it!

oakashes 1y ago

Something I ran into during exercise 2 (and from watching the solution video[0] closely I see the author did as well): There were four consecutive changed lines in my original commit. When I split it, I selected the deletion and addition for the first two lines. In the resulting newly created commit, those two lines had been moved to below the other two lines, so the order was now 3 -> 4 -> 1 -> 2, with the second commit moving 3 and 4 back to their original places. I didn't figure out a clean way to fix this - when I edited the commit which changed lines 1 and 2 to put them back at the top, it made a conflict with the second commit which I had to repair. Anybody know what I should have done differently to split the commit and keep the edited lines in their original places? [0]: https://www.loom.com/share/e3e148f07fb9420180ebb047f5ca94b3 https://www.loom.com/share/e3e148f07fb9420180ebb047f5ca94b3

Darmani 1y ago
Wow, good catch! I had not noticed. I don't know if there is a fix for this. It seems to be a fundamental issue of the delete-and-add way of representing change hunks.
- palata 1y ago
  Is there a way to do something similar to `git add -p`? I am used to editing the patch manually, but jj forces me to use their TUI and I get into the same issue.
deleted 1y ago
[deleted]
kinghajj 1y ago
It seems to work correctly if you include the last two lines in the first commit. jj-workshop on  HEAD (2cab0f1) [!] > jj @ unwquwxk samfredrickson@gmail.com 2025-07-29 18:47:18 f7db7c8a │ Part 2 first ○ wskswvnt samfredrickson@gmail.com 2025-07-29 18:47:13 git_head() 2cab0f16 │ Part 2 second ◆ pnxpmvpz jkoppel@users.noreply.github.com 2025-07-27 21:54:50 main 4d04bcef │ Update README.md with link to JJ homepage ~ jj-workshop on  HEAD (2cab0f1) [!] > jj show w --git Commit ID: 2cab0f167c64cea1d23407e12196fa6d1b8aab25 Change ID: wskswvntlvtwzqutoowyqltsouklzmqr Author : Sam Fredrickson <samfredrickson@gmail.com> (2025-07-29 18:34:52) Committer: Sam Fredrickson <samfredrickson@gmail.com> (2025-07-29 18:47:13) Part 2 second diff --git a/part1/foo.txt b/part1/foo.txt index 067f76475a..56c99c9cc3 100644 --- a/part1/foo.txt +++ b/part1/foo.txt @@ -6,5 +6,5 @@ * The best operating system is ______ * The best text editor is ______ -* The best kind of phone is _______ -* The best superhero is ___________ +* The best kind of phone is nothing +* The best superhero is nobody jj-workshop on  HEAD (2cab0f1) [!] > jj show u --git Commit ID: f7db7c8a5f37df8c29e08a6697ca6cd59c2313c4 Change ID: unwquwxklkprlqoksmxzvoumspnmnknk Author : Sam Fredrickson <samfredrickson@gmail.com> (2025-07-29 18:34:52) Committer: Sam Fredrickson <samfredrickson@gmail.com> (2025-07-29 18:47:18) Part 2 first diff --git a/part1/foo.txt b/part1/foo.txt index 56c99c9cc3..f48ae9b3f9 100644 --- a/part1/foo.txt +++ b/part1/foo.txt @@ -4,7 +4,7 @@ Maybe fill this out? -* The best operating system is ______ -* The best text editor is ______ +* The best operating system is Linux +* The best text editor is neovim * The best kind of phone is nothing * The best superhero is nobody