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

Henri GEIST [off-list ref] writes:

Le lundi 10 mars 2014 à 08:31 -0700, Junio C Hamano a écrit :
...

quoted

This is not limited to submodules.  There are multiple lower-level
mechanisms for a $path/.git to borrow the repository data from
elsewhere outside of $path and a cloned submodule uses only one of
them.  For any such $path, "cp -R $path $otherplace" will result in
an "$otherplace" that does not work as a Git repository in exactly
the same way, whether it happens to be a submodule checkout or not.

That is why I suggested to enhance description on a more general
part of the documentation that covers what a Git repository is.

...
If there is some other situation where this can occur as a side effect
of a git command it can be good to have the user aware of the list or
at least inform them in general case a git repository cannot be copied
in a place every body will see.
Or place a note in the manpage of every git command which can have this
side effect.

I think we should do two things:

 - In the repository format document, state that there are two
   lower-level mechanisms and a half that lets a repository borrow
   from somewhere else, and "cp -R" of the former will not result in
   a complete, usable repository, and who employs these mechanisms.

   * Redirecting the entire .git via the textual gitfile mechanism,
     which is used by "clone --separate-git-dir" and "submodule";

   * Borrowing .git/objects read-only from elsewhere, overlaying our
     own, via .git/objects/info/alternates, which is used by "clone
     --reference";

   * Redirecting some paths in .git to another, via "git workdir";
     soon to be replaced with .git/commondir mechansim.

 - In each of the documentation page on an end-user facing command
   that will be mentioned above, add "See also" reference to the
   above description in the repository format document.

   We could elaborate the "See also" as something like "If you use
   this feature, do not think you can "cp -R" the repository to
   elsewhere and expect the copy to function; see also ...", if we
   wanted to.