From bf3e96aa0aaba5f8e2095551498f50f1080f7f74 Mon Sep 17 00:00:00 2001
From: "sur.la.route" <christopher.pickering@keemail.me>
Date: Sat, 6 Nov 2021 01:06:49 +0100
Subject: [PATCH] docs: updated docs for #578 recommendation (#1148)

* updated docs for #578 recommendation

#578
https://github.com/nedbat/coveragepy/issues/578#issuecomment-413881957
https://bitbucket.org/suriya/coverage-xml-bug/pull-requests/1/demonstrate-a-fix-to-coverage-xml-bug/diff

also see #1146

* fixed per lint

* updated per lint
---
 doc/cmd.rst | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/doc/cmd.rst b/doc/cmd.rst
index b674e2985..5957bc11a 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -488,6 +488,44 @@ compatible with `Cobertura`_.
 
 You can specify the name of the output file with the ``-o`` switch.
 
+To include complete file paths in the output file, rather than just
+the file name, use [include] vs [source] in your ".coveragerc" file.
+
+For example, use this:
+
+.. code:: ini
+
+    [run]
+    include =
+        foo/*
+        bar/*
+
+
+which will result in
+
+.. code:: xml
+
+    <class branch-rate="0" complexity="0" filename="bar/hello.py" line-rate="1" name="hello.py">
+    <class branch-rate="0" complexity="0" filename="bar/baz/hello.py" line-rate="1" name="hello.py">
+    <class branch-rate="0" complexity="0" filename="foo/hello.py" line-rate="1" name="hello.py">
+
+in place of this:
+
+.. code:: ini
+
+    [run]
+    source =
+        foo
+        bar
+
+which may result in
+
+.. code:: xml
+
+    <class branch-rate="0" complexity="0" filename="hello.py" line-rate="1" name="hello.py">
+    <class branch-rate="0" complexity="0" filename="baz/hello.py" line-rate="1" name="hello.py">
+
+
 Other common reporting options are described above in :ref:`cmd_reporting`.