Always get checkout error with submodule on GitHub Desktop on Windows

Question

I have a repo with a few branches. On one of them I deleted a directory, which does not really belong to the repo and added it back as a git submodule.

That's what I do:

1. Clone the repo
2. Switch to the branch with the submodule in GitHub Desktop
3. git submodule init
4. Until now I can switch the branches (between the ones with the submodule and no submodule without any issues).
5. git submodule update to finally get the "content" of the submodule

So everything is right until I try to switch the branch in GitHub Desktop (to another branch without any git submodules). If I do so I get a checkout error claiming I have uncommitted changes:

Failed to checkout the branch

The following files in your working directory would be overwritten by a checkout: [...] Please commit your changes before you can switch branches.

However as I said I did not changed anything - the only thing I did was updating my submodules.

git status shows everything is all right:

$ git status
On branch patch-submodule
Your branch is up-to-date with 'origin/patch-submodule'.

nothing to commit, working directory clean

When I deinit my submodules I can also switch the branches again.

So what's wrong here? And how can I prevent this error or get around it?

Answer 1

Thanks to the GitHub support I finally got a very useful reply.

Especially they directed me to Replaced third party code with git submodules, now I can't switch branches which exactly describes my issue - except of one difference: I did used the GitHub GUI and not the console.

And there is linked to git-scm where this is explained very nicely:

Switching branches with submodules in them can also be tricky. If you create a new branch, add a submodule there, and then switch back to a branch without that submodule, you still have the submodule directory as an untracked directory[.]

[...] You have to either move it out of the way or remove it, in which case you have to clone it again when you switch back—and you may lose local changes or branches that you didn’t push up.

This basically is all what this error messages meant in my case.

Answer 2

You mentioned that you removed a directory from the repo and instead made it a git submodule.

Was this directory removed from the brach you attempting to check out?

What's likely happening is that the submodule contains one of the same files as is contained in the branch you are attempting to check out.

You update the submodule, which places the file(s) on your file system. When you attempt to checkout the branch, git tries to overwrite that submodule version of the file with the version that is still contained in the main repo on that particular branch. This could/would result in lost work, so git throws the error.

Make a clean checkout of that branch, then remove the files and commit the changes. Possibly add or merge the submodule changes to that branch as well.