Graphite Reviewer is now Diamond

How to change branches in Git

Kenny DuMez
Kenny DuMez
Graphite software engineer
Try Graphite


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


Branching in Git allows you to diverge from the main line of development and continue to work independently without affecting other branches. This guide provides a comprehensive overview of how to change branches in Git, including changing branch names both locally and remotely.

In Git, a branch represents an independent line of development within a repository, allowing you to diverge from the main project without affecting ongoing work. Each branch in Git encapsulates its own set of file modifications, commits, and subsequent history, distinct from other branches until merged. This feature is crucial for developers to experiment with new features, fix bugs, or safely integrate and test new code before committing it to the main project line.

Technically speaking, each branch is a lightweight movable pointer to a specific commit. When you create a new branch, Git simply creates a new pointer; it does not duplicate any files or directories. These pointers allow developers to switch between different contexts within the same repository.

Before changing branches, it's helpful to know which branch you're currently on. To see your current branch and all other branches that exist in your repository, you can use the following command:

Terminal
git branch

The branch you are currently on will be marked with an asterisk (*).

To change branches, you use the git checkout command, which will switch you from your current branch to another branch. If the branch does not exist locally, Git will try to find a matching branch in your remote repositories:

Terminal
git checkout <branch-name>

Replace <branch-name> with the name of the branch you want to switch to.

Example:

Suppose you are currently on the main branch and want to switch to a branch named feature-login. You would enter the following command in your terminal:

Terminal
git checkout feature-login

This command will switch the current workspace to the feature-login branch, updating the working directory to match the snapshot of that branch.

If you need to create a new branch and immediately switch to it, you can use the -b option with git checkout:

Terminal
git checkout -b <new-branch-name>

This command creates a new branch based on your current branch and switches to it.

If you need to rename a branch locally, you can use the git branch -m command:

Terminal
git branch -m <old-branch-name> <new-branch-name>

This is useful when you want to correct a typo in a branch name or update the branch name to reflect a change in the scope or direction of the feature you are working on.

Example:

To rename a branch from feature-lgooin to feature-login, you would use the following command:

Terminal
git branch -m feature-lgooin feature-login
  1. Rename the branch locally: Use the git branch -m command to rename the branch locally. This changes the branch's name locally but does not affect the remote branch until you push the changes.

    Terminal
    git branch -m <old-branch-name> <new-branch-name>
  2. Push the renamed branch to the remote repository: After renaming the branch locally, push the new branch to the remote repository. This step uploads the new branch to the remote server.

    Terminal
    git push origin <new-branch-name>
  3. Update the upstream tracking branch: You must reset the upstream branch for your local branch to track the new remote branch.

    Terminal
    git push --set-upstream origin <new-branch-name>
  4. Delete the old branch from the remote repository: To complete the renaming process, you should remove the old branch from the remote repository to avoid confusion and ensure that others do not continue to use it.

    Terminal
    git push origin --delete <old-branch-name>

This approach simplifies the process and correctly handles the renaming of a branch both locally and remotely, ensuring that the new branch name is tracked and the old branch is cleaned up from the remote repository.

For further reading on changing Git branches, see the official Git documentation.

The Graphite CLI simplifies branch management and offers enhancements like pull request (PR) stacking. It provides streamlined alternatives to traditional Git commands while enabling advanced workflows, such as syncing branches and managing stacks efficiently.

Instead of using git checkout main, the Graphite CLI offers the following command:

Terminal
gt checkout main

This performs the same task as the Git command but integrates seamlessly with the Graphite workflow, ensuring that your branches stay organized and up-to-date, especially in environments with stacked PRs.

The gt sync command simplifies the process of pulling changes from the main branch and updating your open stacks. It performs several steps in one:

  1. Fetches the latest changes into main.
  2. Rebases all open PRs on top of the updated main.
  3. Cleans up merged or closed branches locally.

Run:

Terminal
gt sync

This ensures that your stacked PRs align with the latest changes on the main branch, saving time and minimizing merge conflicts.

In scenarios where updates are made to the main branch, you can efficiently update your stack with Graphite CLI. For instance:

Terminal
gt checkout main
gt sync

This workflow ensures your changes integrate smoothly without manually handling rebases or branch deletions.

  • Simplified commands: Graphite CLI abstracts away complex Git workflows.
  • PR stacking: Easily manage multiple PRs as a cohesive stack.
  • Conflict resolution: Quickly address merge conflicts with gt restack.

The Graphite CLI complements and enhances traditional Git commands, making it a valuable tool for teams managing complex branch structures and collaborative workflows.

For detailed instructions on using the Graphite CLI, refer to the Graphite CLI quick start guide.

Git inspired
Graphite's CLI and VS Code extension make working with Git effortless.
Learn more

Built for the world's fastest engineering teams, now available for everyone