Table of contents

• Rename with plain Git
• Rename with Graphite (stack-aware)
• Minimal end-to-end examples
• Good practices
• Frequently asked questions

Renaming a branch in Git (and with Graphite)

Renaming a Git branch touches two places: your local repo and (if you’ve pushed) the remote (e.g., origin on GitHub). If you use Graphite for stacked PRs, there’s also a one-command path that keeps your stack tidy.

Rename with plain Git

1. Rename locally

• If you are on the branch you want to rename:

  Terminal

  git branch -m NEW_NAME
  
  

• If you are on a different branch:

  Terminal

  git branch -m OLD_NAME NEW_NAME
  
  

This updates only your local branch name.

2. Push the new branch and remove the old remote

git push origin NEW_NAME
git push origin --delete OLD_NAME

This publishes the newly named branch and removes the old one from the remote.

3. Re-establish upstream tracking (recommended)

git push --set-upstream origin NEW_NAME

This tells your local branch which remote branch to track going forward.

Rename with Graphite (stack-aware)

If you use Graphite for stacked branches/PRs, use:

gt rename NEW_NAME

What it does:

• Renames the current branch and updates Graphite metadata.
• Notes: GitHub PR branch names are immutable; renaming breaks the PR’s branch association. Graphite warns you and (if needed) you can force with --force. After renaming, you’ll typically resubmit the PR on the new branch name.

Tip for stacks: renaming doesn’t move a branch in the stack; it keeps its position. If your stack needs cleanup afterward, run a restack:

gt branch restack

(or the equivalent command in your version of the CLI). GUI tools integrating Graphite expose the same rename action and keep the branch in place in the stack.

Minimal end-to-end examples

Example 1: feature/login → feature/auth (plain Git)

git checkout feature/login
git branch -m feature/auth
git push origin feature/auth
git push origin --delete feature/login
git push --set-upstream origin feature/auth

Now git pull/git push work as before, just under the new name.

Example 2: feature/login → feature/auth (Graphite)

git checkout feature/login
gt rename feature/auth
# if there was an open PR on GitHub, re-submit from feature/auth
gt submit

If Graphite indicates the old PR association can’t be kept, follow the prompt or use --force, then resubmit.

Good practices

• Warn teammates before renaming shared branches to prevent broken references in open PRs or CI.
• Update docs/scripts that reference the old name.
• Prefer short, consistent names (e.g., feat/auth, fix/tx-timeout). Graphite’s docs have a quick guide on branch naming conventions if you want patterns to follow.

Frequently asked questions

Do I have to delete the old remote branch?

Yes, if you want to avoid duplicate branches on the remote. Renaming locally doesn't touch the old remote; push the new name and delete the old one.

I renamed the branch but git push says "no upstream configured."

Set the upstream again:

git push --set-upstream origin NEW_NAME

This re-links your local branch to its remote counterpart.

What happens to my GitHub PR when I use gt rename?

GitHub PR branch names can't be changed. Graphite will note that the PR's branch association is removed; you'll submit a new PR on the renamed branch (use gt submit). Use --force if you must rename despite an open PR. For more information on managing pull requests with Graphite, see our guide on implementing feature branch workflows in GitHub.

I use stacked branches. Will renaming break my stack?

The rename keeps the branch in place within the stack; restack if you've done other surgery (gt branch restack). Graphite-integrated UIs expose a Rename action that maps to gt rename and preserves stack relationships. To learn more about managing stacked branches, see our guide on advanced Git branching strategies.

Can I rename the default branch (e.g., master → main)?

Yes, but coordinate with your host (GitHub has a one-click rename that updates references) and your team. Locally, you can still use git branch -m; then update the remote default and any branch protections/CI settings. (Host-specific details vary and aren't covered here.)

Is git branch -m the same as --move?

Yes—-m is short for --move; both rename the branch.