Prerequisites
To navigate a stack of branches with the Graphite CLI, make sure you've:
Initialized
gtin a repo of your choiceCreated or tracked a branch/stack of branches
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│
Check out a branch
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_1gt 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_3pp--06-14-part_2❯ pp--06-14-part_1main
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
Move up and down a stack
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 checkout --trunk/-t, 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 upgt u# check out the branch directly downstack (in this case back to part_1)gt down#alias for branch downgt d# move multiple branches at a time (up to part_3)gt up 2# alias for branch up 2gt u 2# move multiple branches at a time (back to main)gt down 3# alias for branch down 3gt d 3# move to the tip of the stack (back to part_3)gt top# alias for branch topgt t# move to the base of the stack, not including trunk (to part_1)gt bottom# alias for branch bottomgt b
Note
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.
