Navigate a stack


To navigate a stack of branches with the Graphite CLI, make sure you've:

gt log

You can use gt log to view the current state of your repository:

> gt log
◉ pp--06-14-part_3 (current)
│ 8 seconds ago
│ 95338df - part 3
◯ pp--06-14-part_2
│ 8 seconds ago
│ 95610c6 - part 2
◯ pp--06-14-part_1
│ 27 seconds ago
│ 48cd85e - part 1
◯ main
│ 5 weeks ago

Branches in Graphite are just git branches under the hood—you can check them out with native git, but the easiest way is to use gt checkout:

# checkout pp--06-14-part_1
gt checkout pp--06-14-part_1
# even easier, use the alias!
gt co pp--06-14-part_1

If you aren't sure which branch you want to checkout, you can also use gt checkout (or gt co) in interactive mode:

> gt co
? Checkout a branch (autocomplete or arrow keys)
❯ pp--06-14-part_1

Now, you can see in gt log short you're on part_1 as intended:

> gt ls
◯ pp--06-14-part_3
◯ pp--06-14-part_2
◉ pp--06-14-part_1
◯ main

Sometimes you want to move to the branch directly above or below the current branch in a stack. The gt up, gt down, gt top, and gt bottom commands help make this possible.

Since gt bottom takes you to the bottom-most branch in your stack not including your trunk branch, you can use gt trunk, which always takes you to your trunk branch (e.g. main):

# check out the branch directly upstack (in this case part_2)
gt up
#alias for branch up
gt u
# check out the branch directly downstack (in this case back to part_1)
gt down
#alias for branch down
gt d
# move multiple branches at a time (up to part_3)
gt up 2
# alias for branch up 2
gt u 2
# move multiple branches at a time (back to main)
gt down 3
# alias for branch down 3
gt d 3
# move to the tip of the stack (back to part_3)
gt top
# alias for branch top
gt t
# move to the base of the stack, not including trunk (to part_1)
gt bottom
# alias for branch bottom
gt b
# move directly to the trunk branch
gt trunk


If you find yourself navigating a complex stack where there are multiple children of a particular branch, gt up and gt top will ask which child branch you'd like to checkout if there's ever ambiguity.