X-Git-Url: https://git.brokenzipper.com/gitweb?a=blobdiff_plain;ds=sidebyside;f=doc%2Ftar.texi;h=1bbb5b7a09a97498d70200a486fefda029257d34;hb=e2dbba2f07a403fbdda06efea93b79be910a1402;hp=d76ec5163114f9ad3cb0eb8a5b30e9dcb14809d8;hpb=6e2760f7d73d86809503c767b5d167d3e89556c8;p=chaz%2Ftar

diff --git a/doc/tar.texi b/doc/tar.texi
index d76ec51..1bbb5b7 100644
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -6932,7 +6932,7 @@ replacement for each file name part that matches @var{regexp}.  Both
 @var{regexp} and @var{replace} are described in detail in
 @ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
 
-The supported @var{flags} are:
+Supported @var{flags} are:
 
 @table @samp
 @item g
@@ -6946,6 +6946,17 @@ Use case-insensitive matching
 @var{regexp} is an @dfn{extended regular expression} (@pxref{Extended
 regexps, Extended regular expressions, Extended regular expressions,
 sed, GNU sed}.
+
+@item @var{number}
+Only replace the @var{number}th match of the @var{regexp}.
+
+Note: the @var{posix} standard does not specify what should happen
+when you mix the @samp{g} and @var{number} modifiers.  @GNUTAR{}
+follows the GNU @command{sed} implementation in this regard, so
+the the interaction is defined to be: ignore matches before the
+@var{number}th, and then match and replace all matches from the
+@var{number}th on.
+                                   
 @end table
 
 Any delimiter can be used in lieue of @samp{/}, the only requirement being
@@ -6979,26 +6990,26 @@ Here are several examples of @option{--transform} usage:
 @item Extract @file{usr/} hierarchy into @file{usr/local/}:
 
 @smallexample
-$ @kbd{tar --transform='s,usr/,usr/local/,' -x arch.tar}
+$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar}
 @end smallexample
 
 @item Strip two leading directory components (equivalent to
 @option{--strip-components=2}):
 
 @smallexample
-$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x arch.tar}
+$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
 @end smallexample
 
 @item Prepend @file{/prefix/}  to each file name:
 
 @smallexample
-$ @kbd{tar --transform 's,^,/prefix/,' -x arch.tar}
+$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
 @end smallexample
 
 @item Convert each file name to lower case:
 
 @smallexample
-$ @kbd{tar --transform 's/.*/\L&/' -x arch.tar}
+$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
 @end smallexample
 
 @end enumerate
@@ -7019,6 +7030,10 @@ To test @option{--transform} effect we suggest to use
 $ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \
        --verbose --show-transformed-names /}
 @end smallexample
+
+If both @option{--strip-components} and @option{--transform} are used
+together, then @option{--transform} is applied first, and the required
+number of components is then stripped from its result.
     
 @node after
 @section Operating Only on New Files