git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: Dakota Hawkins <dakota@dakotahawkins.com>
Cc: Jeff King <peff@peff.net>, Duy Nguyen <pclouds@gmail.com>,
	Junio C Hamano <gitster@pobox.com>, Git <git@vger.kernel.org>
Subject: Re: [PATCH] doc: clarify non-recursion for ignore paths like `foo/`
Date: Wed, 21 Mar 2018 13:21:51 +0100	[thread overview]
Message-ID: <87woy5y5y8.fsf@evledraar.gmail.com> (raw)
In-Reply-To: <CAHnyXxQRfzAT75P7dxvdEEN_FRYCc7j97VEfL8tTUgVdeK-O+g@mail.gmail.com>


On Wed, Mar 21 2018, Dakota Hawkins wrote:

> Re-reading the section you quoted again a couple of times you're
> correct, but somehow that wasn't clear to me despite reading/searching
> for what I wanted to see several times.

FWIW I just knew this because I'd run into this the other day, so it was
fresh in my mind.

> While what I wrote may need improvement, I think there are a couple of
> valid concerns with the way this behavior is documented currently:
>
>   - Generally: Reading about pattern matching for .gitignore is
> awkward on its face, since positive matches have negative consequences
> (in other words `include = !match`).
>   - Specifically: This behavior that is specific to `foo/` matches is
> documented in the section for `!foo` matches. If you're trying to find
> the implications of `foo/` you may not have read about `!foo` as
> carefully.
>
> Since this behavior is practically applicable to both pattern formats,
> and since patterns in the sum of a repo's .gitignore files can get
> somewhat complicated, I think it would be a good idea to either:

I think it makes more sense to document it where it's documented now,
i.e. under how "!" works in general, since this is an edge case with
negative matching.

Whether you specify "foo" or "foo/" is then just an unrelated edge case
in how we match directories v.s. files, but doesn't per-se have anything
to do with how the inversion rules work, so I think it makes sense to
document it where we document the inversion rules.

I.e. you'd get the same for all of (assuming a directory "foo"):

    f*
    !*.txt

    foo
    !*.txt

    foo/
    !*.txt

So what we subsequently exclude just because it's deeper in the tree has
nothing to do with how the disambiguation syntax for matching the
directory looks like.

>   - Do this and basically explain the same behavior twice in two
> pattern format sections, or
>   - Pull the documentation for this behavior out into another section
> where users would be likely to find and understand it if they're
> looking into either pattern format

I think it can certainly be made clearer, but maybe with a practical
example (per above) where we also show the dir structure that
would/wouldn't be matched.

I just chimed in on this one because your patch says the docs are
"unclear" then "Explain this behavior (and its implications) more
explicitly" without a reference to the existing adjacent docs. I think
whatever we do we should be unifying these docs if they're amended, not
stating this twice.

  parent reply	other threads:[~2018-03-21 12:21 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-03-21 11:13 [PATCH] doc: clarify non-recursion for ignore paths like `foo/` Dakota Hawkins
2018-03-21 11:25 ` Ævar Arnfjörð Bjarmason
2018-03-21 11:53   ` Dakota Hawkins
2018-03-21 12:13     ` Dakota Hawkins
2018-03-21 12:21     ` Ævar Arnfjörð Bjarmason [this message]
2018-03-21 12:46       ` Dakota Hawkins

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87woy5y5y8.fsf@evledraar.gmail.com \
    --to=avarab@gmail.com \
    --cc=dakota@dakotahawkins.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=pclouds@gmail.com \
    --cc=peff@peff.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).