Re: [PATCH] documentation symlink restrictions for .git* files

From: Philip Oakley <philipoakley@iee.email>
Date: Oct 27, 2020, 21:00 UTC
Message-ID: <21e4bac1-b3ef-e28f-586d-fe17baf6b15e@iee.email>
In-Reply-To: <xmqqk0vbcxtb.fsf@gitster.c.googlers.com>

On 27/10/2020 18:45, Junio C Hamano wrote:

Show 22 quoted lines

> Jeff King <peff@peff.net> writes:
>
>>>  DESCRIPTION
>>>  -----------
>>>  
>>> -A `gitattributes` file is a simple text file that gives
>>> -`attributes` to pathnames.
>>> +A `gitattributes` file is a simple text file (it cannot be a
>>> +symbolic link to anything) that gives `attributes` to pathnames.
>> I worried that even a short mention like this would be distracting. Not
>> because it's so long, but because it's right there in the very first
>> sentence, and I really think this is a corner case that most people
>> would not even think about.
>>
>> So it is helpful if you are looking for info on symlinks and these
>> files, but probably clutter if you are looking for something else.
>>
>> I have to admit I don't feel all that strongly either way, though.
> I don't, either, and as I said, I found that the placement of new
> text was OK.
>
>

I do think that the extra text above is the right thing to do.

We should be informing readers early about things that are expressly prohibited.

Leaving just the note till nearly the end of the rather long attributes/ignore man pages makes it very hard to discover for frustrated users, which would accidentally reinforce the idea of the docs being poor (rather than being focussed).

Philip