fix: more cleanup of --data-file options

3 files changed, 88 insertions, 43 deletions

diff --git a/coverage/cmdline.py b/coverage/cmdline.py
index c862cb88..47f21984 100644
--- a/coverage/cmdline.py
+++ b/coverage/cmdline.py
@@ -62,7 +62,7 @@ class Opts:
     combine_datafile = optparse.make_option(
         '', '--data-file', action='store', metavar="DATAFILE",
         help=(
-            "Base name of the data files to combine and write. " +
+            "Base name of the data files to operate on. " +
             "Defaults to '.coverage'. [env: COVERAGE_FILE]"
         ),
     )
@@ -344,17 +344,16 @@ GLOBAL_ARGS = [
     Opts.rcfile,
     ]
 
-REPORT_ARGS = [Opts.input_datafile]
-
 CMDS = {
     'annotate': CmdOptionParser(
         "annotate",
         [
             Opts.directory,
+            Opts.input_datafile,
             Opts.ignore_errors,
             Opts.include,
             Opts.omit,
-            ] + REPORT_ARGS + GLOBAL_ARGS,
+            ] + GLOBAL_ARGS,
         usage="[options] [modules]",
         description=(
             "Make annotated copies of the given files, marking statements that are executed " +
@@ -366,9 +365,9 @@ CMDS = {
         "combine",
         [
             Opts.append,
+            Opts.combine_datafile,
             Opts.keep,
             Opts.quiet,
-            Opts.combine_datafile
             ] + GLOBAL_ARGS,
         usage="[options] <path1> <path2> ... <pathN>",
         description=(
@@ -396,7 +395,10 @@ CMDS = {
     ),
 
     'erase': CmdOptionParser(
-        "erase", [Opts.input_datafile] + GLOBAL_ARGS,
+        "erase",
+        [
+            Opts.combine_datafile
+            ] + GLOBAL_ARGS,
         description="Erase previously collected coverage data.",
     ),
 
@@ -411,6 +413,7 @@ CMDS = {
         [
             Opts.contexts,
             Opts.directory,
+            Opts.input_datafile,
             Opts.fail_under,
             Opts.ignore_errors,
             Opts.include,
@@ -422,7 +425,7 @@ CMDS = {
             Opts.no_skip_covered,
             Opts.skip_empty,
             Opts.title,
-            ] + REPORT_ARGS + GLOBAL_ARGS,
+            ] + GLOBAL_ARGS,
         usage="[options] [modules]",
         description=(
             "Create an HTML report of the coverage of the files.  " +
@@ -435,6 +438,7 @@ CMDS = {
         "json",
         [
             Opts.contexts,
+            Opts.input_datafile,
             Opts.fail_under,
             Opts.ignore_errors,
             Opts.include,
@@ -443,7 +447,7 @@ CMDS = {
             Opts.json_pretty_print,
             Opts.quiet,
             Opts.show_contexts,
-            ] + REPORT_ARGS + GLOBAL_ARGS,
+            ] + GLOBAL_ARGS,
         usage="[options] [modules]",
         description="Generate a JSON report of coverage results.",
     ),
@@ -451,6 +455,7 @@ CMDS = {
     'lcov': CmdOptionParser(
         "lcov",
         [
+            Opts.input_datafile,
             Opts.fail_under,
             Opts.ignore_errors,
             Opts.include,
@@ -466,6 +471,7 @@ CMDS = {
         "report",
         [
             Opts.contexts,
+            Opts.input_datafile,
             Opts.fail_under,
             Opts.ignore_errors,
             Opts.include,
@@ -476,7 +482,7 @@ CMDS = {
             Opts.skip_covered,
             Opts.no_skip_covered,
             Opts.skip_empty,
-            ] + REPORT_ARGS + GLOBAL_ARGS,
+            ] + GLOBAL_ARGS,
         usage="[options] [modules]",
         description="Report coverage statistics on modules.",
     ),
@@ -488,10 +494,10 @@ CMDS = {
             Opts.branch,
             Opts.concurrency,
             Opts.context,
+            Opts.output_datafile,
             Opts.include,
             Opts.module,
             Opts.omit,
-            Opts.output_datafile,
             Opts.pylib,
             Opts.parallel_mode,
             Opts.source,
@@ -504,6 +510,7 @@ CMDS = {
     'xml': CmdOptionParser(
         "xml",
         [
+            Opts.input_datafile,
             Opts.fail_under,
             Opts.ignore_errors,
             Opts.include,
@@ -511,7 +518,7 @@ CMDS = {
             Opts.output_xml,
             Opts.quiet,
             Opts.skip_empty,
-            ] + REPORT_ARGS + GLOBAL_ARGS,
+            ] + GLOBAL_ARGS,
         usage="[options] [modules]",
         description="Generate an XML report of coverage results.",
     ),
diff --git a/doc/cmd.rst b/doc/cmd.rst
index cba10065..46d21575 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -134,6 +134,8 @@ There are many options:
                             Valid values are: eventlet, gevent, greenlet,
                             multiprocessing, thread, or a comma-list of them.
       --context=LABEL       The context label to record for this coverage run.
+      --data-file=OUTFILE   Write the recorded coverage data to this file.
+                            Defaults to '.coverage'. [env: COVERAGE_FILE]
       --include=PAT1,PAT2,...
                             Include only files whose paths match one of these
                             patterns. Accepts shell-style wildcards, which must be
@@ -142,8 +144,6 @@ There are many options:
                             path, to be run as 'python -m' would run it.
       --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
                             Accepts shell-style wildcards, which must be quoted.
-      --data-file=OUTFILE   Write the recorded coverage data to this file.
-                            Defaults to '.coverage'. [env: COVERAGE_FILE]
       -L, --pylib           Measure coverage even inside the Python installed
                             library, which isn't done by default.
       -p, --parallel-mode   Append the machine name, process id and random number
@@ -160,7 +160,7 @@ There are many options:
       --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                             'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                             tried. [env: COVERAGE_RCFILE]
-.. [[[end]]] (checksum: 3ec48d96422f8b3aed3cf5a8b223891f)
+.. [[[end]]] (checksum: 05d15818e42e6f989c42894fb2b3c753)
 
 If you want :ref:`branch coverage <branch>` measurement, use the ``--branch``
 flag.  Otherwise only statement coverage is measured.
@@ -391,18 +391,18 @@ want to keep those files, use the ``--keep`` command-line option.
     Options:
       -a, --append          Append coverage data to .coverage, otherwise it starts
                             clean each time.
+      --data-file=DATAFILE  Base name of the data files to operate on. Defaults to
+                            '.coverage'. [env: COVERAGE_FILE]
       --keep                Keep original coverage files, otherwise they are
                             deleted.
       -q, --quiet           Don't print messages about what is happening.
-      --data-file=DATAFILE  Base name of the data files to combine and write.
-                            Defaults to '.coverage'. [env: COVERAGE_FILE]
       --debug=OPTS          Debug options, separated by commas. [env:
                             COVERAGE_DEBUG]
       -h, --help            Get help on this command.
       --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                             'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                             tried. [env: COVERAGE_RCFILE]
-.. [[[end]]] (checksum: 6cba18a0531f9d2f7af67e472b96eb6b)
+.. [[[end]]] (checksum: 0ac91b0781d7146b87953f09090dab92)
 
 
 .. _cmd_erase:
@@ -421,15 +421,15 @@ To erase the collected data, use the **erase** command:
     Erase previously collected coverage data.
 
     Options:
-      --data-file=INFILE  Read coverage data for report generation from this file.
-                          Defaults to '.coverage'. [env: COVERAGE_FILE]
-      --debug=OPTS        Debug options, separated by commas. [env:
-                          COVERAGE_DEBUG]
-      -h, --help          Get help on this command.
-      --rcfile=RCFILE     Specify configuration file. By default '.coveragerc',
-                          'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
-                          [env: COVERAGE_RCFILE]
-.. [[[end]]] (checksum: e3dec8ef7687d3525682904340e8cf54)
+      --data-file=DATAFILE  Base name of the data files to operate on. Defaults to
+                            '.coverage'. [env: COVERAGE_FILE]
+      --debug=OPTS          Debug options, separated by commas. [env:
+                            COVERAGE_DEBUG]
+      -h, --help            Get help on this command.
+      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
+                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
+                            tried. [env: COVERAGE_RCFILE]
+.. [[[end]]] (checksum: cfeaef66ce8d5154dc6914831030b46b)
 
 If your configuration file indicates parallel data collection, **erase** will
 remove all of the data files.
@@ -496,6 +496,8 @@ as a percentage.
                             Only display data from lines covered in the given
                             contexts. Accepts Python regexes, which must be
                             quoted.
+      --data-file=INFILE    Read coverage data for report generation from this
+                            file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       --fail-under=MIN      Exit with a status of 2 if the total coverage is less
                             than MIN.
       -i, --ignore-errors   Ignore errors while reading source files.
@@ -514,15 +516,13 @@ as a percentage.
       --skip-covered        Skip files with 100% coverage.
       --no-skip-covered     Disable --skip-covered.
       --skip-empty          Skip files with no code.
-      --data-file=INFILE    Read coverage data for report generation from this
-                            file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       --debug=OPTS          Debug options, separated by commas. [env:
                             COVERAGE_DEBUG]
       -h, --help            Get help on this command.
       --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                             'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                             tried. [env: COVERAGE_RCFILE]
-.. [[[end]]] (checksum: 97565fdb6f1eefbeeb12d56151fa5e63)
+.. [[[end]]] (checksum: 2f8dde61bab2f44fbfe837aeae87dfd2)
 
 The ``-m`` flag also shows the line numbers of missing statements::
 
@@ -613,6 +613,8 @@ Click the keyboard icon in the upper right to see the complete list.
                             quoted.
       -d DIR, --directory=DIR
                             Write the output files to DIR.
+      --data-file=INFILE    Read coverage data for report generation from this
+                            file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       --fail-under=MIN      Exit with a status of 2 if the total coverage is less
                             than MIN.
       -i, --ignore-errors   Ignore errors while reading source files.
@@ -630,15 +632,13 @@ Click the keyboard icon in the upper right to see the complete list.
       --no-skip-covered     Disable --skip-covered.
       --skip-empty          Skip files with no code.
       --title=TITLE         A text string to use as the title on the HTML.
-      --data-file=INFILE    Read coverage data for report generation from this
-                            file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       --debug=OPTS          Debug options, separated by commas. [env:
                             COVERAGE_DEBUG]
       -h, --help            Get help on this command.
       --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                             'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                             tried. [env: COVERAGE_RCFILE]
-.. [[[end]]] (checksum: e3208f3b38a44ca81e0235e867f4fd1c)
+.. [[[end]]] (checksum: e3a1a6e24ad9b303ba06d42880ed0219)
 
 The title of the report can be set with the ``title`` setting in the
 ``[html]`` section of the configuration file, or the ``--title`` switch on
@@ -691,6 +691,8 @@ compatible with `Cobertura`_.
     Generate an XML report of coverage results.
 
     Options:
+      --data-file=INFILE    Read coverage data for report generation from this
+                            file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       --fail-under=MIN      Exit with a status of 2 if the total coverage is less
                             than MIN.
       -i, --ignore-errors   Ignore errors while reading source files.
@@ -704,15 +706,13 @@ compatible with `Cobertura`_.
                             'coverage.xml'
       -q, --quiet           Don't print messages about what is happening.
       --skip-empty          Skip files with no code.
-      --data-file=INFILE    Read coverage data for report generation from this
-                            file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       --debug=OPTS          Debug options, separated by commas. [env:
                             COVERAGE_DEBUG]
       -h, --help            Get help on this command.
       --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                             'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                             tried. [env: COVERAGE_RCFILE]
-.. [[[end]]] (checksum: 3dc4450c0a723109f987c4b6f968be43)
+.. [[[end]]] (checksum: 8b239d89534be0b2c69489e10b1352a9)
 
 You can specify the name of the output file with the ``-o`` switch.
 
@@ -777,6 +777,8 @@ The **json** command writes coverage data to a "coverage.json" file.
                             Only display data from lines covered in the given
                             contexts. Accepts Python regexes, which must be
                             quoted.
+      --data-file=INFILE    Read coverage data for report generation from this
+                            file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       --fail-under=MIN      Exit with a status of 2 if the total coverage is less
                             than MIN.
       -i, --ignore-errors   Ignore errors while reading source files.
@@ -791,15 +793,13 @@ The **json** command writes coverage data to a "coverage.json" file.
       --pretty-print        Format the JSON for human readers.
       -q, --quiet           Don't print messages about what is happening.
       --show-contexts       Show contexts for covered lines.
-      --data-file=INFILE    Read coverage data for report generation from this
-                            file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       --debug=OPTS          Debug options, separated by commas. [env:
                             COVERAGE_DEBUG]
       -h, --help            Get help on this command.
       --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                             'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                             tried. [env: COVERAGE_RCFILE]
-.. [[[end]]] (checksum: fdc9af899380fbb78599d08a70e564fc)
+.. [[[end]]] (checksum: e53e60cb65d971c35d1db1c08324b72e)
 
 You can specify the name of the output file with the ``-o`` switch.  The JSON
 can be nicely formatted by specifying the ``--pretty-print`` switch.
@@ -820,6 +820,8 @@ The **lcov** command writes coverage data to a "coverage.lcov" file.
     Generate an LCOV report of coverage results.
 
     Options:
+      --data-file=INFILE    Read coverage data for report generation from this
+                            file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       --fail-under=MIN      Exit with a status of 2 if the total coverage is less
                             than MIN.
       -i, --ignore-errors   Ignore errors while reading source files.
@@ -838,7 +840,7 @@ The **lcov** command writes coverage data to a "coverage.lcov" file.
       --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                             'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                             tried. [env: COVERAGE_RCFILE]
-.. [[[end]]] (checksum: 4d078e4637e5b507cbb997803a0d4758)
+.. [[[end]]] (checksum: 16acfbae8011d2e3b620695c5fe13746)
 
 Other common reporting options are described above in :ref:`cmd_reporting`.
 
@@ -890,6 +892,8 @@ For example::
     Options:
       -d DIR, --directory=DIR
                             Write the output files to DIR.
+      --data-file=INFILE    Read coverage data for report generation from this
+                            file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       -i, --ignore-errors   Ignore errors while reading source files.
       --include=PAT1,PAT2,...
                             Include only files whose paths match one of these
@@ -897,15 +901,13 @@ For example::
                             quoted.
       --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
                             Accepts shell-style wildcards, which must be quoted.
-      --data-file=INFILE    Read coverage data for report generation from this
-                            file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       --debug=OPTS          Debug options, separated by commas. [env:
                             COVERAGE_DEBUG]
       -h, --help            Get help on this command.
       --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                             'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                             tried. [env: COVERAGE_RCFILE]
-.. [[[end]]] (checksum: aa41bad1cd4c08efc3276b5dca01dea3)
+.. [[[end]]] (checksum: fd7d8fbd2dd6e24d37f868b389c2ad6d)
 
 Other common reporting options are described above in :ref:`cmd_reporting`.
 
diff --git a/doc/python-coverage.1.txt b/doc/python-coverage.1.txt
index 41a3bbea..7cd16b8d 100644
--- a/doc/python-coverage.1.txt
+++ b/doc/python-coverage.1.txt
@@ -8,7 +8,7 @@ Measure Python code coverage
 
 :Author: Ned Batchelder <ned@nedbatchelder.com>
 :Author: |author|
-:Date: 2021-01-24
+:Date: 2022-01-25
 :Copyright: Apache 2.0 license, attribution and disclaimer required.
 :Manual section: 1
 :Manual group: Coverage.py
@@ -96,6 +96,10 @@ COMMAND REFERENCE
     \-d `DIR`, --directory=`DIR`
         Write the output files to DIR.
 
+    \--data-file `INFILE`
+        Read coverage data for report generation from this
+        file. Defaults to '.coverage'.
+
     \-i, --ignore-errors
         Ignore errors while reading source files.
 
@@ -123,6 +127,9 @@ COMMAND REFERENCE
         Append coverage data to .coverage, otherwise it starts clean each
         time.
 
+    \--data-file `DATAFILE`
+        Base name of the data files to operate on.  Defaults to '.coverage'.
+
     \--keep
         Keep original coverage data files.
 
@@ -145,6 +152,11 @@ COMMAND REFERENCE
 
     Erase previously collected coverage data.
 
+    Options:
+
+    \--data-file `DATAFILE`
+        Base name of the data files to operate on. Defaults to '.coverage'.
+
 **help** [ `command` ]
 
     Describe how to use coverage.py.
@@ -163,6 +175,10 @@ COMMAND REFERENCE
     \-d `DIR`, --directory `DIR`
         Write the output files to `DIR`.
 
+    \--data-file `INFILE`
+        Read coverage data for report generation from this file.
+        Defaults to '.coverage'.
+
     \--fail-under `MIN`
         Exit with a status of 2 if the total coverage is less than `MIN`.
 
@@ -206,6 +222,10 @@ COMMAND REFERENCE
     \--contexts `PAT` [ , ... ]
         Only include contexts that match one of the regex patterns.
 
+    \--data-file `INFILE`
+        Read coverage data for report generation from this file.
+        Defaults to '.coverage'.
+
     \--fail-under `MIN`
         Exit with a status of 2 if the total coverage is less than `MIN`.
 
@@ -238,6 +258,10 @@ COMMAND REFERENCE
 
     Options:
 
+    \--data-file `INFILE`
+        Read coverage data for report generation from this file.
+        Defaults to '.coverage'.
+
     \--fail-under `MIN`
         Exit with a status of 2 if the total coverage is less than `MIN`.
 
@@ -267,6 +291,10 @@ COMMAND REFERENCE
     \--contexts `PAT` [ , ... ]
         Only include contexts that match one of the regex patterns.
 
+    \--data-file `INFILE`
+        Read coverage data for report generation from this file.
+        Defaults to '.coverage'.
+
     \--fail-under `MIN`
         Exit with a status of 2 if the total coverage is less than `MIN`.
 
@@ -324,6 +352,10 @@ COMMAND REFERENCE
     \--context `CONTEXT`
         The context label to record for this coverage run.
 
+    \--data-file `OUTFILE`
+        Write the recorded coverage data to this file.
+        Defaults to '.coverage'.
+
     \--include `PATTERN` [ , ... ]
         Include only files whose paths match one of these
         PATTERNs. Accepts shell-style wildcards, which must be quoted.
@@ -357,6 +389,10 @@ COMMAND REFERENCE
 
     Options:
 
+    \--data-file `INFILE`
+        Read coverage data for report generation from this file.
+        Defaults to '.coverage'.
+
     \--fail-under `MIN`
         Exit with a status of 2 if the total coverage is less than `MIN`.