[PATCH/RFC] Documentation: Say that submodule clones use a separate gitdirs.

Adding a note in the submodule documentation signaling that the
automatically cloned missing submodules are cloned with a separate
gitdir. And where it is put.

Signed-off-by: Henri GEIST <redacted>
---
 Documentation/git-submodule.txt |    5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 21cb59a..ea837fd 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt

@@ -64,6 +64,11 @@ using the 'status' subcommand and get a detailed overview of the
 difference between the index and checkouts using the 'summary'
 subcommand.
 
+*NOTE*: when submodule add or submodule update commands clone a missing
+submodule, the option --separate-git-dir is passed to the clone command
+and the gitdir of the submodule is placed outside of its working
+directory in the .git/module of the current repository.
+
 
 COMMANDS
 --------

-- 
1.7.9.3.369.gd715.dirty

On Mar 7, 2014, at 2:53 AM, Henri GEIST [off-list ref] wrote:

The modules directory is 'modules'.  And, the '.git' folder is not always called '.git' -- in a submodule, for example, the directory name is the name of the module.

Also, this file contains mostly high-level documentation, and this addition feels technical in nature.  Is there a location for more technical documentation?  Or, perhaps it can be reworded to sound less technical?

COMMANDS
--------
-- 
1.7.9.3.369.gd715.dirty


--

 - Andrew Keller

Le vendredi 07 mars 2014 à 16:42 -0500, Andrew Keller a écrit :

On Mar 7, 2014, at 2:53 AM, Henri GEIST [off-list ref] wrote:

quoted

Adding a note in the submodule documentation signaling that the
automatically cloned missing submodules are cloned with a separate
gitdir. And where it is put.

Signed-off-by: Henri GEIST <redacted>
---
Documentation/git-submodule.txt |    5 +++++
1 file changed, 5 insertions(+)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 21cb59a..ea837fd 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt

@@ -64,6 +64,11 @@ using the 'status' subcommand and get a detailed overview of the

difference between the index and checkouts using the 'summary'
subcommand.

+*NOTE*: when submodule add or submodule update commands clone a missing
+submodule, the option --separate-git-dir is passed to the clone command
+and the gitdir of the submodule is placed outside of its working
+directory in the .git/module of the current repository.
+

The modules directory is 'modules'.  And, the '.git' folder is not always called '.git' -- in a submodule, for example, the directory name is the name of the module.

Also, this file contains mostly high-level documentation, and this addition feels technical in nature.  Is there a location for more technical documentation?  Or, perhaps it can be reworded to sound less technical?

This information is technical in nature but has some importance for general users.
As this kind of clone have a separate gitdir, you will have a surprise if you
copy past the worktree as the gitdir will not come together.
I have done it and as the doc say nothing about that it take me some time to
understand what happened. And why this repository behave differently than others.

May be I can rephrase like this :

*NOTE*: when 'submodule add' or 'submodule update' commands clone a missing
submodule, the $GIT_DIR of the submodule containing the metadata is placed
outside of its working directory in the $GIT_DIR/modules of the current
repository. Those submodule can not directly be copied or move.
You need to use 'git clone'.

quoted

COMMANDS
--------
-- 
1.7.9.3.369.gd715.dirty


--

 - Andrew Keller