Re: [RFC PATCH 4/6] Include NAMESPACE COLLISIONS doc into gitrepository-layout.txt

From: Kenneth Lorber <keni@his.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: Kenneth Lorber <keni@hers.com>, git@vger.kernel.org
Subject: Re: [RFC PATCH 4/6] Include NAMESPACE COLLISIONS doc into gitrepository-layout.txt
Date: Mon, 18 May 2020 19:54:54 -0400	[thread overview]
Message-ID: <6FA1EDEE-5DB4-446D-9579-593E9EADFC0F@his.com> (raw)
In-Reply-To: <xmqqr1vi5brm.fsf@gitster.c.googlers.com>

> On May 17, 2020, at 8:26 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Kenneth Lorber <keni@hers.com> writes:
> 
>> From: Kenneth Lorber <keni@his.com>
>> 
>> Signed-off-by: Kenneth Lorber <keni@his.com>
>> ---
>> Documentation/gitrepository-layout.txt | 3 ++-
>> 1 file changed, 2 insertions(+), 1 deletion(-)
> 
> As I said elsewhere, I am not sure if we want to even let
> third-party tools direct access at the filesystem level to
> $GIT_DIR/.  We do want to say things like where the ref namespace
> that are taken as "per worktree" are located, so that a third-party
> tool wants to carve out a hierarchy out of the per-worktree part of
> the ref namespace, that may indirectly influence where on the
> filesystem under $GIT_DIR/ their stuff is stored, but how we decide
> to store refs inside $GIT_DIR/ should still be blackbox to these
> third-party tools (e.g. we may not be using loose or packed refs,
> but using a chain of reftable files).  

Probably true in the abstract, but the current situation is an undefined mix.  Changing it is almost certainly more work than it's worth (my little game with COMMIT_EDITMSG notwithstanding), but documenting some safe places for end users seems reasonable to me.

> 
> So from that point of view, we shouldn't have to touch the
> repository layout document, I would think.

Where the information goes is certainly up for debate - that's why I put it in its own file.
Any suggestions for a better place?

(It looks like I may not have backed up far enough when I cut this diff.  I'll fix that for v2.)

> 
>> diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
>> index a84a4df513..8050e8cc1f 100644
>> --- a/Documentation/gitrepository-layout.txt
>> +++ b/Documentation/gitrepository-layout.txt
>> @@ -290,9 +290,10 @@ worktrees/<id>/locked::
>> worktrees/<id>/config.worktree::
>> 	Working directory specific configuration file.
>> 
>> -include::technical/namespace-collisions.txt[]
>> include::technical/repository-version.txt[]
>> 
>> +include::technical/namespace-collisions.txt[]
>> +
>> SEE ALSO
>> --------
>> linkgit:git-init[1],