Fwd: Re: [git-users] List of ignore configuration file

Fwd: Re: [git-users] List of ignore configuration file

[Konstantin Khomoutov]

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@gmail.com -----

Date: Wed, 23 Jan 2019 10:15:59 -0800 (PST)
From: cl.robitaille@gmail.com
To: Git for human beings <git-users@googlegroups.com>
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