Skip to content

Instantly share code, notes, and snippets.

@nissan
Forked from edwardmyung/graphite-dev.md
Created June 29, 2024 10:25
Show Gist options
  • Save nissan/bd033aff142d6e9d67170fc72711cb1a to your computer and use it in GitHub Desktop.
Save nissan/bd033aff142d6e9d67170fc72711cb1a to your computer and use it in GitHub Desktop.
Graphite.dev Basic Guide

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment