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

[Junio C Hamano <gitster@pobox.com>]

Henri GEIST <geist.henri@laposte.net> writes:

> Le lundi 10 mars 2014 à 08:31 -0700, Junio C Hamano a écrit :
> ...
>> 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.