Bad advice on switching between branches with submodules and directories

[cederlys]

The "Git Submodules" chapter talks ends with a discussion about how to switch from a subdirectory to a submodule. Unfortunately, I think it gives some very bad advice. It tells me to use "git checkout -f" to switch to the subdirectory branch, but that has several issues:

• it doesn't check for local modifications (as mentioned in the book)
• it doesn't remove files, so if more files are added in the submodule, those files will still be present in the working tree.
• as a special case of the above point, it doesn't remove the ".git" file. As a result, running "git log" in the subdirectory that used to be a submodule will show the history of the submodule, not the superproject!

A much better approach is to run:

git submodule deinit --all
git checkout master

This will properly remove all the files of the submodule and then check out the subdirectory.

I'm attaching a commented shellscript that demonstrates these issues and shows that the deinit method works better. submodule-conversion.txt

[ben]

I'd love to review a PR that makes that section better.

[cederlys]

Careful. I assembled the man pages of CVS, wrote a few introductory chapters, and called the result the CVS manual. A few years later, everybody called it "the Cederqvist". Are you really sure you want me to contribute any material to the Pro Git book? I would be happy to review any proposed change you make, however.