Stacks in Jujutsu

This article is part of a series on Stacks in Jujutsu. Other articles in the series:

GitHub Stacks in Jujutsu
Stacks in Jujutsu <== you are here

Here are some helpers to make basic stack operations easier with Jujutsu (jj).

Full configuration

Everything below, distilled into one config. Run jj config edit --user and add the following to get it all:

1
[aliases.move-to]
2
definition = ["util", "exec", "--", "bash", "-c", """
3
cd "${JJ_WORKSPACE_ROOT:-.}"
4
revset=$1
5
shift
6
edit=$(jj config get ui.movement.edit 2>/dev/null || echo false)
7
args=()
8
for a in "$@"; do
9
  case $a in
10
    -e|--edit)    edit=true ;;
11
    -n|--no-edit) edit=false ;;
12
    *)            args+=("$a") ;;
13
  esac
14
done
15
if $edit; then verb=edit; else verb=new; fi
16
exec jj "$verb" "${args[@]}" "$revset"
17
""", "jj-move"]
18
doc = "Move to a revset: new child of it, or edit it with -e"
19

20
[aliases.bottom]
21
definition = ["move-to", "stack_bottom()"]
22
doc = "Move to the bottom of the current stack, stack_bottom()"
23

24
[aliases.top]
25
definition = ["move-to", "stack_top()"]
26
doc = "Move to the top of the current stack, stack_top()"
27

28
[aliases.sb]
29
definition = ["stack-bookmarks"]
30
doc = "Shorthand for stack-bookmarks"
31

32
[aliases.stack-bookmarks]
33
definition = [
34
  "--config",
35
  "revsets.log=substack()",
36
  "log",
37
  "--no-graph",
38
  "--reversed",
39
  "-T",
40
  'if(local_bookmarks, local_bookmarks.map(|b| b.name()).join(" ") ++ " ", "")'
41
]
42
doc = "Local bookmark names in substack(@), oldest first, space-separated"
43

44
[revset-aliases."stack_heads()"]
45
definition = "stack_heads(@)"
46
doc = "Newest mutable commits at or ahead of the working copy"
47

48
[revset-aliases."stack_heads(to)"]
49
definition = "heads(mutable() & to::)"
50
doc = "Newest mutable commits at or ahead of to"
51

52
[revset-aliases."stack_top()"]
53
definition = "stack_top(@)"
54
doc = "Newest mutable, single commit at or ahead of the working copy"
55

56
[revset-aliases."stack_top(to)"]
57
definition = "exactly(stack_heads(to), 1)"
58
doc = "Newest mutable, single commit at or ahead of to"
59

60
[revset-aliases."stack_bottom(to)"]
61
definition = "roots(mutable() & ::to)"
62
doc = "Oldest mutable commits at or behind to"
63

64
[revset-aliases."stack_bottom()"]
65
definition = "stack_bottom(@)"
66
doc = "Oldest mutable commits at or behind the working copy"
67

68
[revset-aliases."stack(to)"]
69
definition = "stack_bottom(to)::stack_top(to)"
70
doc = "Full stack containing to, from stack_bottom(to) to stack_top(to)"
71

72
[revset-aliases."stack()"]
73
definition = "stack(@)"
74
doc = "Full stack containing the working copy, from its bottom to its top"
75

76
[revset-aliases."substack(to)"]
77
definition = "stack_bottom(to)::to"
78
doc = "Stack containing to, from stack_bottom(to) through to"
79

80
[revset-aliases."substack()"]
81
definition = "substack(@)"
82
doc = "Stack from its bottom through the working copy"
83

84
[revset-aliases."tree()"]
85
definition = "tree(@)"
86
doc = "Full tree (all stacks) containing the working copy"
87

88
[revset-aliases."tree(to)"]
89
definition = "reachable(to, mutable())"
90
doc = "Full tree (all stacks) containing to"

Revsets in jj are expressions in “a functional language for selecting a set of revisions.” jj allows you to define revset aliases that can be used anywhere that accepts revsets. The revset aliases that follow make it easier to select revisions in stacks.

`stack_heads()`

Select the topmost commits. Selects all topmost commits if there is a fork.

1
[revset-aliases."stack_heads()"]
2
definition = "stack_heads(@)"
3
doc = "Newest mutable commits at or ahead of the working copy"
4

5
[revset-aliases."stack_heads(to)"]
6
definition = "heads(mutable() & to::)"
7
doc = "Newest mutable commits at or ahead of to"

stack_heads()

`stack_top()`

Select the single, topmost commit. Errors if there are multiple top commits (e.g. there is a fork above the current commit).

1
[revset-aliases."stack_top()"]
2
definition = "stack_top(@)"
3
doc = "Newest mutable, single commit at or ahead of the working copy"
4

5
[revset-aliases."stack_top(to)"]
6
definition = "exactly(stack_heads(to), 1)"
7
doc = "Newest mutable, single commit at or ahead of to"

stack_top()

stack_top() => Error: The revset has more than the
                      expected 1 revisions

`stack_bottom()`

Select the bottommost commits.

1
[revset-aliases."stack_bottom(to)"]
2
definition = "roots(mutable() & ::to)"
3
doc = "Oldest mutable commits at or behind to"
4

5
[revset-aliases."stack_bottom()"]
6
definition = "stack_bottom(@)"
7
doc = "Oldest mutable commits at or behind the working copy"

stack_bottom()

`stack()`

Select the entire stack.

1
[revset-aliases."stack(to)"]
2
definition = "stack_bottom(to)::stack_top(to)"
3
doc = "Full stack containing to, from stack_bottom(to) to stack_top(to)"
4

