GitHub Stacks in Jujutsu

Install CLIs

• You need the git (instructions) and jj (instructions) CLIs installed.
• You need the gh GitHub CLI installed (instructions).
• Install the stacking extension with gh extension install github/gh-stack

This article was written/tested against:

• jj v0.43.0
• git v2.52.0
• gh v2.96.0
• github/gh-stack v0.1.0

Configure jj

I will be re-using some jj aliases and revset aliases we defined in the previous article, Stacks in Jujutsu.

Bonus: Learn jj’s bookmark aliases

GitHub’s Stacked PRs require every PR to have a jj bookmark (git branch), so you’ll be creating a lot of these. UI tools in the future will surely automate creating branch names under the covers, but for now, learn the jj aliases for easily managing bookmarks:

[revset-aliases."closest_pushable(to)"]
definition = 'heads(::to & mutable() & ~empty() & description(regex:".+"))'
doc = "Closest mutable, non-empty, described commits at or behind to"
[revsets]
bookmark-advance-to = "closest_pushable(@)"

Create a stack

1. Either:

   • Manually create a bookmark for each commit in your stack:

     # go to the bottom of your stack using our revset alias
     jj bottom --edit
     # give commit a name
     jj b c <name>
     # go to the next commit
     jj next --edit
     # give commit a name
     jj b c <name>
     # ... repeat for each commit in stack

   • Or push your commits to GitHub with automatic branch names:

     jj git push --change "stack()"

     --change takes the place of -r, also takes a revset argument, and:

     • It uses templates.git_push_bookmark to create a bookmark for each change it pushes.
     • templates.git_push_bookmark has a default value of "push-" ++ change_id.short(), e.g. push-lltmmqnymopn, and can be customized.
     • If a change already has a bookmark, jj git push -c will NOT use it. It still uses a new push-lltmmqnymopn bookmark.
     • If you re-push, it re-uses the existing bookmark.
     • jj git push -c is smart about not pushing changes with no description, e.g. if you’re on a new empty commit and try to push it with -c you’ll get an error.
     • Lobste.rs users offby1 and bengesoff shared their custom templates:

       [template-aliases]
       "slugify(str)" = '''
         truncate_end(
           65,
           str.first_line()
             .replace(regex:'[^[[:alnum:]].]', '-')
             .replace(regex:'-{2,}', '-')
             .replace(regex:'\.{2,}', '.')
             .replace(regex:'(^-+|-+$)', '')
             .lower()
         )
       '''
       git_push_bookmark = 'slugify(description) ++ "/" ++ change_id.short()'

       With this, push-lltmmqnymopn becomes backend-api-changes/lltmmqnymopn.

2. Upload your bookmarks to GitHub, create draft PRs for each, and link them all into a stack:

   Using our stack alias:

   gh stack link $(jj sb -r "stack()")

   Or, using a jj revision range:

   gh stack link $(jj sb -r commit1::commitN)

   Or, since jj sb defaults to your substack, you can go to the top (where your stack and substack are the same thing) and then link the entire stack:

   jj top --edit
   gh stack link $(jj sb)

   This last one is probably the easiest to remember.

3. Whether you used your own bookmarks or jj git push --change "stack()" above, your draft PRs are going to need cleaning up before they’re ready to publish, so head to the GitHub web UI and clean up the titles and PR descriptions for each PR, and then mark them as ready to review.

Add a new commit to the TOP of the stack

Assuming the new commit is change id abc:

1. Make sure you’re editing your new commit:
2. Create a bookmark for the new, current commit:
3. If you’ve modified any of the downstack commits, you need to push the updates (since jj git push will do a --force-with-lease push, but gh stack link won’t):
4. Re-run link with all stack bookmarks: The existing PRs (for everything downstack) will be skipped and the new branch will get a new draft PR and will be linked into the stack.

Add a new commit to the BOTTOM or MIDDLE of the stack

You can’t add to the middle of a stack (you’ll get an error: “Cannot update stack: new PRs must be added to the top of the existing stack”), so you have to delete your stack and recreate it. Assuming the new commit is change id abc:

1. Go to the GitHub web UI and remove the stack:
2. Create a bookmark for the new commit:
3. Since you’ve modified the rebased, upstack commits, re-push everything:
4. Re-run link with all stack bookmarks, including the new one:

   jj top --edit
   gh stack link $(jj sb)

   the existing PRs will be skipped, and the new branch will get a new draft PR and will be linked into the stack

Remove a commit from the stack

You have to delete your stack and recreate it. Assuming the commit to remove is change id abc:

1. Go to the GitHub web UI and remove the stack:
2. Make sure you’re at the top of the stack:
3. Abandon the commit if you haven’t already:
4. Push your updates:
5. Re-run link with all stack bookmarks:

   jj top --edit
   gh stack link $(jj sb)

   the existing PRs will be skipped and the stack will be recreated
6. Your removed commit will have an orphaned PR on GitHub. Manually close it and/or delete the remote branch if you want. Or, push all deleted bookmarks with jj git push --deleted.

NOTE: Deleting the remote branch closes its PR, so if you run the jj git push --deleted before re-running gh stack link ..., you will end up closing the PR ABOVE the removed branch as well. Delete after linking to avoid this.

Update the existing commits of an existing stack

1. Re-push your stack:

Merge your stack

Like unstacking, it is theoretically possible to do it from the CLI, but too complicated:

gh stack link --open $(jj sb -r "stack()") # draft => published
gh stack merge $(gh pr view "$(jj sb -r "stack()" | awk '{print $NF}')" --json number --jq .number) --yes --squash

So, just do this from the web UI. You’ll probably be there anyway, checking on that CI signal. 🤷🏽‍♀️

Reordering commits

1. Reorder your commits locally, however you want (e.g. jj arrange):

   jj arrange

2. Go to the GitHub web UI and remove the stack: You have to do this first, since, while a PR is in a stack, GitHub refuses to change its base (“Cannot change the base branch because the pull request is part of a stack”).

3. Starting at the bottom-most commit, push each bookmark and retarget the base branch of each PR:

   # go to the bottom of the stack
   jj bottom --edit
   # re-push the bottom commit
   jj git push -r @
   # retarget bottom commit to base=main (or whatever your base is)
   gh pr edit $(jj sb) --base main
   # then, for each subsequent commit in your stack, one-by-one:
   #   1. re-push the substack
   #   2. re-link the substack, which retargets the PR bases
   for b in $(jj sb -r "stack() ~ stack_bottom()"); do
     jj edit "$b"
     jj git push -r "substack()" &&
     gh stack link $(jj sb) || break
   done

AI Facts

1 serving per container

Serving sizeAbout 1 article

% Machine*

• Prose Written by hand. Proof-read by machine. Edits applied by hand. 0%
• Code & Config 0%
• Creation All code/configuration written by hand. 0%
• Validation All code/configuration programmatically verified by Claude Opus 5 for correctness and consistency. Fixes applied by hand. 100%
• Human Review 100%

* % Machine tells you how much of this article a machine wrote. Values are yolo'd, not a measurement. This label has not been evaluated by the Food and Drug Administration.