On 18.05.19 21:34, Philip Oakley wrote:
Hi Adam
Hi Philip
On 18/05/2019 15:07, Dr. Adam Nielsen wrote:
This "Otherwise" below could be the complement to the initial "If", or
could be part of a "matches" pair of example sentences. At least on my
initial reading I paired it via the 'matches'.
Now that you said it, I can see the ambiguity. Maybe its better to
create a blank line separator, the mentioned paragraph is already very
big. Perhaps like this:
If the pattern contains no slash or only a trailing slash, [..].
For example, `frotz/` matches `frotz` and `a/frotz` that
is a directory (relative from the `.gitignore` file).
Otherwise, if the pattern contains a non-trailing slash,
the pattern is matched relative to the location
of the `.gitignore` file.
On 19.05.19 03:59, Junio C Hamano wrote:
>> 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 ;-)
You are right. The paragraph below
>> + - The above pargraph also includes the case of a leading slash.
can of course not be read in any order. Maybe its more precise to say:
Remove meta-rules in a paragraph that effect the way one
has to read upcoming paragraphs.
> 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 ;-)
This paragraph references to the immediate forerunner. Why do you think
it references to all four paragraphs?
> To put it differently, your reading of the above four
> bullets are incomplete unless you read this too.
I would say the paragraph
>> + - The above pargraph also includes the case of a leading slash. [...]
is redundant. Its purpose is to point out that the previous paragraph
also included the rule about the leading slash.
So the above four paragraphs are valid in my opinion without this paragraph.
>
> Typofix: "pargraph" -> "paragraph".
>
> In any case, I cannot guess what 'also include the case of a leaning
> slash' wants to say.
Maybe this is better understandable(?):
Note that any pattern that starts with a leading slash contains
a non-trailing slash and is therefore effected by the
previous paragraph.
This might be even better after creating a new paragraph for the
"Otherwise.." part as suggested by Philip.
> 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'.
I think examples that are as descriptive as this should rather belong to
the "Example" section. For the rules section I would like to keep the
examples as short and clean as possible (I think Johannes agrees with me
here?).
If understand you correctly, then you find my example too abstract?
Maybe this is better(?):
For example, 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).
On 19.05.19 08:59, Johannes Sixt wrote:
> All those examples unterrupt the flow of thought in a way that makes it
> diffcult to follow the reasoning.
I agree with you that complex examples make it harder to read. However,
I find that if a complex rule is accompanied by a simple example, it
improves readability a lot. I find that for example the four paragraphs
about the `**` have a perfect balance between rules and examples.
>May I suggest a different approach to
> upate this text? Provide two patches:
>
> - Patch 1/2 updates the Examples section such that it contains all
> examples that you provide in the text above, with explanation.
> Perhaps refer to the Examples section early above the rules.
>
> - Patch 2/2 updates the rules section without giving examples.
Maybe its best if discuss this for each changed/new paragraph if the
example should be moved into the example section.
1.
>> + - 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).
I think the example very short and important, and it should stay.
2.
- Otherwise, if the pattern contains a non-trailing slash,
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).
Same here. Its a short and important. I would like to keep it there.
3.
Note that any pattern that starts with a leading slash contains
a non-trailing slash and is therefore effected by the
previous paragraph.
For example, 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).
I would agree to put this entire paragraph in the example section.
4.
>> + - 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.
I would also agree to put the 4-line example into the example section.
We could also put this in the example section:
Note that the pattern `doc/frotz` and `/doc/frotz` have the
same effect in any `.gitignore` file, while `/bar` and `bar`
have not the same effect (`/bar` will not match `foo/bar`).
If we do all this, I could imagine the following procedure:
- Patch 1/2 updates all the changes but do not include
the examples from 3. and 4.
- Patch 2/2 improving the example section and including the
examples from 3. and 4.
I have actually some ideas for the example section that you may see in
my blog post in the section examples:
https://dr-nielsen.com/git/gitignore-pattern-explained
I would like to put all of those in the example section of the docs. But
this is clearly out of scope of patch 1/2.
> The examples in the Examples section are overly technical by saying
>
> $ cat .gitignore
> vmlinux*
> $ ls arch/foo/kernel/vm*
> arch/foo/kernel/vmlinux.lds.S
> $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
>
> I think that this could be made more pleasent to read if one would not
> have to use a mental shell interpreter. ;)
I agree, I would also vote to remove this one.
All the best,
Adam
