Document --filter options working with any goal (#16090)

Closes #16057.

[ci skip-rust]
[ci skip-build-wheels]

docs/markdown/Getting Started/getting-started/existing-repositories.md

@@ -60,8 +60,7 @@ python_tests(
 `./pants test ::` will only run the relevant tests. You can combine this with [`./pants peek`](doc:project-introspection) to get a list of test files that should be run with your original test runner:
 
 ```
-./pants list --filter-target-type=python_test :: | \
-  xargs ./pants peek | \
+./pants --filter-target-type=python_test peek :: | \
   jq -r '.[] | select(.skip_tests== true) | .["sources"][]'
 ```
 

docs/markdown/Using Pants/advanced-target-selection.md

@@ -6,9 +6,11 @@ hidden: false
 createdAt: "2020-05-11T20:10:29.560Z"
 updatedAt: "2022-02-08T23:44:44.463Z"
 ---
-See [File arguments vs. target arguments](doc:goals#goal-arguments) for the normal techniques for telling Pants what to run on. 
+See [Goal arguments](doc:goals#goal-arguments) for the normal techniques for telling Pants what to
+run on. 
 
-See [Project introspection](doc:project-introspection) for queries that you can run and then pipe into another Pants run, such as running over certain target types.
+See [Project introspection](doc:project-introspection) for queries that you can run and then pipe
+into another Pants run, such as finding the dependencies of a target or file.
 
 Running over changed files with `--changed-since`
 -------------------------------------------------
@@ -36,10 +38,59 @@ By default, `--changed-since` will only run over files directly changed. Often,
   test
 ```
 
+`filter` options
+----------------
+
+Use filters to operate on only targets that match the predicate, e.g. only running Python tests.
+
+Specify a predicate by using one of the below `filter` options, like `--filter-target-type`. You
+can use a comma to OR multiple values, meaning that at least one member must be matched. You
+can repeat the option multiple times to AND each filter. You can prefix the filter with
+`-` to negate the filter, meaning that the target must not be true for the filter.
+
+Some examples:
+
+```bash
+# Only `python_source` targets.
+./pants --filter-target-type=python_source list ::
+
+# `python_source` or `python_test` targets.
+./pants --filter-target-type='python_source,python_test' list ::
+
+# Any target except for `python_source` targets
+./pants --filter-target-type='-python_source' list ::
+```
+
+You can combine multiple filter options in the same run, e.g.:
+
+```bash
+./pants --filter-target-type='python_test' --filter-address-regex=^integration_tests test ::
+```
+
+### `--filter-target-type`
+
+Each value should be the name of a target type, e.g.
+`./pants --filter-target-type=python_test test ::`.
+
+Run `./pants help targets` to see what targets are registered.
+
+### `--filter-address-regex`
+
+Regex strings for the address, such as
+`./pants --filter-address-regex='^integration_tests$' test ::`.
+
+### `--filter-tag-regex`
+
+Regex strings to match against the `tags` field, such as 
+`./pants --filter-tag-regex='^skip_lint$' lint ::`.
+
+If you don't need the power of regex, use the simpler `--tag` global option explained below.
+
 Tags: annotating targets
 ------------------------
 
-Every target type has a field called `tags`, which allows you to add a sequence of strings. The strings can be whatever you'd like, such as `"integration_test"`.
+Every target type has a field called `tags`, which allows you to add a sequence of strings. The
+strings can be whatever you'd like, such as `"integration_test"`.
 
 ```python BUILD
 python_tests(
@@ -67,6 +118,8 @@ You can even combine multiple includes and excludes:
 ./pants --tag='+type_checked,skip_lint' --tag='-integration_test' list ::
 ```
 
+Use `--filter-tag-regex` instead for more complex queries.
+
 `--spec-files`
 --------------
 
@@ -101,8 +154,9 @@ To pipe a Pants run, use your shell's `|` pipe operator and `xargs`:
 You can, of course, pipe multiple times:
 
 ```bash
-$ ./pants dependees helloworld/util | \
-   xargs ./pants list --filter-target-type=python_source | \
+# Run over the second-degree dependees of `utils.py`.
+❯ ./pants dependees helloworld/utils.py | \
+   xargs ./pants dependees | \
    xargs ./pants lint
 ```
 
@@ -132,5 +186,5 @@ You can leverage shell piping to partition the input targets into multiple shard
 For example, to split your Python tests into 10 shards, and select shard 0:
 
 ```bash
-./pants list :: | xargs ./pants list --filter-target-type=python_test | awk 'NR % 10 == 0' | ./pants test
+./pants --filter-target-type=python_test list :: | awk 'NR % 10 == 0' | xargs ./pants test
 ```

docs/markdown/Using Pants/project-introspection.md

@@ -53,34 +53,9 @@ You can specify a file, which will find the target(s) owning that file:
 helloworld/greet/greeting_test.py:tests
 ```
 
-You can also specify filters of various sorts to only include targets that match the predicate(s).
-
-Specify a predicate by using one of the below `filter` options, like `--filter-target-type`. You can use a comma to OR multiple values, meaning that at least one member must be matched. You can repeat the option multiple times to AND each filter. You can prefix the filter with `-` to negate the filter, meaning that the target must not be true for the filter.
-
-Some examples:
-
-```bash
-# Only `python_source` targets.
-./pants list --filter-target-type=python_source ::
-
-# `python_source` or `python_test` targets.
-./pants list --filter-target-type='python_source,python_test' ::
-
-# Any target except for `python_source` targets
-./pants list --filter-target-type='-python_source' ::
-```
-
-### `--filter-target-type`
-
-Each value should be the name of a target type, e.g. `python_source` or `resource`. Run `./pants help targets` to see what targets are registered.
-
-### `--filter-address-regex`
-
-Regex strings for the address, such as `^dir` or `:util$`.
-
-### `--filter-tag-regex`
-
-Regex strings for the `tags` field. Alternatively, you can use the global `--tags` option, which uses exact string matches instead of regex. See [Advanced target selection](doc:advanced-target-selection).
+`list` often works well when paired with the `--filter` options from
+[Advanced Target Selection](doc:advanced-target-selection), e.g.
+`./pants --filter-target-type=python_test list ::` to find all your `python_test` targets.
 
 `dependencies` - find a target's dependencies
 ---------------------------------------------

docs/markdown/Using Pants/troubleshooting.md

@@ -87,7 +87,7 @@ To see what dependencies Pants knows about, run `./pants dependencies path/to/fi
 Is the missing import from a third-party dependency? Common issues:
 
 - Pants does know about your third-party requirements, e.g. missing `python_requirements` and `go_mod` target generators.
-  - To see all third-party requirement targets Pants knows, run `./pants list --filter-target-type=$tgt ::`, where Python: `python_requirement`, Go: `go_third_party_package`, and JVM: `jvm_artifact`.
+  - To see all third-party requirement targets Pants knows, run `./pants --filter-target-type=$tgt list ::`, where Python: `python_requirement`, Go: `go_third_party_package`, and JVM: `jvm_artifact`.
   - Run `./pants tailor ::`, or manually add the relevant targets.
 - The dependency is missing from your third-party requirements list, e.g. `go.mod` or `requirements.txt`.
 - The dependency exposes a module different than the default Pants uses, e.g. Python's `ansicolors` exposing `colors`.
@@ -195,7 +195,7 @@ You can use `./pants peek` to help identify why the same requirement is being us
 
 ```shell Shell
 # Check the `requirements` key to see if it has the problematic requirement.
-./pants list --filter-target-type=python_requirement | xargs ./pants peek
+./pants --filter-target-type=python_requirement peek ::
 ```
 
 macOS users: issues with system Python interpreters