Options to control option handling in file lists.

[chaz/tar] / doc / tar.1

diff --git a/doc/tar.1 b/doc/tar.1
index ec25aa918688e7ece4c80e74611b3ffe9c406c19..4f19cffdac50b7507078f62672f1f404e28ee4c4 100644 (file)
--- a/doc/tar.1
+++ b/doc/tar.1
@@ -1,5 +1,5 @@
 .\" This file is part of GNU tar. -*- nroff -*-
 .\" This file is part of GNU tar. -*- nroff -*-

-.\" Copyright 2013 Free Software Foundation, Inc.
+.\" Copyright 2013-2014 Free Software Foundation, Inc.

 .\"
 .\" GNU tar is free software; you can redistribute it and/or modify
 .\" it under the terms of the GNU General Public License as published by
 .\"
 .\" GNU tar is free software; you can redistribute it and/or modify
 .\" it under the terms of the GNU General Public License as published by


@@ -13,7 +13,7 @@
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.

-.TH TAR 1 "January 27, 2014" "TAR" "GNU TAR Manual"
+.TH TAR 1 "August 16, 2014" "TAR" "GNU TAR Manual"

 .SH NAME
 tar \- an archiving utility
 .SH SYNOPSIS
 .SH NAME
 tar \- an archiving utility
 .SH SYNOPSIS


@@ -330,6 +330,11 @@ Don't replace existing files that are newer than their archive copies.
 \fB\-\-no\-overwrite\-dir\fR
 Preserve metadata of existing directories.
 .TP
 \fB\-\-no\-overwrite\-dir\fR
 Preserve metadata of existing directories.
 .TP

+\fB\-\-one\-top\-level\fR[\fB=\fIDIR\fR]
+Extract all files into \fIDIR\fR, or, if used without argument, into a
+subdirectory named by the base name of the archive (minus standard
+compression suffixes recognizable by \fB\-\-auto\-compress).
+.TP

 \fB\-\-overwrite\fR
 Overwrite existing files when extracting.
 .TP
 \fB\-\-overwrite\fR
 Overwrite existing files when extracting.
 .TP


@@ -342,6 +347,9 @@ Recursively remove all files in the directory prior to extracting it.
 \fB\-\-remove\-files\fR
 Remove files from disk after adding them to the archive.
 .TP
 \fB\-\-remove\-files\fR
 Remove files from disk after adding them to the archive.
 .TP

+\fB\-\-skip\-old\-files
+Don't replace existing files when extracting, silently skip over them.
+.TP

 \fB\-U\fR, \fB\-\-unlink\-first\fR
 Remove each file prior to extracting over it.
 .TP
 \fB\-U\fR, \fB\-\-unlink\-first\fR
 Remove each file prior to extracting over it.
 .TP


@@ -501,6 +509,24 @@ Try extracting files with the same ownership as exists in the archive
 .TP
 \fB\-s\fR, \fB\-\-preserve\-order\fR, \fB\-\-same\-order\fR
 Sort names to extract to match archive
 .TP
 \fB\-s\fR, \fB\-\-preserve\-order\fR, \fB\-\-same\-order\fR
 Sort names to extract to match archive

+.TP
+\fB\-\-sort=\fIORDER\fR
+When creating an archive, sort directory entries according to
+\fIORDER\fR, which is one of
+.BR none ,
+.BR name ", or"
+.BR inode .
+
+The default is \fB\-\-sort=none\fR, which stores archive members in
+the same order as returned by the operating system.
+
+Using \fB\-\-sort=name\fR ensures the member ordering in the created archive
+is uniform and reproducible.
+
+Using \fB\-\-sort=inode\fR reduces the number of disk seeks made when
+creating the archive and thus can considerably speed up archivation.
+This sorting order is supported only if the underlying system provides
+the necessary information.

 .SS Device selection and switching
 .TP
 \fB\-f\fR, \fB\-\-file\fR=\fIARCHIVE\fR
 .SS Device selection and switching
 .TP
 \fB\-f\fR, \fB\-\-file\fR=\fIARCHIVE\fR


@@ -534,7 +560,7 @@ instead.  You can do so by giving the following command line option:
 --rsh-command=/usr/bin/ssh
 .EE
 
 --rsh-command=/usr/bin/ssh
 .EE
 

-The remote mashine should have the
+The remote machine should have the

 .BR rmt (8)
 command installed.  If its pathname does not match \fBtar\fR's
 default, you can inform \fBtar\fR about the correct pathname using the
 .BR rmt (8)
 command installed.  If its pathname does not match \fBtar\fR's
 default, you can inform \fBtar\fR about the correct pathname using the


