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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 10, 2014, 15:31 UTC
Message-ID: <xmqq61nmrrxe.fsf@gitster.dls.corp.google.com>
In-Reply-To: <B2A4F350-1F20-4ABA-80A6-CF244DD7FAFD@kellerfarm.com>

Andrew Keller <andrew@kellerfarm.com> writes:

Show 27 quoted lines

> 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.