doc: touch-ups for `combine --keep`

7 files changed, 19 insertions, 8 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 8a27e5ee..0c5d7667 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -24,8 +24,13 @@ want to know what's different in 5.0 since 4.5.x, see :ref:`whatsnew5x`.
 Unreleased
 ----------
 
-Nothing yet.
+- ``coverage combine`` has a new option, ``--keep`` to keep the original data
+  files after combining them.  The default is still to delete the files after
+  they have been combined.  This was requested in `issue 1108`_ and implemented
+  in `pull request 1110`_.  Thanks, Éric Larivière.
 
+.. _issue 1108: https://github.com/nedbat/coveragepy/issues/1108
+.. _pull request 1110: https://github.com/nedbat/coveragepy/pull/1110
 
 .. _changes_54:
 
diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index 80084213..b43eeaf8 100644
--- a/CONTRIBUTORS.txt
+++ b/CONTRIBUTORS.txt
@@ -54,9 +54,10 @@ Dirk Thomas
 Dmitry Shishov
 Dmitry Trofimov
 Eduardo Schettino
+Edward Loper
 Eli Skeggs
 Emil Madsen
-Edward Loper
+Éric Larivière
 Federico Bond
 Frazer McLean
 Geoff Bache
diff --git a/coverage/cmdline.py b/coverage/cmdline.py
index 11bc5d99..cdcde451 100644
--- a/coverage/cmdline.py
+++ b/coverage/cmdline.py
@@ -33,7 +33,7 @@ class Opts(object):
     )
     keep = optparse.make_option(
         '', '--keep', action='store_true',
-        help="Keep combined coverage files, otherwise they are deleted.",
+        help="Keep original coverage files, otherwise they are deleted.",
     )
     branch = optparse.make_option(
         '', '--branch', action='store_true',
diff --git a/coverage/control.py b/coverage/control.py
index c952afcd..358e4a97 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -674,7 +674,7 @@ class Coverage(object):
         If `strict` is true, then it is an error to attempt to combine when
         there are no data files to combine.
 
-        If `keep` is true, then combined data files won't be deleted.
+        If `keep` is true, then original input data files won't be deleted.
 
         .. versionadded:: 4.0
             The `data_paths` parameter.
@@ -682,6 +682,8 @@ class Coverage(object):
         .. versionadded:: 4.3
             The `strict` parameter.
 
+        .. versionadded: 5.5
+            The `keep` parameter.
         """
         self._init()
         self._init_data(suffix=None)
diff --git a/doc/cmd.rst b/doc/cmd.rst
index f6087fec..2b2086b1 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -287,6 +287,9 @@ setting to store relative file paths (see :ref:`relative_files
 If any of the data files can't be read, coverage.py will print a warning
 indicating the file and the problem.
 
+The original input data files are deleted once they've been combined. If you
+want to keep those files, use the ``--keep`` command-line option.
+
 .. include:: help/combine.rst
 
 
diff --git a/doc/help/combine.rst b/doc/help/combine.rst
index c35d5b93..7926e9cd 100644
--- a/doc/help/combine.rst
+++ b/doc/help/combine.rst
@@ -13,7 +13,7 @@
     Options:
       -a, --append     Append coverage data to .coverage, otherwise it starts
                        clean each time.
-      --keep           Keep combined coverage files, otherwise they are deleted.
+      --keep           Keep original coverage files, otherwise they are deleted.
       --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',
diff --git a/doc/python-coverage.1.txt b/doc/python-coverage.1.txt
index 10a8927a..00c243de 100644
--- a/doc/python-coverage.1.txt
+++ b/doc/python-coverage.1.txt
@@ -108,8 +108,8 @@ COMMAND REFERENCE
 
     Combine data from multiple coverage files collected with ``run -p``.
     The combined results are written to a single file representing the
-    union of the data.
-    Unless --keep is provided the combined coverage files are deleted.
+    union of the data.  Unless --keep is provided the original input
+    coverage files are deleted.
 
     If `PATH` is specified, they are files or directories containing data to
     be combined.
@@ -121,7 +121,7 @@ COMMAND REFERENCE
         time.
 
     \--keep
-        Keep combined coverage file.
+        Keep original coverage data files.
 
 **debug** `TOPIC` ...