Re: [PATCH] make slash-rules more readable

[Junio C Hamano <gitster@pobox.com>]

"Dr. Adam Nielsen" <admin@in-ici.net> writes:

> gitignore.txt: make slash-rules more readable
>
> Make all paragraphs valid, even if they are not read
> in strict order.

I think you are giving up on this, and I do not think that is
particularly a bad thing ;-)

> + - 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
> +   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.
> +
> + - If the pattern contains no slash or only a trailing slash,
> +   the pattern is matched against all files and folders (recursively)
> +   from the location of the `.gitignore` file.
> +   For example, `frotz/` matches `frotz` and `a/frotz` that
> +   is a directory (relative from the `.gitignore` file).
> +   Otherwise the pattern is matched relative to the
> +   location of the `.gitignore` file.
> +   For example, `doc/frotz/` matches `doc/frotz` directory, but not
> +   `a/doc/frotz` (relative from the `.gitignore` file).

OK.

> + - The above pargraph also includes the case of a leading slash.

Now you (not you the author of the document, but figuratively "any
reader of this document") must have read all the four before this
point ;-) To put it differently, your reading of the above four
bullets are incomplete unless you read this too.

Typofix: "pargraph" -> "paragraph".

In any case, I cannot guess what 'also include the case of a leaning
slash' wants to say.  Perhaps

      Note that the above rule means you cannot easily say "a file
      whose name contains 'hello' and in this directory only, not in
      its subdirectories." because a pattern 'hello.*' 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'.

as the third point of the above paragraph (the first is about a
pattern without a slash, the second "Otherwise" is about a pattern
with one or more slashes, and the new "Note that" becomes the
third) may make it easier to follow and keep your "each bullet point
is independent".

> +   For example, the pattern `/bar` only matches the file or
> +   folder `bar` that is at the same location as the `gitignore`
> +   file. Whereas the pattern `bar` would also match in folders
> +   below the `gitignore`  file.
> +
> + - An asterisk "`*`" matches anything except a slash.
> +   A pattern "foo/*", for example, 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.
> +   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: