Introduction

This Git error appears when one checkout command is trying to do two different jobs at once: switch branches and restore specific paths. Git treats those as separate operations, so when the command line is ambiguous or contradictory, it stops with "Cannot update paths and switch to branch at the same time."

Why Git Refuses the Command

Historically, git checkout overloaded multiple behaviors:

• switch to another branch
• restore files from another commit or branch
• detach HEAD

That flexibility is powerful, but it also means Git has to guess your intent from the argument structure. When the arguments look like both a branch switch and a path update, Git refuses instead of risking the wrong operation.

For example, a command like this is invalid:

git checkout feature-branch -- README.md

Git reads feature-branch as a tree-ish source for the file checkout, not as a branch switch you also want to perform. You cannot combine "switch me to this branch" and "update this specific path" in one step.

Do the Two Actions Separately

If you want to switch branches, do only that:

git switch feature-branch

If you want to restore a file from another branch or commit, do only that:

git restore --source feature-branch README.md

Or, using the older checkout syntax just for the file operation:

git checkout feature-branch -- README.md

The fix is usually not a special flag. It is simply splitting the intent into two commands.

Prefer git switch and git restore

Modern Git introduced git switch and git restore specifically to make this less confusing.

Use:

• 'git switch for branch movement'
• 'git restore for file content restoration'

That separation maps directly onto the error message and makes command intent much clearer during code review or incident recovery.

A Typical Workflow Example

Suppose you are on main, you want to move to feature-x, and you also want one file from release.

Do it like this:

git switch feature-x
git restore --source release path/to/config.yml

Git is happy because each command now does exactly one category of work.

What If Uncommitted Changes Are Involved?

Sometimes this error appears in a workflow that also has uncommitted changes in the working tree. Those are a separate issue. Even after fixing the command form, Git may still prevent the branch switch if your local modifications would be overwritten.

In that case, either commit, stash, or discard the changes before switching branches.

git stash push -m "temp before branch switch"
git switch feature-branch

Do not confuse the two problems:

• ambiguous command structure
• unsafe working-tree state

They can happen together, but they are different Git complaints.

Common Pitfalls

The biggest pitfall is treating git checkout as one universal command and forgetting that branch switching and file restoration are logically separate actions.

Another issue is assuming the branch name in git checkout branch -- file means "switch to branch." In that form, the branch name is only the source tree for the path update.

Developers also sometimes debug the wrong thing by focusing on local changes when the immediate problem is just command ambiguity.

Finally, if you are teaching or scripting Git workflows today, prefer git switch and git restore. They reduce this entire category of confusion.

Summary

• This error means one command is trying to switch branches and update paths at the same time.
• Split the operation into two commands instead of searching for a magic combined form.
• Use git switch for branches and git restore for file content.
• Remember that uncommitted-change conflicts are a separate issue from command ambiguity.
• Modern Git commands are clearer than overloading git checkout for everything.