Your history looks something like this:
---X A
\
Y B
git ls-tree A shows (e.g.):
040000 tree 48770cdc854cc14fecc71029180be7a979f4baa1 S
100644 blob beac6e189b7c69b249271b52cd2db5e418c05a50 file
git ls-tree A:S shows (e.g.):
100644 blob 6357df9903460c9e8b43311aff3c7a6fd7fe6aa1 somefile
git ls-tree B shows (e.g.):
100644 blob 1f8556335163a2bcbcc366a17d08d1f8e0540e6f .gitmodules
160000 commit 234871cd6f0c1f9109e483383d7712dd8a1986e5 S
100644 blob beac6e189b7c69b249271b52cd2db5e418c05a50 file
(cd S; git ls-tree HEAD) shows (e.g.):
100644 blob abccc3958be33be4b93f56efae1b60820545aad2 somefile
You want to move from commit Y (or later) to commit X (or earlier) or vice versa.
If your active branch is B, then git checkout A says (e.g.):
error: The following untracked working tree files would be overwritten by checkout:
S/somefile
Please move or remove them before you can switch branches.
Aborting
Git tries very hard to never lose data unless you tell it to do so (e.g. with “force” options). The problem Git finds and reports here is that branch A has different content for S/somefile then the working tree. Because S/somefile is not tracked (from the perspective of the superproject), Git refuses to replace the file and thus refuses to switch branches/commits.
Git could arguably be smarter about this (by noticing that the file is tracked in the submodule, so it should not really be considered untracked when switching branches in the superproject), but it is a limitation of the current implementation. There is a Google Summer of Code 2011 project for Git that aims to address some areas of submodule support, but it is not clear to me whether this exact problem will be covered.
You could, as you suggest, rewrite your history so that S always appeared to have been a submodule. This would certainly present the smoothest surface for future commit switches, but it is complicated by the fact that you would need to make sure you have commits in the submodule’s origin repository that reflect each historical state of the S directory in the original commits. If you have many different S trees (i.e. you had made some local changes under S before converting it to a submodule), then this may be a complicated process/script.
A simpler workaround might be to temporarily checkout an “empty branch” in the submodule before switching to a commit that has it as a directory.
Create the “empty branch” in the submodule.
git checkout --orphan empty
git rm -r --cached .
git commit --allow-empty -mempty
You could publish this “branch” in the submodule’s origin repository so that no one else would need to recreate it form themselves.
When you need to switch from a commit where S is a submodule to a commit where S is a directory, checkout the “empty branch” in the submodule first:
(cd S && git checkout empty)
git checkout A
You will see this warning because Git will leave behind S/.git:
warning: unable to rmdir S: Directory not empty
Because S/.git is still present, you should be careful to issue Git commands only outside S when working on a commit that has S as a directory; Git commands issued under S would operate on the S/.git (in this state, it is just a “subrepository”, not a full submodule) instead of the top level .git repository.
When you need to switch from a commit where S is a directory to a commit where S is a submodule, you will need to check out the appropriate branch/commit in the submodule after switching the superproject’s commit.
You can use git submodule update to restore the commit that is recorded in the superproject. Or, if you were working on a branch in the submodule, just check it back out.
git checkout B
# THEN
git submodule update
# OR checkout a specific branch
(cd S && git checkout master)
# OR checkout previous branch
(cd S && git checkout -)
