From: Philip Oakley <philipoakley@iee.org>
Date: Tue, 04 Jun 2019 12:34:25 GMT
Subject: Re: [PATCH] make slash-rules more readable
Message-ID: <0c9f79f3-b43b-5f32-d217-ff92531c5da7@iee.org>
In-Reply-To: <20190531074426.6810-1-admin@in-ici.net>

Hi Adam,
On 31/05/2019 08:44, Dr. Adam Nielsen wrote:
> gitignore.txt: make slash-rules more readable
>
> Remove meta-rule in a paragraph for trailing-slash.
> Be precise whenever a trailing slash would make a
> difference. Improve paragraph for pattern without slash.
> Remove rule for leading slash because its now redundant.
> Instead, add examples for leading slash and asterix in
> example section.
>
> Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>
I think the rules end up being difficult because we describe them from a 
coders implementation viewpoint, rather than a users descriptive 
viewpoint. Thus we avoided things like the difficult to code slashes in 
the front/middle, and we get caught on the equivalent of neither/nor 
phrases, which can even be difficult for native English speakers.

Later on there is a recursively/respectively issue (latter not 
explicitly mentioned).  There is also an "Except if" not-a-proper 
sentence. (mentioned off-line)

I think this is the truth table for the slash..
Lead/  | mid/  | end/  |
yes    |yes    |yes    | Directory, directly at .gitignore
no     |yes    |yes    | Directory, directly at .gitignore
yes    |no     |yes    | Directory, directly at .gitignore
no     |no     |yes    | Directory, anywhere at, or below, .gitignore   
<the tricky one ;-)

yes    |yes    |no     | file or Directory, directly at .gitignore
no     |yes    |no     | file or Directory, directly at .gitignore
yes    |no     |no     | file or Directory, directly at .gitignore
no     |no     |no     | file or Directory, anywhere at, or below, 
.gitignore

After sleeping on it, I came up with:

    The slash '/' is used as the directory separator. Separators may
    occur at the beginning, middle or end of the .gitignore search pattern.

    If there is a separator at the beginning or middle (or both) of the
    pattern, then the pattern is relative to the directory level of the
    particular .gitignore file itself. Otherwise the pattern may also
    match at any level below the .gitignore level.

    If there is a separator at the end of the pattern then the pattern
    will only match directories, otherwise the pattern can match both
    files and directories.

    Examples text..

    The special '*' ...

    The special '**' ...

-- 
The key (for me) was to add in the sentence that says we have 
beginning/middle/end slashes as a prompt ready for later, and use the 
plural for 'separator'.

I then also used 'otherwise' and an occasional 'also'  to avoid any 
and/or/neither/nor logic problems. I removed all 'it/they/them' style 
indirect references as it is easy to pick the wrong indirection.

I have been explicit (pedantic) about '.gitignore search pattern' to 
avoid the reader accidentally changing focus and thinking of the path 
string.

One could also add "Likewise the directory(?) pattern will not match a 
symbolic link, as is normal for pathspecs in Git." as this isn't 
mentioned elsewhere.
--
Philip

> ---
>   Documentation/gitignore.txt | 71 ++++++++++++++++++++++++++-----------
>   1 file changed, 50 insertions(+), 21 deletions(-)
>
> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
> index b5bc9dbff0..a6c7807c74 100644
> --- a/Documentation/gitignore.txt
> +++ b/Documentation/gitignore.txt
> @@ -89,28 +89,32 @@ PATTERN FORMAT
>      Put a backslash ("`\`") in front of the first "`!`" for patterns
>      that begin with a literal "`!`", for example, "`\!important!.txt`".
>   
> - - If the pattern ends with a slash, it is removed for the
> -   purpose of the following description, but it would only find
> + - A slash `/` is used as a directory separator. A leading and trailing
> +   slash have special meaning and are explained in the following.
> +
> + - If the pattern ends with a slash, it would only find
>      a match with a directory.  In other words, `foo/` will match a
> -   directory `foo` and paths underneath it, but will not match a
> -   regular file or a symbolic link `foo` (this is consistent
> -   with the way how pathspec works in general in Git).
> -
> - - If the pattern does not contain a slash '/', Git treats it as
> -   a shell glob pattern and checks for a match against the
> -   pathname relative to the location of the `.gitignore` file
> -   (relative to the toplevel of the work tree if not from a
> -   `.gitignore` file).
> -
> - - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
> -   anything except "`/`", "`?`" matches any one character except "`/`"
> -   and "`[]`" matches one character in a selected range. See
> -   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
> -   description.
> -
> - - A leading slash matches the beginning of the pathname.
> -   For example, "/{asterisk}.c" matches "cat-file.c" but not
> -   "mozilla-sha1/sha1.c".
> +   directory `foo`, but will not match a regular file or a
> +   symbolic link `foo` (this is consistent with the way how
> +   pathspec works in general in Git).
> +
> + - If the pattern does not end with a slash, it would find a match
> +   with a file or directory.
> +
> + - The pattern is matched relative to the location of
> +   the `.gitignore` file. Except if the pattern contains
> +   no slash (or no slash but a trailing slash), then the pattern is
> +   matched against all files and folders (recursively)
> +   from the location of the `.gitignore` file.
> +   For example, `doc/frotz/` matches `doc/frotz` directory, but not
> +   a/doc/frotz`; however `frotz/` matches `frotz` and `a/frotz` that
> +   is a directory (all paths are relative from the `.gitignore` file).
> +
> + - An asterisk "`*`" matches anything except a slash.
> +   The character "`?`" matches any one character except "`/`".
> +   The range notation, e.g. `[a-zA-Z]`, can be used to match
> +   one of the characters in a range. See fnmatch(3) and the
> +   FNM_PATHNAME flag for a more detailed description.
>   
>   Two consecutive asterisks ("`**`") in patterns matched against
>   full pathname may have special meaning:
> @@ -152,6 +156,31 @@ To stop tracking a file that is currently tracked, use
>   EXAMPLES
>   --------
>   
> + - The pattern `/bar` only matches the file or folder `bar`
> +   but not `a/bar`, whereas the pattern `bar` would match both
> +   (relative to the `.gitignore` file). That is because the
> +   pattern `/bar` contains a non-trailing slash and thus matches
> +   relative to the location of the `.gitignore` file.
> +   Since `bar` has no slash, it matches recursively.
> +
> + - The pattern 'hello.*' is not sufficient for the following rule:
> +   "ignore any file whose name begins with 'hello' and in this
> +   directory only, not in its subdirectories." because the pattern
> +   does not have any slash. To work around this limitation,
> +   you can prepend your pattern with a slash, i.e. '/hello.*';
> +   the pattern now matches 'hello.txt', 'hello.c' but not
> +   'a/hello.java'.
> +
> + - The pattern `doc/frotz` and `/doc/frotz` have the same effect
> +   in any `.gitignore` file. Both pattern contain a non-trailing
> +   slash and thus match relative to the location of the
> +   `.gitignore` file.
> +
> + - The pattern "foo/*", matches "foo/test.json"
> +   (a regular file), "foo/bar" (a diretory), but it does not match
> +   "foo/bar/hello.c" (a regular file), as the asterisk in the
> +   patter does not match "bar/hello.c" which has a slash in it.
> +
>   --------------------------------------------------------------
>       $ git status
>       [...]