doc/bugs/Git_checkout_fails_using_--recurse-submodules.mdwn

@@ -0,0 +1,85 @@
+### Please describe the problem.
+
+Consider a parent repository with a single submodule and two branches in the parent repository. When checking out a branch in the parent using --recurse-submodules, git returns the error:
+
+fatal: could not open 'sub/.git' for writing: Is a directory
+
+This issue was originally mentioned in the post at https://git-annex.branchable.com/submodules/ where there is a statement that "The conversion of .git file to .git symlink mostly won't bother git." The original poster said there was a solution to use "git checkout mybranch && git submodule update", but this does not work with git version 2.40.0 and git-annex version 10.20230407. In this case, rather than giving a fatal error, git is unable to remove the submodule directory and leaves it untouched. However, this then leaves the new branch in a dirty state (because the submodule is an untracked or modified file). 
+
+
+### What steps will reproduce the problem?
+Here is a sequence of steps to reproduce the issue.
+
+```bash
+# create git repo to use as a submodule
+SUB_DIR=/tmp/submodule-source
+if [ -d $SUB_DIR ]; then
+    sudo rm -rf $SUB_DIR
+fi
+mkdir $SUB_DIR
+cd $SUB_DIR
+git init
+git annex init
+# add file to main
+touch sub_file1.txt
+git annex add .
+git commit -m "Add sub_file1.txt"
+
+# setup parent dataset
+PRNT_DIR=/tmp/submodules_annex
+if [ -d $PRNT_DIR ]; then
+    sudo rm -rf $PRNT_DIR
+fi
+mkdir $PRNT_DIR
+cd $PRNT_DIR
+git init
+git annex init
+# add file to main
+touch file1.txt
+git annex add .
+git commit -m "Create file1.txt"
+
+# Add branch 1 to parent dataset
+cd $PRNT_DIR
+git checkout -b branch_1 main
+# add submodule 1 to branch 1 of parent dataset
+git -c protocol.file.allow=always submodule add $SUB_DIR/.git sub
+git commit -m "Add submodule 1"
+
+# add new file to submodule annex
+cd sub
+touch sub_file2.txt
+git annex add .
+git commit -m "Create sub_file2.txt"
+
+# register changes in the parent
+cd ..
+git add .
+git commit -m "Register sub changes"
+
+# return to main branch, this fails
+git checkout main --recurse-submodules
+# return to main branch, this fails
+# git checkout main && git submodule update
+```
+
+### What version of git-annex are you using? On what operating system?
+
+git version 2.40.0
+git-annex version: 10.20230407
+operating system: darwin aarch64
+
+
+### Please provide any additional information below.
+
+[[!format sh """
+# If you can, paste a complete transcript of the problem occurring here.
+# If the problem is with the git-annex assistant, paste in .git/annex/daemon.log
+
+
+# End of transcript or log.
+"""]]
+
+### Have you had any luck using git-annex before? (Sometimes we get tired of reading bug reports all day and a lil' positive end note does wonders)
+Yes! Been familiarizing myself with it on and off over the last year and am very excited about it's possibilities.
+