Switch Branch (git switch)

Why Switch Branch?

• Work on a different feature: Move from one feature branch to another without creating a new repository or workspace.
• Fix a bug: Switch to a bug-fix branch to address an issue separately from your current work.
• Review someone else’s changes: Switch to another branch to inspect or test its implementation.
• Compare different versions: Move between branches to see how the code differs or behaves.
• Return to a stable branch: Switch back to main/master to build, test, or release the stable version.

What Does it Mean to Switch Branch?

Switching branch is easy and straightforward:

git switch <branch-name>

Switching branch means to go to another branch. Yes as simple as that. But what makes it interesting is knowing what happens under the hood when you switch the branch.

Under the Hood

Under the hood:

• HEAD now points to switched branch
• Git updates the content (files) in working directory to match the state of that branch if branches are diverged
• In case of uncommitted changes, Git also checks if those changes can be applied to the target branch
  • If branches are not diverged, Git keeps the changes
  • If branches are diverged, Git aborts switching branch

The third point is important. See Handling Uncommitted Changes to deep dive.

Handling Uncommitted Changes

Before Divergence

Suppose both your master and feat branch are currently pointing to the same commit C which means they have not diverged yet.

    flowchart RL
    subgraph commits
    A
    B
    C
    C --> B
    B --> A
    end
    master --> C
    feat --> C
  

And the content of file in commit C is:

HELLO

Now, you switch to feat branch and modify the content to be “HOLA” but not yet committed.

git switch feat
echo "HOLA" > file

Guess what happens when you switch branch to master?

According to rule(2), git updates only when branches are diverged. But master and feat aren’t diverged yet. The content remains “HOLA”. This is proof:

git switch master
cat file

file has:

HOLA

After Divergence

Committed Changes

But if you commit before switching to master:

git switch feat
echo "HOLA" > file
git commit -m 'file updated'

Guess what happens when you switch branch to master?

Now the brances are diverged. You can see it.

    flowchart RL
    subgraph commits
    A
    B
    C
    D
    D --> C
    C --> B
    B --> A
    end
    master --> C
    feat --> D
  

master still points to the commit C but feat has move forward the above commit D. Which means, According to rule(2), git updates contents in working tree when branches are diverged. The content of file will now be updated to “HELLO” which is what commit C has:

git switch master
cat file

file has:

HELLO

Uncommitted Changes

After this divergence, you again modify the content of file in feat branch to say “HI” but left it uncommitted.

git switch feat
echo "HI" > file

Now if you try to switch to master:

git switch master

Git complains and aborts:

error: Your local changes to the following files would be overwritten by checkout:
        file
Please commit your changes or stash them before you switch branches.
Aborting

Git aborts because if it hadn’t you would have loose your changes. Hence, Git askes you to either commit or stash. What should you do depends:

If you are done with changes, commit it else stash. You can also discard the changes if you don’t need.

Stash if you need later

git stash
git switch master

After switching, you can retrieve stashed changes using:

git stash pop

Commit if you are done

You can commit and switch branch if you are done with your work.

git add .
git commit -m 'msg'
git switch master

Discard if you don’t need

If you don’t need the changes, discard the changes and switch branch.

git restore --worktree --staged .
git switch master