CLI troubleshooting FAQs
Tips for resolving common Graphite CLI issues.

If you find yourself in a bad state and are unsure how to proceed, please submit a bug report with debug information by running gt feedback and sending debug logs. This allows us to fix most issues.

If the CLI gets stuck in a broken state and you are not able to wait for a member of our team to help, there are a few options.

  • gt dev cache --clear is a safe command that sometimes fixes inadvertent issues that we haven't caught before release. It doesn't change any git or Graphite state.

  • gt untrack specific branches that are behaving weirdly. You will then need to re-track branches with gt track – note that in certain cases you may need to git rebase manually in order to track a branch with the correct parent. Read more about gt track .

  • gt init --reset is the nuclear option which deletes all Graphite metadata from your repository. All branches will need to be re-tracked.

If none of these work, and you would like specific help for your issue, reach out in our community Slack channel.

We use git push --force-with-lease under the hood for our push, which should ensure this doesn't happen. You should only be able to overwrite changes that you have already pushed from your machine or synced to your machine with gt get.

Using this option is just like using --force (push to a branch on remote even if remote's SHA cannot be fast-forwarded to the new SHA), with the caveat that if the remote's SHA for the branch doesn't match the "remote-tracking branch" on your machine (for example, refs/remotes/origin/feature), it will fail, as this means that someone else has updated the branch since you last pushed to it or pulled it. Graphite respects the "remote-tracking branch", only updating it on a gt submit or gt get operation.

The issue can arise if you have some other tooling (for example, some VS Code extension) that is git fetching your branches in the background. This could update the "remote-tracking branch" and result in the --force-with-lease check passing—even if someone has updated the branch to a commit that you haven't synced to your repository (or pushed yourself).

Because gt stack submit both performs a git push and a GitHub API call, occasionally GitHub will pick up both as a synchronize event on the PR.

We recommend using GitHub's concurrency configuration to ensure that you do not have duplicated CI.

For example, the following configuration will cancel previous CI runs on the same pull request:

yaml
concurrency:
group: ${{ github.repository }}-${{ github.workflow }}-${{ github.ref }}-${{ github.ref == 'refs/heads/main' && github.sha || ''}}
cancel-in-progress: true

The Graphite CLI use branches instead of commits to represent atomic changes in a stack. But it's possible to replicate the single-commit workflow.

Just don't use gt modify --commit, and if you end up with multiple commits on a branch by accident, you can always use gt squash to get your branch back to a single commit. This way, you can essentially only use gt, and your workflow will look something like (making use of lots of shortcuts and short-form flags):

Terminal
# make changes to the codebase
gt c -am "my first commit"
# make some more changes
gt c -am "my second commit"
# now we're ready to submit!
gt s -np
# address requested changes
gt co my_first_commit
gt m -a
gt ss
# or you can use
gt absorb -a
gt ss
# ... etc

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2