diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/cmd.rst | 40 | ||||
-rw-r--r-- | doc/config.rst | 2 | ||||
-rw-r--r-- | doc/source.rst | 29 |
3 files changed, 48 insertions, 23 deletions
diff --git a/doc/cmd.rst b/doc/cmd.rst index cb9a147e..f8de0cb3 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -342,7 +342,7 @@ single directory, and use the **combine** command to combine them into one $ coverage combine -You can also name directories or files on the command line:: +You can also name directories or files to be combined on the command line:: $ coverage combine data1.dat windows_data_files/ @@ -364,22 +364,6 @@ An existing combined data file is ignored and re-written. If you want to use runs, use the ``--append`` switch on the **combine** command. This behavior was the default before version 4.2. -To combine data for a source file, coverage has to find its data in each of the -data files. Different test runs may run the same source file from different -locations. For example, different operating systems will use different paths -for the same file, or perhaps each Python version is run from a different -subdirectory. Coverage needs to know that different file paths are actually -the same source file for reporting purposes. - -You can tell coverage.py how different source locations relate with a -``[paths]`` section in your configuration file (see :ref:`config_paths`). -It might be more convenient to use the ``[run] relative_files`` -setting to store relative file paths (see :ref:`relative_files -<config_run_relative_files>`). - -If data isn't combining properly, you can see details about the inner workings -with ``--debug=pathmap``. - If any of the data files can't be read, coverage.py will print a warning indicating the file and the problem. @@ -414,6 +398,28 @@ want to keep those files, use the ``--keep`` command-line option. .. [[[end]]] (checksum: 0bdd83f647ee76363c955bedd9ddf749) +.. _cmd_combine_remapping: + +Re-mapping paths +................ + +To combine data for a source file, coverage has to find its data in each of the +data files. Different test runs may run the same source file from different +locations. For example, different operating systems will use different paths +for the same file, or perhaps each Python version is run from a different +subdirectory. Coverage needs to know that different file paths are actually +the same source file for reporting purposes. + +You can tell coverage.py how different source locations relate with a +``[paths]`` section in your configuration file (see :ref:`config_paths`). +It might be more convenient to use the ``[run] relative_files`` +setting to store relative file paths (see :ref:`relative_files +<config_run_relative_files>`). + +If data isn't combining properly, you can see details about the inner workings +with ``--debug=pathmap``. + + .. _cmd_erase: Erase data: ``coverage erase`` diff --git a/doc/config.rst b/doc/config.rst index 6b753579..c6f6442a 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -357,7 +357,7 @@ The first list that has a match will be used. The ``--debug=pathmap`` option can be used to log details of the re-mapping of paths. See :ref:`the --debug option <cmd_run_debug>`. -See :ref:`cmd_combine` for more information. +See :ref:`cmd_combine_remapping` and :ref:`source_glob` for more information. .. _config_report: diff --git a/doc/source.rst b/doc/source.rst index cfd0e6fc..64ebd132 100644 --- a/doc/source.rst +++ b/doc/source.rst @@ -59,10 +59,10 @@ removed from the set. .. highlight:: ini -The ``include`` and ``omit`` file name patterns follow typical shell syntax: -``*`` matches any number of characters and ``?`` matches a single character. -Patterns that start with a wildcard character are used as-is, other patterns -are interpreted relative to the current directory:: +The ``include`` and ``omit`` file name patterns follow common shell syntax, +described below in :ref:`source_glob`. Patterns that start with a wildcard +character are used as-is, other patterns are interpreted relative to the +current directory:: [run] omit = @@ -77,7 +77,7 @@ The ``source``, ``include``, and ``omit`` values all work together to determine the source that will be measured. If both ``source`` and ``include`` are set, the ``include`` value is ignored -and a warning is printed on the standard output. +and a warning is issued. .. _source_reporting: @@ -103,3 +103,22 @@ reporting. Note that these are ways of specifying files to measure. You can also exclude individual source lines. See :ref:`excluding` for details. + + +.. _source_glob: + +File patterns +------------- + +File path patterns are used for include and omit, and for combining path +remapping. They follow common shell syntax: + +- ``*`` matches any number of file name characters, not including the directory + separator. + +- ``?`` matches a single file name character. + +- ``**`` matches any number of nested directory names, including none. + +- Both ``/`` and ``\`` will match either a slash or a backslash, to make + cross-platform matching easier. |