@@ -765,6 +791,15 @@ Exclude directories containing file \fBCACHEDIR.TAG\fR and the file itself.
 \fB\-\-exclude\-caches\-under\fR
 Exclude everything under directories containing \fBCACHEDIR.TAG\fR
 .TP
 \fB\-\-exclude\-caches\-under\fR
 Exclude everything under directories containing \fBCACHEDIR.TAG\fR
 .TP

+\fB\-\-exclude\-ignore=\fIFILE\fR
+Before dumping a directory, see if it contains \fIFILE\fR.
+If so, read exclusion patterns from this file.  The patterns affect
+only the directory itself.
+.TP
+\fB\-\-exclude\-ignore\-recursive=\fIFILE\fR
+Same as \fB\-\-exclude\-ignore\fR, except that patterns from
+\fIFILE\fR affect both the directory and all its subdirectories.
+.TP

 \fB\-\-exclude\-tag\fR=\fIFILE\fR
 Exclude contents of directories containing \fIFILE\fR, except for
 \fIFILE\fR itself.
 \fB\-\-exclude\-tag\fR=\fIFILE\fR
 Exclude contents of directories containing \fIFILE\fR, except for
 \fIFILE\fR itself.


@@ -778,6 +813,14 @@ Exclude everything under directories containing \fIFILE\fR.
 \fB\-\-exclude\-vcs\fR
 Exclude version control system directories.
 .TP
 \fB\-\-exclude\-vcs\fR
 Exclude version control system directories.
 .TP

+\fB\-\-exclude\-vcs\-ignores\fR
+Exclude files that match patterns read from VCS-specific ignore
+files.  Supported files are:
+.BR .cvsignore ,
+.BR .gitignore ,
+.BR .bzrignore ", and"
+.BR .hgignore .
+.TP

 \fB\-h\fR, \fB\-\-dereference\fR
 Follow symlinks; archive and dump the files they point to.
 .TP
 \fB\-h\fR, \fB\-\-dereference\fR
 Follow symlinks; archive and dump the files they point to.
 .TP


@@ -799,7 +842,7 @@ Disable the effect of the previous \fB\-\-null\fR option.
 Avoid descending automatically in directories.
 .TP
 \fB\-\-no\-unquote\fR
 Avoid descending automatically in directories.
 .TP
 \fB\-\-no\-unquote\fR

-Do not unquote filenames read with \fB\-T\fR.
+Do not unquote input file or member names.

 .TP
 \fB\-\-null\fR
 Instruct subsequent \fB\-T\fR options to read null-terminated names,
 .TP
 \fB\-\-null\fR
 Instruct subsequent \fB\-T\fR options to read null-terminated names,


@@ -827,7 +870,7 @@ unless overridden by environment variable \fBSIMPLE_BACKUP_SUFFIX\fR.
 Get names to extract or create from \fIFILE\fR.
 .TP
 \fB\-\-unquote\fR
 Get names to extract or create from \fIFILE\fR.
 .TP
 \fB\-\-unquote\fR

-Unquote filenames read with \fB\-T\fR (default).
+Unquote file or member names (default).

 .TP
 \fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
 Exclude files matching patterns listed in FILE.
 .TP
 \fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
 Exclude files matching patterns listed in FILE.


@@ -836,7 +879,7 @@ Exclude files matching patterns listed in FILE.
 \fB\-\-strip\-components\fR=\fINUMBER\fR
 Strip \fINUMBER\fR leading components from file names on extraction.
 .TP
 \fB\-\-strip\-components\fR=\fINUMBER\fR
 Strip \fINUMBER\fR leading components from file names on extraction.
 .TP

-\fB\-\-transform\fR=\fIEXPRESSION\dR, \fB\-\-xform\fR=\fIEXPRESSION\fR
+\fB\-\-transform\fR=\fIEXPRESSION\fR, \fB\-\-xform\fR=\fIEXPRESSION\fR

 Use sed replace \fIEXPRESSION\fR to transform file names.
 .SS File name matching options
 These options affect both exclude and include patterns.
 Use sed replace \fIEXPRESSION\fR to transform file names.
 .SS File name matching options
 These options affect both exclude and include patterns.


@@ -981,6 +1024,9 @@ Keywords applicable for \fBtar --create\fR:
 .HP
 Keywords applicable for \fBtar --extract\fR:
 .TP
 .HP
 Keywords applicable for \fBtar --extract\fR:
 .TP

+.B existing\-file
+"%s: skipping existing file"
+.TP

 .B timestamp
 "%s: implausibly old time stamp %s"
 .br
 .B timestamp
 "%s: implausibly old time stamp %s"
 .br