A user over there at the git-users ML is having troubles with the
wording of the `git check-ignore` manual page which, in their opinion,
fails to clearly communicate the twist about tracked files being not
eligible for ignored/non-ignored checks:
----- Forwarded message from cl.robitaille@xxxxxxxxx -----
Date: Wed, 23 Jan 2019 10:15:59 -0800 (PST)
From: cl.robitaille@xxxxxxxxx
To: Git for human beings <git-users@xxxxxxxxxxxxxxxx>
Subject: Re: [git-users] List of ignore configuration file
Well, the first point to mention is that anyone writing help, man page and
information must not forget that the vast majority of readers are reading
such information because they do not know..... This is obvious but the main
point is to not take for granted that they have a deep knowledge,
particularly when a concept is a bit "strange"...
Now, I understand that git is, normally, for developers, which are
typically more knowledgeable, but still....
And I agree it helps to have real user inputs, so I will provide many. I do
not expect all be accepted but this is Ok.
So, here it is
1 - Ideally, the man page should be following "the standard" format. I am
not sure if one exists but since the vast majority of the man pages are
using the same layout I presume that there is some form of soft standard.
Here, obviously, my point is about listing all of the files and their
location at the end of the page (which does not preclude to mention then
elsewhere in the text if desire).
2 - For the git-check-ignore. here are my suggestions
DESCRIPTION
For each pathname given via the command-line or from a file via
--stdin, check whether the file* / directory* is excluded by .gitignore
(or other input files to the
exclude mechanism) and output the path if it is excluded.
By default, tracked files * and directories *are not shown at all
since they are not subject to exclude rules; but see ‘--no-index’. *In the
case of a directory, any *
* tracked file or directory below it will cause the directory not to
be shown.*
3 - Again in git-check-ignore.
Actually, here, I think the description of --no-index is wrong. At least in
my case, which was that a directory WAS ignored by git add because a file
under it was already tracked. The man page description is only talking
about the opposite case where git add is not ignoring the pathname. I
wanted to provide a suggestion here but I fail to understand the use case
described by the man page. In fact, I am not even sure it is correct. git
add appears to honor the ignore instructions despite having already tracked
objects. May be the use case is when the pathname is BELOW something
already tracked??
4 - git check-ignore should be augmented to have an option of simply
listing all of the ignore files, may be even allowing to dump their
content. The latter may be too much....
On Tuesday, January 22, 2019 at 5:37:11 PM UTC-5, Philip Oakley wrote:
> On 22/01/2019 22:35, Philip Oakley wrote:
>
> Extra points for you will be on order if you can suggest some better
> wording for manual pages to help others patch that misunderstanding.
> The same would apply to a contribution for the git-scm 'book'.
>
> It is a help to the devs to have some real user input...
>> On 22/01/2019 21:20, Claude Robitaille wrote:
>> Thanks this help.
>>
>> I did read the man page, but I am used at seeing the files and
>> locations at the end of the man page the section FILES. My bad to
>> skiping right to the end of the man page. See dnsmasq as an example.
>>
>> Yes TL;DR..... :-( I skip too quickly on --no-index. But now I
>> understand that it makes check-ignore to "mimic" add.... (even if
>> mimic was not the intent)
>>
>> But, the description is talking about file and tracked files. It is
>> not obvious for an occasional user to correlate that with "my dir is
>> not checked because something under it is indeed tracked" . Bomttom
>> line, what I am saying is that dir and file are slightly different in
>> the context here and yes my mental model was wrong.
[...]
----- End forwarded message -----
The whole thread is archived at [1].
1. https://groups.google.com/d/topic/git-users/GPBJxQWeHuA/discussion
