Graphite.dev Basic Guide

graphite-dev.md

Graphite.dev

• Site: https://graphite.dev
• Docs: https://docs.graphite.dev/

Why?

• Stacked PRs allow you to easily work like so:
  • Work on branch ACQ-000-part-A (which is based on master)
  • Work on branch ACQ-000-part-B (which is based on part-A)
  • Work on branch ACQ-000-part-C (which is based on part-B)
• It enables you to work in small PRs without ever getting blocked by code-review
• Once all your work is done, you can merge:
  1. ACQ-000-part-C -> ACQ-000-part-B
  2. ACQ-000-part-B -> ACQ-000-part-A
  3. ACQ-000-part-A -> master

Miscellaneous commands

• gt log -> show all PRs in the current stack

---

Core workflow

1. Set the prefix for the feature e.g. gt config > "Branch name settings" > Set a new prefix
   • this should be done at the start of each ticket
2. Starting from master, make some changes (e.g. add api calls)
3. gt create -a -m ‘api-changes'
   • this will create a branch called "ACQ-000-api-changes"
4. Do work for the next PR on that branch (e.g. add edit address modal)
5. gt create -a -m 'edit-address-modal'
   • this will create a branch called "ACQ-000-edit-address-modal"

Navigating branches

• gt checkout (shorthand: gt co)
  • interactive branch navigator
  • lets you use arrow keys to go up/down a stack
• gt up (shorthand: gt u)
  • go to next branch of stack
• gt down (shorthand: gt d)
  • go to previous branch of stack

To update a mid-level branch

1. gt checkout -> then navigate with arrow-keys + 'Enter', to the branch you want to update
2. Make your fixes
3. Either:
   • gt create -a -m ‘fix stuff’ -> create a new branch on the stack
   • gt modify -a -c -> create a new commit
   • gt modify -a -> amend existing commit
4. graphite will auto-rebase all branches above the stack where you’ve just committed.
   • If you hit a conflict, the CLI will provide simple instructions on how to fix
   • This looks like: resolve conflicts -> git add changed files -> gt continue)

To submit PRs

• gt submit --stack - this will either: (i) create PRs (ii) update existing PRs for all branches of the stack up to the checked out commit

To sync with remote (master changes)

• gt sync (good practice to do this every time you start dev)

Merging a stack

Possible approaches:

1. Merge into master all at once: merge from the tip of the stack (latest PR) to the root of the stack (first PR), then merge the root
2. Merge into master one at a time:

• i. Merge the root
• ii. gt repo sync --restack from any branch of your local stack to reset the root
• iii. gt stack submit so that the new bottom of your stack can be merged into trunk
• iv. Repeat until all PRs are merged