Re: [PATCH v3 2/3] Doc: cover multiple contains/no-contains filters

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Sep 13, 2020, 21:10 UTC
Message-ID: <CAPig+cRaz+HPNW_WFX7UqcqtRwG_Td59LkXWF6HHoYOO1M6=bg@mail.gmail.com>
In-Reply-To: <20200913193140.66906-3-alipman88@gmail.com>

On Sun, Sep 13, 2020 at 3:32 PM Aaron Lipman <alipman88@gmail.com> wrote:

Show 7 quoted lines

> Update documentation for "git branch", "git for-each-ref" and "git tag"
> with notes explaining what happens when passed multiple --contains or
> --no-contains filters, e.g.:
>
>   When combining multiple `--contains` and `--no-contains` filters,
>   `git for-each-ref` shows refs containing at least one of the named
>   `--contains` commits and none of the named `--no-contains` commits.

We normally avoid repeating in the commit message what the patch itself already says. The first paragraph alone (without the example text) would be plenty sufficient. (Not itself worth a re-roll, though.)

> This behavior is useful to document prior to enabling multiple
> merged/no-merged filters, in order to demonstrate consistent behavior
> between merged/no-merged and contains/no-contains filters.
> ---

Missing sign-off.

Show 5 quoted lines

> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> @@ -370,6 +370,10 @@ serve four related but different purposes:
> +When combining multiple `--contains` and `--no-contains` filters,
> +`git branch` shows branches containing at least one of the named
> +`--contains` commits and none of the named `--no-contains` commits.

This is repeated nearly verbatim in the other two documentation pages. It makes one wonder if it can be generalized and placed in its own file which is included in the other documents via `include::contains.txt[]`. Perhaps like this:

    When combining multiple `--contains` and `--no-contains` filters,
    `git branch` shows references containing at least one of the named
    `--contains` commits and none of the named `--no-contains`
    commits.

But perhaps that's too generic?