Deprecate --owner-of in favor of file arguments

src/docs/target_addresses.md

@@ -37,18 +37,6 @@ The following target addresses all specify the same single target.
 
     It's idiomatic to omit the repetition of the target name in this case.
 
--   If the address of the target that owns a certain file is not known, the `--owner-of=` global
-    option can be passed to run the goal on the target which own that file.
-
-        ::::bash
-        $ ./pants --owner-of=src/python/myproject/example/hello.py list
-        src/python/myproject/example/hello:app
-
-    It's also worth noting that multiple instances of `--owner-of=` are accepted in order to work with multiple
-    files and pants will execute the goal on all the targets that own those files. Additionally, `fromfile`
-    support is enabled for this option, so passing `--owner-of=@file` (where "file" is a filename
-    containing a list of filenames to look up owners for) is supported.
-
 -   Relative paths and trailing forward slashes are ignored on the
     command-line to accommodate tab completion:
 
@@ -108,3 +96,26 @@ A trailing double colon specifies a recursive glob of targets at the specified l
     ...
     tests/python/pants_test/tasks:sort_targets
     src/python/pants/testutil:testutils
+
+Alternative: File args
+======================
+
+Instead of specifying the address, you may instead simply specify the file you want Pants to operate on. Pants will find all owner(s) and operate over those owning targets.
+
+    :::bash
+    $ ./pants list src/python/myproject/example.py
+    src/python/myproject:lib
+
+You may pass multiple files and even use globs, with the same syntax as the `sources` field in BUILD files (see ...):
+
+    :::bash
+    # This will format every `.py` file under `src/python/myproject`, except for `ignore.py`
+    $ ./pants fmt 'src/python/myproject/**/*.py' '!src/python/myproject/ignore.py'
+
+You may use the `--spec-file` option to pass a text file with a list of all the files you'd like Pants to operate on (with a newline separating each file):
+
+    :::bash
+    $ echo 'src/python/myproject/f1.py
+      src/python/myproject/f2.py
+      src/python/myproject/example/*.py' > to_be_formatted.txt
+    $ ./pants --spec-file=to_be_formatted.txt fmt

src/python/pants/option/global_options.py

@@ -327,6 +327,14 @@ def register_bootstrap_options(cls, register):
              help='Paths that correspond with build roots for any subproject that this '
                   'project depends on.')
     register('--owner-of', type=list, member_type=file_option, default=[], daemon=False, metavar='<path>',
+             removal_version="1.27.0.dev0",
+             removal_hint=(
+               "Use direct file arguments instead, such as "
+               "`./pants list src/python/f1.py src/python/f2.py` or even "
+               "`./pants fmt 'src/python/**/*.py'`. Instead of `--owner-of=@my_file`, use "
+               "`--spec-file=my_file`.\n\nJust like with `--owner-of`, Pants will "
+               "try to find the owner(s) of the file and then operate on those owning targets."
+             ),
              help='Select the targets that own these files. '
                   'This is the third target calculation strategy along with the --changed-* '
                   'options and specifying the targets directly. These three types of target '