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

From: Henri GEIST <[email-masked]>
Date: Mon, 10 Mar 2014 19:22:13 +0100

Le lundi 10 mars 2014 à 08:31 -0700, Junio C Hamano a écrit :
> Andrew Keller <[email-masked]> writes:
> 
> > On Mar 7, 2014, at 7:50 PM, Henri GEIST wrote:
> > ...
> >> To give one of my project to someone else I have copied it on a USB key.
> >> By a simple drag and drop with the mouse.
> >> And I am quite sure I am not alone doing this way.
> >> 
> >> I have done those kind of things lot of time without any problem.
> >> But that day 'the_project' happened to be a submodule cloned by
> >> 'git submodule update' then on the USB key the $GIT_DIR of 'the_project'
> >> was missing.
> >> 
> >> If 'man git-submodule' have made me aware of the particularities of submodules
> >> clone I had write in a terminal:
> >> 
> >> git clone the_project /media/usb/the_project
> >> 
> >> Or at least I had understand what happened quicker.
> >> 
> >> I have nothing against also adding something in repository-layout but I am
> >> pretty sure normal users never read repository-layout as it is not a command
> >> they use. And it is not mentioned in most tutorials.
> >
> > How about something like this:
> >
> > "The git directory of a submodule lives inside the git directory of the parent repository instead of within the working directory."
> >
> > I'm not sure where to put it, though.
> 
> 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.

You are entirely right.
My view of the situation was biased by the fact that submodule cloning
is the only case I am aware of except when the user manually type
'--separate-git-dir' where this problem could occur.

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.