.\"
.\" 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 15, 2024" "TAR" "GNU TAR Manual"
+.TH TAR 1 "June 7, 2024" "TAR" "GNU TAR Manual"
.SH NAME
tar \- an archiving utility
.SH SYNOPSIS
\fBtar\fR {\fBA\fR|\fBc\fR|\fBd\fR|\fBr\fR|\fBt\fR|\fBu\fR|\fBx\fR}\
[\fBGnSkUWOmpsMBiajJzZhPlRvwo\fR] [\fIARG\fR...]
.SS UNIX-style usage
-.sp
\fBtar\fR \fB\-A\fR [\fIOPTIONS\fR] \fB\-f\fR \fIARCHIVE\fR \fIARCHIVE\fR...
.sp
\fBtar\fR \fB\-c\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
.sp
\fBtar\fR \fB\-x\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
.SS GNU-style usage
-.sp
\fBtar\fR {\fB\-\-catenate\fR|\fB\-\-concatenate\fR} [\fIOPTIONS\fR] \fB\-\-file\fR \fIARCHIVE\fR \fIARCHIVE\fR...
.sp
\fBtar\fR \fB\-\-create\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
.B tar
is an archiving program designed to store multiple files in a single
file (an \fBarchive\fR), and to manipulate such archives. The archive
-can be either a regular file or a device (e.g. a tape drive, hence the name
+can be either a regular file or a device (e.g., a tape drive, hence the name
of the program, which stands for \fBt\fRape \fBar\fRchiver), which can
be located either on the local or on a remote machine.
-.PP
-
.SS Option styles
Options to GNU \fBtar\fR can be given in three different styles.
In
whitespace, as in \fB\-g/tmp/snar.db\fR.
.PP
Any number of options not taking arguments can be
-clustered together after a single dash, e.g. \fB\-vkp\fR. An option
+clustered together after a single dash, e.g.\& \fB\-vkp\fR. An option
that takes an argument (whether mandatory or optional) can appear at
-the end of such a cluster, e.g. \fB\-vkpf a.tar\fR.
+the end of such a cluster, e.g.\& \fB\-vkpf a.tar\fR.
.PP
The example command above written in the
.B short-option style
could look like:
.PP
.EX
-tar -cvf etc.tar /etc
+tar \-cvf etc.tar /etc
.EE
or
.EX
-tar -c -v -f etc.tar /etc
+tar \-c \-v \-f etc.tar /etc
.EE
.PP
In
Here are several ways of writing the example command in this style:
.PP
.EX
-tar --create --file etc.tar --verbose /etc
+tar \-\-create \-\-file etc.tar \-\-verbose /etc
.EE
or (abbreviating some options):
.EX
-tar --cre --file=etc.tar --verb /etc
+tar \-\-cre \-\-file=etc.tar \-\-verb /etc
.EE
.PP
The options in all three styles can be intermixed, although doing so
Extract files from an archive. Arguments are optional. When given,
they specify names of the archive members to be extracted.
.TP
-.TP
\fB\-\-show\-defaults\fR
Show built-in defaults for various \fBtar\fR options and exit.
.TP
Assume the archive is seekable. Normally \fBtar\fR determines
automatically whether the archive can be seeked or not. This option
is intended for use in cases when such recognition fails. It takes
-effect only if the archive is open for reading (e.g. with
+effect only if the archive is open for reading (e.g., with
.B \-\-list
or
.B \-\-extract
The name of the archive \fBtar\fR is processing.
.TP
.B TAR_BLOCKING_FACTOR
-Current blocking factor, i.e. number of 512-byte blocks in a record.
+Current blocking factor, i.e., number of 512-byte blocks in a record.
.TP
.B TAR_VOLUME
Ordinal number of the volume \fBtar\fR is processing (set if
.B \-\-selinux
Enable SELinux context support.
.TP
-.B \-\-no-selinux
+.B \-\-no\-selinux
Disable SELinux context support.
.TP
.B \-\-xattrs
.TP
.BI \-\-xattrs\-exclude= PATTERN
Specify the exclude pattern for xattr keys. \fIPATTERN\fR is a globbing
-pattern, e.g. \fB\-\-xattrs\-exclude='user.*'\fR to include only
+pattern, e.g.\& \fB\-\-xattrs\-exclude='user.*'\fR to include only
attributes from the user namespace.
.TP
.BI \-\-xattrs\-include= PATTERN
pathname, e.g.:
.EX
---file=remotehost:/dev/sr0
+\-\-file=remotehost:/dev/sr0
.EE
An optional username can be prefixed to the hostname, placing a \fB@\fR
instead. You can do so by giving the following command line option:
.EX
---rsh-command=/usr/bin/ssh
+\-\-rsh-command=/usr/bin/ssh
.EE
The remote machine should have the
The name of the archive \fBtar\fR is processing.
.TP
.B TAR_BLOCKING_FACTOR
-Current blocking factor, i.e. number of 512-byte blocks in a record.
+Current blocking factor, i.e., number of 512-byte blocks in a record.
.TP
.B TAR_VOLUME
Ordinal number of the volume \fBtar\fR is processing (set if
\fB\-\-record\-size\fR=\fINUMBER\fR
Set record size. \fINUMBER\fR is the number of bytes per record. It
must be multiple of \fB512\fR. It can can be suffixed with a \fBsize
-suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
+suffix\fR, e.g.\& \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
subsection
.BR "Size suffixes" ,
for a list of valid suffixes.
.TP
.BR never ", " simple
Always make simple backups
-.RS
.RE
-
+.IP
If \fICONTROL\fR is not given, the value is taken from the
.B VERSION_CONTROL
environment variable. If it is not set, \fBexisting\fR is assumed.
-.RE
.TP
\fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR
Change to \fIDIR\fR before performing any operations. This option is
-order-sensitive, i.e. it affects all options that follow.
+order-sensitive, i.e., it affects all options that follow.
.TP
\fB\-\-exclude\fR=\fIPATTERN\fR
Exclude files matching \fIPATTERN\fR, a
except for the tag file itself. The \fBCACHEDIR.TAG\fR file must be
a regular file whose content begins with the following 43 characters:
.IP
+
.RS
.EX
Signature: 8a477f597d28d172789f06886806bc55
Get names to extract or create from \fIFILE\fR.
Unless specified otherwise, the \fIFILE\fR must contain a list of
-names separated by ASCII \fBLF\fR (i.e. one name per line). The
+names separated by ASCII \fBLF\fR (i.e., one name per line). The
names read are handled the same way as command line arguments. They
undergo quote removal and word splitting, and any string that starts
with a \fB\-\fR is handled as \fBtar\fR command line option.
starts with a dash. File lists are supplied with the
\fB\-\-files\-from\fR (\fB\-T\fR) option. The default behavior is to
handle names supplied in file lists as if they were typed in the
-command line, i.e. any names starting with a dash are treated as
+command line, i.e., any names starting with a dash are treated as
\fBtar\fR options. The \fB\-\-verbatim\-files\-from\fR option
disables this behavior.
.B alone-zero-block
"A lone zero block at %s"
.HP
-Keywords applicable for \fBtar --create\fR:
+Keywords applicable for \fBtar \-\-create\fR:
.TP
.B cachedir
"%s: contains a cache directory tag %s; %s"
.B \-\-ignore\-failed\-read
option.
.HP
-Keywords applicable for \fBtar --extract\fR:
+Keywords applicable for \fBtar \-\-extract\fR:
.TP
.B existing\-file
"%s: skipping existing file"
you can get when using this warning is:
.EX
-$ tar --warning=decompress-program -x -f archive.Z
+$ tar \-\-warning=decompress-program \-x \-f archive.Z
tar (child): cannot run compress: No such file or directory
tar (child): trying gzip
.EE
When creating, same as \fB\-\-old\-archive\fR. When extracting, same
as \fB\-\-no\-same\-owner\fR.
.SS Size suffixes
-.sp
.nf
.ta 8n 18n 42n
.ul
T Terabytes \fISIZE\fR x 1024^4
w Words \fISIZE\fR x 2
.fi
-.PP
.SH "RETURN VALUE"
Tar's exit code indicates whether it was able to successfully perform
the requested operation, and if not, what kind of error occurred.
.I Some files differ.
If \fBtar\fR was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR)
command line option, this means that some files in the archive differ
-from their disk counterparts. If \fBtar\fR was given one of the \fB\-\-create\fR,
-\fB\-\-append\fR or \fB\-\-update\fR options, this exit code means
-that some files were changed while being archived and so the resulting
-archive does not contain the exact copy of the file set.
+from their disk counterparts. If \fBtar\fR was given one of the
+\fB\-\-create\fR, \fB\-\-append\fR or \fB\-\-update\fR options, this
+exit code means that some files were changed while being archived and
+so the resulting archive does not contain the exact copy of the file
+set.
.TP
.B 2
.I Fatal error.
exited with a nonzero exit code,
.B tar
itself exits with that code as well. This can happen, for example, if
-a compression option (e.g. \fB\-z\fR) was used and the external
+a compression option (e.g.\& \fB\-z\fR) was used and the external
compressor program failed. Another example is
.B rmt
failure during backup to a remote device.