This answer is an attempt to explain why Git behaves the way it does. It is not a recommendation to engage in any particular workflows. (My own preference is to just commit anyway, avoiding
git stash and not trying to be too tricky, but others like other methods.)
The observation here is that, after you start working in
branch1 (forgetting or not realizing that it would be good to switch to a different branch
branch2 first), you run:
git checkout branch2
Sometimes Git says “OK, you’re on branch2 now!” Sometimes, Git says “I can’t do that, I’d lose some of your changes.”
If Git won’t let you do it, you have to commit your changes, to save them somewhere permanent. You may want to use
git stash to save them; this is one of the things it’s designed for. Note that
git stash save or
git stash push actually means “Commit all the changes, but on no branch at all, then remove them from where I am now.” That makes it possible to switch: you now have no in-progress changes. You can then
git stash apply them after switching.
git stash saveis the old syntax;
git stash pushwas introduced in Git version 2.13, to fix up some problems with the arguments to
git stashand allow for new options. Both do the same thing, when used in the basic ways.
You can stop reading here, if you like!
If Git won’t let you switch, you already have a remedy: use
git stash or
git commit; or, if your changes are trivial to re-create, use
git checkout -f to force it. This answer is all about when Git will let you
git checkout branch2 even though you started making some changes. Why does it work sometimes, and not other times?
The rule here is simple in one way, and complicated/hard-to-explain in another:
You may switch branches with uncommitted changes in the work-tree if and only if said switching does not require clobbering those changes.
That is—and please note that this is still simplified; there are some extra-difficult corner cases with staged
git rms and such—suppose you are on
git checkout branch2 would have to do this:
- For every file that is in
branch1and not in
branch2,1 remove that file.
- For every file that is in
branch2and not in
branch1, create that file (with appropriate contents).
- For every file that is in both branches, if the version in
branch2is different, update the working tree version.
Each of these steps could clobber something in your work-tree:
- Removing a file is “safe” if the version in the work-tree is the same as the committed version in
branch1; it’s “unsafe” if you’ve made changes.
- Creating a file the way it appears in
branch2is “safe” if it does not exist now.2 It’s “unsafe” if it does exist now but has the “wrong” contents.
- And of course, replacing the work-tree version of a file with a different version is “safe” if the work-tree version is already committed to
Creating a new branch (
git checkout -b newbranch) is always considered “safe”: no files will be added, removed, or altered in the work-tree as part of this process, and the index/staging-area is also untouched. (Caveat: it’s safe when creating a new branch without changing the new branch’s starting-point; but if you add another argument, e.g.,
git checkout -b newbranch different-start-point, this might have to change things, to move to
different-start-point. Git will then apply the checkout safety rules as usual.)
1This requires that we define what it means for a file to be in a branch, which in turn requires defining the word branch properly. (See also What exactly do we mean by “branch”?) Here, what I really mean is the commit to which the branch-name resolves: a file whose path is
P is in
git rev-parse branch1:P produces a hash. That file is not in
branch1 if you get an error message instead. The existence of path
P in your index or work-tree is not relevant when answering this particular question. Thus, the secret here is to examine the result of
git rev-parse on each
branch-name:path. This either fails because the file is “in” at most one branch, or gives us two hash IDs. If the two hash IDs are the same, the file is the same in both branches. No changing is required. If the hash IDs differ, the file is different in the two branches, and must be changed to switch branches.
The key notion here is that files in commits are frozen forever. Files you will edit are obviously not frozen. We are, at least initially, looking only at the mismatches between two frozen commits. Unfortunately, we—or Git—also have to deal with files that aren’t in the commit you’re going to switch away from and are in the commit you’re going to switch to. This leads to the remaining complications, since files can also exist in the index and/or in the work-tree, without having to exist these two particular frozen commits we’re working with.
2It might be considered “sort-of-safe” if it already exists with the “right contents”, so that Git does not have to create it after all. I recall at least some versions of Git allowing this, but testing just now shows it to be considered “unsafe” in Git 22.214.171.124. The same argument would apply to a modified file that happens to be modified to match the to-be-switch-to branch. Again, 126.96.36.199 just says “would be overwritten”, though. See the end of the technical notes as well: my memory may be faulty as I don’t think the read-tree rules have changed since I first started using Git at version 1.5.something.
Does it matter whether the changes are staged or unstaged?
Yes, in some ways. In particular, you can stage a change, then “de-modify” the work tree file. Here’s a file in two branches, that’s different in
$ git show branch1:inboth this file is in both branches $ git show branch2:inboth this file is in both branches but it has more stuff in branch2 now $ git checkout branch1 Switched to branch 'branch1' $ echo 'but it has more stuff in branch2 now' >> inboth
At this point, the working tree file
inboth matches the one in
branch2, even though we’re on
branch1. This change is not staged for commit, which is what
git status --short shows here:
$ git status --short M inboth
The space-then-M means “modified but not staged” (or more precisely, working-tree copy differs from staged/index copy).
$ git checkout branch2 error: Your local changes ...
OK, now let’s stage the working-tree copy, which we already know also matches the copy in
$ git add inboth $ git status --short M inboth $ git checkout branch2 Switched to branch 'branch2'
Here the staged-and-working copies both matched what was in
branch2, so the checkout was allowed.
Let’s try another step:
$ git checkout branch1 Switched to branch 'branch1' $ cat inboth this file is in both branches
The change I made is lost from the staging area now (because checkout writes through the staging area). This is a bit of a corner case. The change is not gone, but the fact that I had staged it, is gone.
Let’s stage a third variant of the file, different from either branch-copy, then set the working copy to match the current branch version:
$ echo 'staged version different from all' > inboth $ git add inboth $ git show branch1:inboth > inboth $ git status --short MM inboth
Ms here mean: staged file differs from
HEAD file, and, working-tree file differs from staged file. The working-tree version does match the
$ git diff HEAD $
git checkout won’t allow the checkout:
$ git checkout branch2 error: Your local changes ...
Let’s set the
branch2 version as the working version:
$ git show branch2:inboth > inboth $ git status --short MM inboth $ git diff HEAD diff --git a/inboth b/inboth index ecb07f7..aee20fb 100644 --- a/inboth +++ b/inboth @@ -1 +1,2 @@ this file is in both branches +but it has more stuff in branch2 now $ git diff branch2 -- inboth $ git checkout branch2 error: Your local changes ...
Even though the current working copy matches the one in
branch2, the staged file does not, so a
git checkout would lose that copy, and the
git checkout is rejected.
Technical notes—only for the insanely curious 🙂
The underlying implementation mechanism for all of this is Git’s index. The index, also called the “staging area”, is where you build the next commit: it starts out matching the current commit, i.e., whatever you have checked-out now, and then each time you
git add a file, you replace the index version with whatever you have in your work-tree.
Remember, the work-tree is where you work on your files. Here, they have their normal form, rather than some special only-useful-to-Git form like they do in commits and in the index. So you extract a file from a commit, through the index, and then on into the work-tree. After changing it, you
git add it to the index. So there are in fact three places for each file: the current commit, the index, and the work-tree.
When you run
git checkout branch2, what Git does underneath the covers is to compare the tip commit of
branch2 to whatever is in both the current commit and the index now. Any file that matches what’s there now, Git can leave alone. It’s all untouched. Any file that’s the same in both commits, Git can also leave alone—and these are the ones that let you switch branches.
Much of Git, including commit-switching, is relatively fast because of this index. What’s actually in the index is not each file itself, but rather each file’s hash. The copy of the file itself is stored as what Git calls a blob object, in the repository. This is similar to how the files are stored in commits as well: commits don’t actually contain the files, they just lead Git to the hash ID of each file. So Git can compare hash IDs—currently 160-bit-long strings—to decide if commits X and Y have the same file or not. It can then compare those hash IDs to the hash ID in the index, too.
This is what leads to all the oddball corner cases above. We have commits X and Y that both have file
path/to/name.txt, and we have an index entry for
path/to/name.txt. Maybe all three hashes match. Maybe two of them match and one doesn’t. Maybe all three are different. And, we might also have
another/file.txt that’s only in X or only in Y and is or is not in the index now. Each of these various cases requires its own separate consideration: does Git need to copy the file out from commit to index, or remove it from index, to switch from X to Y? If so, it also has to copy the file to the work-tree, or remove it from the work-tree. And if that‘s the case, the index and work-tree versions had better match at least one of the committed versions; otherwise Git will be clobbering some data.
(The complete rules for all of this are described in, not the
git checkout documentation as you might expect, but rather the
git read-tree documentation, under the section titled “Two Tree Merge”.)