Submodules are now supported by git-annex!

Seems to work, but still experimental until it's been tested more.

When repositories are on filesystems not supporting symlinks, the .git dir
symlink trick cannot be used. Since we're going to be in direct mode
anyway, the .git dir symlink is not strictly needed.

However, I have not fixed the code that creates new annex symlinks to
handle this case -- the committed symlinks will be wrong.

git annex sync happens to currently fail in a submodule using direct mode,
because there's no HEAD ref. That also needs to be dealt with to get
this fully working in crippled filesystems.

Leaving http://github.com/datalad/datalad/issues/44 open until these issues
are dealt with.

1 files changed, 21 insertions, 0 deletions

diff --git a/doc/submodules.mdwn b/doc/submodules.mdwn
new file mode 100644
index 000000000..fe5fc9a9e
--- /dev/null
+++ b/doc/submodules.mdwn
@@ -0,0 +1,21 @@
+[Git submodules](http://git-scm.com/book/en/v2/Git-Tools-Submodules) are
+supported by git-annex since version 5.20150303.
+
+Git normally makes a `.git` **file** in a
+submodule, that points to the real git repository under `.git/modules/`.
+This presents problems for git-annex. So, when used in a submodule,
+git-annex will automatically replace the `.git` file with a symlink
+pointing at the git repository.
+
+With that taken care of, git-annex should work ok in submodules. Although
+this is a new and somewhat experimental feature.
+
+The conversion of .git file to .git symlink mostly won't bother git.
+
+Known problems:
+
+* If you want to delete a whole submodule, `git rm submodule`
+  will refuse to delete it, complaining that the
+  submodule "uses a .git directory". Workaround: Use `rm -rf`
+  to delete the tree, and then `git commit`.
+* This won't work on filesystems not supporting symlinks.