[Reproducible-commits] [dpkg] 02/63: man: Clarify pathname filters behavior

[Jérémy Bobbio]

This is an automated email from the git hooks/post-receive script.

lunar pushed a commit to branch pu/buildinfo
in repository dpkg.

commit 5540c4d2e979ef35a118dfa1b76f62536db96943
Author: Guillem Jover <guillem at debian.org>
Date:   Fri Feb 5 18:22:08 2016 +0100

    man: Clarify pathname filters behavior
    
    Document a bit how the filters work internally so that their behavior
    is more easily understood.
    
    Closes: #811267
---
 debian/changelog |  2 ++
 man/dpkg.1       | 15 ++++++++++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/debian/changelog b/debian/changelog
index e84b5e5..9052fe7 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -46,6 +46,8 @@ dpkg (1.18.5) UNRELEASED; urgency=medium
     - Document Source field version in deb-control(5).
     - Add new deb822(5) man page.
     - Document and improve C/C++ programs exit codes in man pages.
+    - Clarify dpkg --path-exclude/--path-include pathname filter behavior.
+      Closes: #811267
 
   [ Updated programs translations ]
   * Portuguese (Miguel Figueiredo).
diff --git a/man/dpkg.1 b/man/dpkg.1
index 026e777..4c61f7a 100644
--- a/man/dpkg.1
+++ b/man/dpkg.1
@@ -698,7 +698,7 @@ starts a character class, which can contain a list of characters, ranges
 and complementations. See \fBglob\fP(7) for detailed information about
 globbing. Note: the current implementation might re-include more directories
 and symlinks than needed, to be on the safe side and avoid possible unpack
-failures, future work might fix this.
+failures; future work might fix this.
 
 This can be used to remove all paths except some particular ones; a typical
 case is:
@@ -713,6 +713,19 @@ to remove all documentation files except the copyright files.
 These two options can be specified multiple times, and interleaved with
 each other. Both are processed in the given order, with the last rule that
 matches a file name making the decision.
+
+The filters are applied when unpacking the binary packages, and as such
+only have knowledge of the type of object currently being filtered
+(e.g. a normal file or a directory) and have not visibility of what
+objects will come next.
+Because these filters have side effects (in contrast to \fBfind\fP(1)
+filters), excluding an exact pathname that happens to be a directory object
+like \fI/usr/share/doc\fP will not have the desired result, and only that
+pathname will be excluded (which could be automatically reincluded if the
+code sees the need).
+Any subsequent files contained within that directory will fail to unpack.
+
+Hint: make sure the globs are not expanded by your shell.
 .TP
 .BI \-\-verify\-format " format-name"
 Sets the output format for the \fB\-\-verify\fP command (since dpkg 1.17.2).

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/reproducible/dpkg.git