diff mbox series

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

Message ID 20200913193140.66906-3-alipman88@gmail.com
State Superseded
Headers show
Series git branch: allow combining merged and no-merged filters | expand

Commit Message

Aaron Lipman Sept. 13, 2020, 7:31 p.m. UTC
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.

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.
---
 Documentation/git-branch.txt       | 4 ++++
 Documentation/git-for-each-ref.txt | 7 +++++++
 Documentation/git-tag.txt          | 7 +++++++
 3 files changed, 18 insertions(+)

Comments

Eric Sunshine Sept. 13, 2020, 9:10 p.m. UTC | #1
On Sun, Sep 13, 2020 at 3:32 PM Aaron Lipman <alipman88@gmail.com> wrote:
> 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.

> 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?
Junio C Hamano Sept. 14, 2020, 8:07 p.m. UTC | #2
Eric Sunshine <sunshine@sunshineco.com> writes:

>> 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?

Replace `git branch` with "this command" and make it even more generic?
Or eliminate the subject by going passive, e.g.

    Only references that contain at least one of the '--contains'
    commits but contain none of the '--no-contains' commits are
    shown

or somesuch?
diff mbox series

Patch

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 03c0824d52..2a36d29929 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -370,6 +370,10 @@  serve four related but different purposes:
 - `--no-merged` is used to find branches which are candidates for merging
   into HEAD, since those branches are not fully contained by HEAD.
 
+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.
+
 SEE ALSO
 --------
 linkgit:git-check-ref-format[1],
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 616ce46087..e5f0226273 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -408,6 +408,13 @@  Note also that multiple copies of an object may be present in the object
 database; in this case, it is undefined which copy's size or delta base
 will be reported.
 
+NOTES
+-----
+
+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.
+
 SEE ALSO
 --------
 linkgit:git-show-ref[1]
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index f6d9791780..adfeab7a93 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -377,6 +377,13 @@  $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
 
 include::date-formats.txt[]
 
+NOTES
+-----
+
+When combining multiple `--contains` and `--no-contains` filters,
+`git tag` shows tags containing at least one of the named `--contains`
+commits and none of the named `--no-contains` commits.
+
 SEE ALSO
 --------
 linkgit:git-check-ref-format[1].