5
[revset-aliases."stack()"]
6
definition = "stack(@)"
7
doc = "Full stack containing the working copy, from its bottom to its top"

stack()

`substack()`

Same as stack(), but the top is the current commit instead of the top of the stack.

1
[revset-aliases."substack(to)"]
2
definition = "stack_bottom(to)::to"
3
doc = "Stack containing to, from stack_bottom(to) through to"
4

5
[revset-aliases."substack()"]
6
definition = "substack(@)"
7
doc = "Stack from its bottom through the working copy"

substack()

`tree()`

Same as stack(), but selects all connected branches to the stack as well.

1
[revset-aliases."tree()"]
2
definition = "tree(@)"
3
doc = "Full tree (all stacks) containing the working copy"
4

5
[revset-aliases."tree(to)"]
6
definition = "reachable(to, mutable())"
7
doc = "Full tree (all stacks) containing to"

tree()

Command examples

Command	Explanation
`jj edit -r "stack_top()"`	edit the top commit in your current stack
`jj log -r "stack(w)"`	log all commits in the stack containing `w`
`jj diff -r "stack()"`	total diff of the entire stack

Aliases

jj allows you to define aliases for commands, including their arguments.

`move-to`

Add move-to, a bash script alias. This behaves like jj next/jj edit and moves to a specific revision, honoring the ui.movement.edit configuration, which --edit/--no-edit override. In ~/.config/jj/config.toml add:

1
[aliases.move-to]
2
definition = ["util", "exec", "--", "bash", "-c", """
3
cd "${JJ_WORKSPACE_ROOT:-.}"
4
revset=$1
5
shift
6
edit=$(jj config get ui.movement.edit 2>/dev/null || echo false)
7
args=()
8
for a in "$@"; do
9
  case $a in
10
    -e|--edit)    edit=true ;;
11
    -n|--no-edit) edit=false ;;
12
    *)            args+=("$a") ;;
13
  esac
14
done
15
if $edit; then verb=edit; else verb=new; fi
16
exec jj "$verb" "${args[@]}" "$revset"
17
""", "jj-move"]
18
doc = "Move to a revset: new child of it, or edit it with -e"

You can call this directly from the CLI with jj move-to <revset>, but it’s mainly a helper function for other aliases we will call.

Examples:

jj move-to w

By default it runs `jj new ...`, creating a new revision
                      on top of the given revision wherever it sits in the
                      stack

jj move-to w --edit

Passing `--edit` (or setting `ui.movement.edit = true`)
                      moves `@` to the given revision

`top` and `bottom`

jj has built-ins for moving forward/backward: jj next and jj prev. Let’s add jj top and jj bottom to move all the way to the top or bottom of the current stack. In ~/.config/jj/config.toml add:

1
[aliases.bottom]
2
definition = ["move-to", "stack_bottom()"]
3
doc = "Move to the bottom of the current stack, stack_bottom()"
4

5
[aliases.top]
6
definition = ["move-to", "stack_top()"]
7
doc = "Move to the top of the current stack, stack_top()"

Examples:

jj top

`jj top` by default adds a new empty revision on top of
                      the stack and leaves `feature-4` where it was

jj top --edit

Passing `--edit` (or setting `ui.movement.edit = true`)
                      moves `@` to the existing top revision

Alternatively, if you always want jj new functionality and never jj edit, or vice versa, you can omit the move-to alias and just hard-code new:

1
[aliases.bottom]
2
definition = ["new", "stack_bottom()"]
3
doc = "Move to the bottom of the current stack, stack_bottom()"
4

5
[aliases.top]
6
definition = ["new", "stack_top()"]
7
doc = "Move to the top of the current stack, stack_top()"

or edit:

1
[aliases.bottom]
2
definition = ["edit", "stack_bottom()"]
3
doc = "Move to the bottom of the current stack, stack_bottom()"
4

5
[aliases.top]
6
definition = ["edit", "stack_top()"]
7
doc = "Move to the top of the current stack, stack_top()"

`stack-bookmarks` (`sb`)

Next, configure jj stack-bookmarks (alias: jj sb) to give you a bottom-up, space-separated list of local bookmark names in your stack. This is useful for workflows that need the stack bookmarks, e.g. gh stack. In ~/.config/jj/config.toml add:

1
[aliases.sb]
2
definition = ["stack-bookmarks"]
3
doc = "Shorthand for stack-bookmarks"
4

5
[aliases.stack-bookmarks]
6
definition = [
7
  "--config",
8
  "revsets.log=substack()",
9
  "log",
10
  "--no-graph",
11
  "--reversed",
12
  "-T",
13
  'if(local_bookmarks, local_bookmarks.map(|b| b.name()).join(" ") ++ " ", "")'
14
]
15
doc = "Local bookmark names in substack(@), oldest first, space-separated"

Examples:

Either call it with no arguments (the default revset is substack()):

jj sb => feature-1 feature-2 feature-3

Or pass it a revset:

jj sb -r w::y => feature-2 feature-3 feature-4

Or hand it a revset alias, e.g. to get the whole stack:

jj sb -r "stack()" => feature-1 feature-2
                      feature-3 feature-4

Production Notes

AI Facts

1 serving per container

Serving sizeAbout 1 article

Amount per serving

Machine-Written Words 0%

% 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%
Diagram Content Commits, bookmarks, revsets, etc. 0%
Component Code 100%
Commit Graph Component The code for the Astro component that draws the jj commit graphs, built on @hpcc-js/wasm-graphviz. 100%
AI Facts Component The code (not content) for this Astro component. 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.