[tar/f20] docs: document mistakes in --exclude

[Pavel Raiskup]

commit 3c5b275e3a900180473ac9f8cf6368f615db44d7
Author: Pavel Raiskup <praiskup at redhat.com>
Date:   Mon Mar 31 14:53:30 2014 +0200

    docs: document mistakes in --exclude
    
    Related: #903666
    Version: 1.26-31

 tar-1.26-document-exclude-mistakes.patch |   92 ++++++++++++++++++++++++++++++
 tar.spec                                 |   13 ++++-
 2 files changed, 103 insertions(+), 2 deletions(-)
---
diff --git a/tar-1.26-document-exclude-mistakes.patch b/tar-1.26-document-exclude-mistakes.patch
new file mode 100644
index 0000000..e3de9b6
--- /dev/null
+++ b/tar-1.26-document-exclude-mistakes.patch
@@ -0,0 +1,92 @@
+commit 2c7692bd81946100244f022fdfa47e91afd44632 (document_exclude_mistake)
+Author:     Pavel Raiskup <praiskup at redhat.com>
+AuthorDate: Mon Mar 31 14:22:56 2014 +0200
+Commit:     Pavel Raiskup <praiskup at redhat.com>
+CommitDate: Mon Mar 31 14:30:02 2014 +0200
+
+    docs: document common mistake with --exclude
+    
+    The default settings of --exclude wildcard matching leads usually
+    to --no-wildcards-match-slash option but there is not obvious that
+    users should also turn --anchored option on.
+    
+    * doc/tar.texi: Describe.
+
+diff --git a/doc/tar.texi b/doc/tar.texi
+index e3df0c9..395f24c 100644
+--- a/doc/tar.texi
++++ b/doc/tar.texi
+@@ -7906,6 +7906,73 @@ The following table summarizes pattern-matching default values:
+ @item Exclusion @tab @option{--wildcards --no-anchored --wildcards-match-slash}
+ @end multitable
+ 
++ at subsubsection Wildcard matching confusion
++Using of @option{--[no-]anchored} and @option{--[no-]wildcards-match-slash}
++was proven to make confusion.  The reasons for this are probably different
++default setting for inclusion and exclusion patterns (in general: you shouldn't
++rely on defaults if possible) and maybe also because when using any of these two
++options, the position on command line matters (these options should be placed
++prior to the member name on command line).
++
++ at noindent
++Consider following directory structure:
++
++ at smallexample
++$ find path/ | sort
++path/
++path/file1
++path/file2
++path/subpath
++path/subpath/file1
++path/subpath/file2
++path/subpath2
++path/subpath2/file1
++path/subpath2/file2
++ at end smallexample
++
++ at noindent
++To archive full directory @samp{path} except all files named @samp{file1} may be
++reached by any of the two following commands:
++
++ at smallexample
++$ tar -cf a.tar --no-wildcards-match-slash --no-anchored path \
++      --exclude='*/file1'
++$ tar -cf a.tar --wildcards-match-slash path --exclude='*/file1'
++ at end smallexample
++
++ at noindent
++Note that the @option{--wildcards-match-slash} and @option{--no-anchored} may be
++omitted as it is default for @option{--exclude}.  Anyway, we usually want just
++concrete file (or rather subset of files with the same name).  Assume we want
++exclude only files named @samp{file1} from the first subdirectory level.
++Following command obviously does not work (it still excludes all files having
++ at samp{file1} name):
++
++ at smallexample
++$ tar -cf a.tar --no-wildcards-match-slash path \
++    --exclude='*/file1' | sort
++ at end smallexample
++
++ at noindent
++This is because the @option{--no-anchored} is set by default for exclusion.
++What you need to fix is to put @option{--anchored} before pathname:
++
++ at smallexample
++$ tar -cvf a.tar --no-wildcards-match-slash --anchored path \
++    --exclude='*/file1' | sort
++path/
++path/file2
++path/subpath1/
++path/subpath1/file1
++path/subpath1/file2
++path/subpath2/
++path/subpath2/file1
++path/subpath2/file2
++ at end smallexample
++
++ at noindent
++Similarly you can exclude second level by specifying @samp{*/*/file1}.
++
+ @node quoting styles
+ @section Quoting Member Names
+ 
diff --git a/tar.spec b/tar.spec
index 3432d04..4d01dde 100644
--- a/tar.spec
+++ b/tar.spec
@@ -5,7 +5,7 @@ Summary: A GNU file archiving program
 Name: tar
 Epoch: 2
 Version: 1.26
-Release: 30%{?dist}
+Release: 31%{?dist}
 License: GPLv3+
 Group: Applications/Archiving
 URL: http://www.gnu.org/software/tar/
@@ -116,7 +116,6 @@ Patch17: tar-1.26-docu-xattrs.patch
 # ~> still downstream
 #    http://lists.gnu.org/archive/html/bug-tar/2013-05/msg00020.html
 # ~> #965969
-
 Patch18: tar-1.26-xattrs-include-implies-xattrs.patch
 
 # If the 'st_size' != 0 && count(blocks) == 0 && st_size < size(block), this
@@ -135,6 +134,12 @@ Patch20: tar-1.26-compare-incremental.patch
 #    http://www.mail-archive.com/bug-tar@gnu.org/msg04294.html
 Patch21: tar-1.26-testsuite-diff-incr.patch
 
+# Document exclude mistakes with --no-wildcards-match-slash & --anchored
+# ~> downstream
+#    http://www.mail-archive.com/bug-tar@gnu.org/msg04488.html
+# ~> related to #903666
+Patch22: tar-1.26-document-exclude-mistakes.patch
+
 # Silence gcc warnings
 # ~> upstream tar: 17f99bc6f, 5bb0433
 # ~> upstream paxutils: 0b3d84a0
@@ -194,6 +199,7 @@ the rmt package on the remote box.
 %patch19 -p1 -b .sparse-stat-detection
 %patch20 -p1 -b .compare-and-incremental
 %patch21 -p1 -b .testsuite-diff-incr
+%patch22 -p1 -b .testsuite-diff-incr
 %patch999 -p1 -b .silence-gcc
 
 autoreconf -v
@@ -253,6 +259,9 @@ fi
 %{_infodir}/tar.info*
 
 %changelog
+* Tue Apr 01 2014 Pavel Raiskup <praiskup at redhat.com> - 1.26-31
+- document --exclude mistakes (#903666)
+
 * Thu Dec 12 2013 Pavel Raiskup <praiskup at redhat.com> - 1.26-30
 - don't add git-hashes to patches
 - fix --compare with --listed-incremental (#1040702)