diff mbox series

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

Message ID 20200916020840.84892-3-alipman88@gmail.com
State Accepted
Commit 415af72b174802a45300039ef2bc1127d48dc0c0
Headers show
Series git branch: allow combining merged and no-merged filters | expand

Commit Message

Aaron Lipman Sept. 16, 2020, 2:08 a.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.

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.

Signed-off-by: Aaron Lipman <alipman88@gmail.com>
---
 Documentation/filters.txt          | 3 +++
 Documentation/git-branch.txt       | 2 ++
 Documentation/git-for-each-ref.txt | 5 +++++
 Documentation/git-tag.txt          | 5 +++++
 4 files changed, 15 insertions(+)
 create mode 100644 Documentation/filters.txt

Comments

Junio C Hamano Sept. 16, 2020, 7:45 p.m. UTC | #1
Aaron Lipman <alipman88@gmail.com> writes:

> 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.
>
> 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.
>
> Signed-off-by: Aaron Lipman <alipman88@gmail.com>
> ---
>  Documentation/filters.txt          | 3 +++

"git" has more than one concepts that relate to the word "filter",
like the one that are used to create lazy clone, the "filter-branch"
command, "smudge/clean" filter, "textconv" filter used by the diff
and grep machinery to name some.

Make sure you do not accidentally squat on a good-sounding but
an overly generic name.  ref-reachability-filters.txt perhaps?

> diff --git a/Documentation/filters.txt b/Documentation/filters.txt
> new file mode 100644
> index 0000000000..4ee17afc01
> --- /dev/null
> +++ b/Documentation/filters.txt
> @@ -0,0 +1,3 @@
> +When combining multiple `--contains` and `--no-contains` filters, only
> +references that contain at least one of the `--contains` commits and
> +contain none of the `--no-contains` commits are shown.
diff mbox series

Patch

diff --git a/Documentation/filters.txt b/Documentation/filters.txt
new file mode 100644
index 0000000000..4ee17afc01
--- /dev/null
+++ b/Documentation/filters.txt
@@ -0,0 +1,3 @@ 
+When combining multiple `--contains` and `--no-contains` filters, only
+references that contain at least one of the `--contains` commits and
+contain none of the `--no-contains` commits are shown.
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 03c0824d52..aa5e4da142 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -370,6 +370,8 @@  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.
 
+include::filters.txt[]
+
 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..c207ed9551 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -408,6 +408,11 @@  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
+-----
+
+include::filters.txt[]
+
 SEE ALSO
 --------
 linkgit:git-show-ref[1]
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index f6d9791780..dadbd71d62 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -377,6 +377,11 @@  $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
 
 include::date-formats.txt[]
 
+NOTES
+-----
+
+include::filters.txt[]
+
 SEE ALSO
 --------
 linkgit:git-check-ref-format[1].