diff --git a/doc/bugs/Git_checkout_fails_using_--recurse-submodules/comment_1_571703fc4e1e2f4e34f54db7a7da7080._comment b/doc/bugs/Git_checkout_fails_using_--recurse-submodules/comment_1_571703fc4e1e2f4e34f54db7a7da7080._comment
new file mode 100644
index 0000000000..e0061a2411
--- /dev/null
+++ b/doc/bugs/Git_checkout_fails_using_--recurse-submodules/comment_1_571703fc4e1e2f4e34f54db7a7da7080._comment
@@ -0,0 +1,31 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 1"""
+ date="2023-04-20T17:51:01Z"
+ content="""
+Notice that your script is doing something a bit unusual. You check out a
+branch, add the submodule in that branch, and then check out the original
+branch, which is before the submodule was added.
+
+So, git needs to delete the submodule. Deleting the submodule is
+mentioned in [[submodules]] as a particular case where git-annex's hack to
+support submodules does not work very well.
+
+If that's all this bug is about, its description is over-broad. 
+It doesn't seem to prevent using submodules with git-annex in situations
+where you are not deleting a submodule, but are updating submodules
+
+Yes, `git checkout main --recurse-submodules` will fail in those
+situations, but the workaround in [this comment](https://git-annex.branchable.com/submodules/#comment-0d7c31e3f08e803bf9b13ab0568fedcc)
+of using `git checkout main && git submodule update` will work.
+
+And yes, I've verified that does still work, with git 2.40.0.
+I modified the test case to add the submodule before checking out
+the branch, then add `sub_file2.txt`, and commit that to the branch.
+At that point,  `git checkout main && git submodule update` worked fine.
+
+So, nothing changed in git, and git-annex's approach for submodules does
+broadly work, except git has issues deleting submodules that have a .git
+directory in them. The solution is to `rm -rf` the submodule after
+running `git checkout`.
+"""]]
diff --git a/doc/bugs/Git_checkout_fails_using_--recurse-submodules/comment_2_9fe6b56ffda6d0c77ce65786514cd79d._comment b/doc/bugs/Git_checkout_fails_using_--recurse-submodules/comment_2_9fe6b56ffda6d0c77ce65786514cd79d._comment
new file mode 100644
index 0000000000..03e893759c
--- /dev/null
+++ b/doc/bugs/Git_checkout_fails_using_--recurse-submodules/comment_2_9fe6b56ffda6d0c77ce65786514cd79d._comment
@@ -0,0 +1,20 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 2"""
+ date="2023-04-20T18:04:56Z"
+ content="""
+I don't think it's possible to improve git-annex's behavior here much.
+
+git-annex could avoid converting .git file to a directory, but then the
+git-annex symlinks would point to the wrong place. It could, when in a
+submodule, make the git-annex symlinks point up to ../.git/modules/sub/,
+but then the links would not work when the submodule was cloned by itself,
+or when the submodule was located at a different directory level.
+
+The only other thing git-annex can do is avoid using symlinks at all,
+eg adjusted unlocked branches. I don't think it's a good trafeoff to do
+that. On the one hand, there is this minor issue with submodule deletion,
+and the need to avoid using `--recurse-submodules` and instead do `git
+submodule update`. On the other hand, unlocked annexed files use 2x
+as much disk space.
+"""]]
diff --git a/doc/submodules/comment_5_9ccb133a957498724188a8749359a422._comment b/doc/submodules/comment_5_9ccb133a957498724188a8749359a422._comment
new file mode 100644
index 0000000000..3f16afb082
--- /dev/null
+++ b/doc/submodules/comment_5_9ccb133a957498724188a8749359a422._comment
@@ -0,0 +1,21 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 5"""
+ date="2023-04-20T16:45:38Z"
+ content="""
+The above issue is being discussed at
+[[bugs/Git_checkout_fails_using_--recurse-submodules]].
+
+DavidD's comment #2 is misleading, `git submodule update` does work fine when
+you've checkout out a branch and want to update an existing submodule.
+
+When `git submodule update` does not work 100% is the case where you checked out
+a branch, added a submodule in that branch, and then checked out another
+branch that does not contain the submodule. What happens then is:
+
+	warning: unable to rmdir 'sub': Directory not empty
+
+And the solution is to `rm -rf sub` manually. This is essentially the same
+problem discussed above on this page where it talks about deleting a whole
+submodule.
+"""]]