Update mid-stack branches

You can iterate on your stack before it's merged by using the following three concepts:

• Using gt checkout to hop between branches in your stack

• Adding changes to a branch using gt modify

• Pushing the new changes to remote using gt submit

Prerequisites

You should be familiar with how to:

• Create branches in a stack

• Visualize a stack

• Navigate a stack

• Create and submit pull requests

Working with commits

Any branch you create with Graphite (using the recommended workflow) will already contain a commit with your initial changes. There are two main ways to update your branch with new changes:

• Maintain the 1:1 relationship between commits and branches, meaning you'll use gt modify to continuously amend the commit on the branch

• Create multiple commits on each branch using gt modify --commit each time you make changes

Amend commits

Here's how you would address feedback on a branch in the middle of your stack by amending a commit. You would amend the commit that already exists on that branch with your new changes:

# address review comments by amending a commit

# navigte to the appropriate branch in the stack
gt checkout some_branch_mid_stack

# make some changes to your files

# amend the latest commit on that branch (this automatically restacks any branches upstack)
gt modify -a
# OR don't pass the -a flag to be prompted to stage changes interactively
gt modify

# you can also use aliases for both of these commands
gt co some_branch_mid_stack
gt m -a

Create commits

If you prefer to create an entirely new commit for each of the changes you make to a branch, you can use this flow:

# navigte to the appropriate branch in the stack
gt checkout some_branch_mid_stack

# make some changes to your files

# create a new commit (this automatically restacks any branches upstack)
gt modify --create -am "my fourth commit"
# OR don't pass -a or -m to be prompted to enter a commit message and stage changes interactively 
gt modify --create

# you can also use aliases for both of these commands
gt co some_branch_mid_stack
gt m -c

Automatically restack branches

Given that there are no merge conflicts (see next section), gt modify will automatically restack any upstack branches on top of your new changes and provide the following output:

1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 my amended commit
Restacked next_branch on some_branch_mid_stack.
Restacked last_branch on next_branch.

Resolve upstack conflicts when modifying branches

If gt modify encounters any conflicts as they recursively restack your branches, you'll be prompted to resolve your conflicts before continuing:

Hit conflict restacking next_branch on some_branch_mid_stack.

You are here (resolving next_branch):
◯ top_branch
◉ next_branch
◯ some_branch_mid_stack
◯ first_branch
◯ main

To fix and continue your previous Graphite command:
(1) resolve the listed merge conflicts
(2) mark them as resolved with gt add .
(3) run gt continue to continue executing your previous Graphite command
It's safe to cancel the ongoing rebase with `gt rebase --abort`

You can always exit out of the rebase using gt rebase --abort.

Read more about the intricacies of restacking branches.