Exclude from dump any directory containing a valid cache directory
tag file. @xref{exclude}.
+@opsummary{exclude-ignore}
+@item --exclude-ignore=@var{file}
+Before dumping a directory, @command{tar} checks if it contains
+@var{file}. If so, exclusion patterns are read from this file.
+The patterns affect only the directory itself. @xref{exclude}.
+
+@opsummary{exclude-ignore-recursive}
+@item --exclude-ignore-recursive=@var{file}
+Before dumping a directory, @command{tar} checks if it contains
+@var{file}. If so, exclusion patterns are read from this file.
+The patterns affect the directory and all itssubdirectories.
+@xref{exclude}.
+
@opsummary{exclude-tag}
@item --exclude-tag=@var{file}
Exclude from dump directories and files, that are internal for some
widely used version control systems.
-@xref{exclude,,exclude-vcs}.
+@xref{exclude-vcs}.
+
+@opsummary{exclude-vcs-ignores}
+@item --exclude-vcs-ignores
+Exclude files that match patterns read from VCS-specific ignore
+files. Supported files are: @file{.cvsignore}, @file{.gitignore},
+@file{.bzrignore}, and @file{.hgignore}. The semantics of each file
+is the same as for the corresponding VCS, e.g. patterns read from
+@file{.gitignore} affect the directory and all its subdirectories.
+@xref{exclude-vcs-ignores}.
@opsummary{file}
@item --file=@var{archive}
directories that are on different file systems from the current
directory.
+@opsummary{one-top-level}
+@item --one-top-level[=@var{dir}]
+Tells @command{tar} to create a new directory beneath the extraction directory
+(or the one passed to @option{-C}) and use it to guard against
+tarbombs. In the absence of @var{dir} argument, the name of the new directory
+will be equal to the base name of the archive (file name minus the
+archive suffix, if recognized). Any member names that do not begin
+with that directory name (after
+transformations from @option{--transform} and
+@option{--strip-components}) will be prefixed with it. Recognized
+file name suffixes are @samp{.tar}, and any compression suffixes
+recognizable by @xref{--auto-compress}.
+
@opsummary{overwrite}
@item --overwrite
this option to produce warning messages about existing old files
(@pxref{warnings}).
+@opsummary{sort}
+@item --sort=@var{order}
+Specify the directory sorting order when reading directories.
+@var{Order} may be one of the following:
+
+@table @samp
+@item none
+No directory sorting is performed. This is the default.
+
+@item name
+Sort the directory entries on name. The operating system may deliver
+directory entries in a more or less random order, and sorting them
+makes archive creation reproducible.
+
+@item inode
+Sort the directory entries on inode number. Sorting directories on
+inode number may reduce the amount of disk seek operations when
+creating an archive for some file systems.
+
+@end table
+
@opsummary{sparse}
@item --sparse
@itemx -S
@smallexample
tar (GNU tar) @value{VERSION}
-Copyright (C) 2013 Free Software Foundation, Inc.
+Copyright (C) 2013-2014 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
@end smallexample
The @samp{%s} and @samp{%u} in the above example are
-@dfn{meta-characters}. The @samp{%s} meta-character is replaced with
+@dfn{format specifiers}. The @samp{%s} specifier is replaced with
the @dfn{type} of the checkpoint: @samp{write} or
@samp{read} (or a corresponding translated version in locales other
-than @acronym{POSIX}). The @samp{%u} meta-character is replaced with
+than @acronym{POSIX}). The @samp{%u} specifier is replaced with
the ordinal number of the checkpoint. Thus, the above example could
produce the following output when used with the @option{--create}
option:
tar: Hit write checkpoint #30
@end smallexample
-Aside from meta-character expansion, the message string is subject to
+The complete list of available format specifiers follows. Some of
+them can take optional arguments. These arguments, if given, are
+supplied in curly braces between the percent sign and the specifier
+letter.
+
+@table @samp
+@item %s
+Print type of the checkpoint (@samp{write} or @samp{read}).
+
+@item %u
+Print number of the checkpoint.
+
+@item %@{r,w,d@}T
+Print number of bytes transferred so far and approximate transfer
+speed. Optional arguments supply prefixes to be used before number
+of bytes read, written and deleted, correspondingly. If absent,
+they default to @samp{R}. @samp{W}, @samp{D}. Any or all of them can
+be omitted, so, that e.g. @samp{%@{@}T} means to print corresponding
+statistics without any prefixes. Any surplus arguments, if present,
+are silently ignored.
+
+@example
+$ @kbd{tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c}
+tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0
+tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240
+@end example
+
+@noindent
+See also the @samp{totals} action, described below.
+
+@item %@{@var{fmt}@}t
+Output current local time using @var{fmt} as format for @command{strftime}
+(@pxref{strftime, strftime,,strftime(3), strftime(3) man page}). The
+@samp{@{@var{fmt}@}} part is optional. If not present, the default
+format is @samp{%c}, i.e. the preferred date and time representation
+for the current locale.
+
+@item %@{@var{n}@}*
+Pad output with spaces to the @var{n}th column. If the
+@samp{@{@var{n}@}} part is omitted, the current screen width
+is assumed.
+
+@item %c
+This is a shortcut for @samp{%@{%Y-%m-%d %H:%M:%S@}t: %ds, %@{read,wrote@}T%*\r},
+intended mainly for use with @samp{ttyout} action (see below).
+@end table
+
+Aside from format expansion, the message string is subject to
@dfn{unquoting}, during which the backslash @dfn{escape sequences} are
replaced with their corresponding @acronym{ASCII} characters
(@pxref{escape sequences}). E.g. the following action will produce an
line, overwriting any previous message:
@smallexample
---checkpoint-action="ttyout=\rHit %s checkpoint #%u"
+--checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r"
+@end smallexample
+
+@noindent
+Notice the use of @samp{%*} specifier to clear out any eventual
+remains of the prior output line. As as more complex example,
+consider this:
+
+@smallexample
+--checkpoint-action=ttyout='%@{%Y-%m-%d %H:%M:%S@}t (%d sec): #%u, %T%*\r'
@end smallexample
+@noindent
+This prints the current local time, number of seconds expired since
+tar was started, the checkpoint ordinal number, transferred bytes and
+average computed I/O speed.
+
@cindex @code{dot}, checkpoint action
Another available checkpoint action is @samp{dot} (or @samp{.}). It
instructs @command{tar} to print a single dot on the standard listing
be abbreviated by placing a dot in front of the checkpoint frequency,
as shown in the previous section.
+@cindex @code{totals}, checkpoint action
+The @samp{totals} action prints the total number of bytes transferred
+so far. The format of the data is the same as for the
+@option{--totals} option (@pxref{totals}). See also @samp{%T} format
+specifier of the @samp{echo} or @samp{ttyout} action.
+
@cindex @code{sleep}, checkpoint action
Yet another action, @samp{sleep}, pauses @command{tar} for a specified
amount of seconds. The following example will stop for 30 seconds at each
However, empty lines are OK.
+@cindex VCS, excluding patterns from ignore files
+@cindex VCS, ignore files
+@cindex CVS, ignore files
+@cindex Git, ignore files
+@cindex Bazaar, ignore files
+@cindex Mercurial, ignore files
+When archiving directories that are under some version control system (VCS),
+it is often convenient to read exclusion patterns from this VCS'
+ignore files (e.g. @file{.cvsignore}, @file{.gitignore}, etc.) The
+following options provide such possibilty:
+
+@table @option
+@anchor{exclude-vcs-ignores}
+@opindex exclude-vcs-ignores
+@item --exclude-vcs-ignores
+Before archiving a directory, see if it contains any of the following
+files: @file{cvsignore}, @file{.gitignore}, @file{.bzrignore}, or
+@file{.hgignore}. If so, read ignore patterns from these files.
+
+The patterns are treated much as the corresponding VCS would treat
+them, i.e.:
+
+@table @file
+@findex .cvsignore
+@item .cvsignore
+Contains shell-style globbing patterns that apply only to the
+directory where this file resides. No comments are allowed in the
+file. Empty lines are ignored.
+
+@findex .gitignore
+@item .gitignore
+Contains shell-style globbing patterns. Applies to the directory
+where @file{.gitfile} is located and all its subdirectories.
+
+Any line beginning with a @samp{#} is a comment. Backslash escapes
+the comment character.
+
+@findex .bzrignore
+@item .bzrignore
+Contains shell globbing-patterns and regular expressions (if prefixed
+with @samp{RE:}@footnote{According to the Bazaar docs,
+globbing-patterns are Korn-shell style and regular expressions are
+perl-style. As of @GNUTAR{} version @value{VERSION}, these are
+treated as shell-style globs and posix extended regexps. This will be
+fixed in future releases.}. Patterns affect the directory and all its
+subdirectories.
+
+Any line beginning with a @samp{#} is a comment.
+
+@findex .hgignore
+@item .hgignore
+Contains posix regular expressions@footnote{Support for perl-style
+regexps will appear in future releases.}. The line @samp{syntax:
+glob} switches to shell globbing patterns. The line @samp{syntax:
+regexp} switches back. Comments begin with a @samp{#}. Patterns
+affect the directory and all its subdirectories.
+@end table
+
+@opindex exclude-ignore
+@item --exclude-ignore=@var{file}
+Before dumping a directory, @command{tar} checks if it contains
+@var{file}. If so, exclusion patterns are read from this file.
+The patterns affect only the directory itself.
+
+@opindex exclude-ignore-recursive
+@item --exclude-ignore-recursive=@var{file}
+Same as @option{--exclude-ignore}, except that the patterns read
+affect both the directory where @var{file} resides and all its
+subdirectories.
+@end table
+
@table @option
@cindex version control system, excluding files
@cindex VCS, excluding files
@cindex Arch, excluding files
@cindex Mercurial, excluding files
@cindex Darcs, excluding files
+@anchor{exclude-vcs}
@opindex exclude-vcs
@item --exclude-vcs
Exclude files and directories used by following version control
@subsection Ustar Archive Format
@cindex ustar archive format
-Archive format defined by @acronym{POSIX}.1-1988 specification is called
-@code{ustar}. Although it is more flexible than the V7 format, it
+The archive format defined by the @acronym{POSIX}.1-1988 specification is
+called @code{ustar}. Although it is more flexible than the V7 format, it
still has many restrictions (@pxref{Formats,ustar}, for the detailed
description of @code{ustar} format). Along with V7 format,
@code{ustar} format is a good choice for archives intended to be read
with other implementations of @command{tar}.
-To create archive in @code{ustar} format, use @option{--format=ustar}
-option in conjunction with the @option{--create} (@option{-c}).
+To create an archive in @code{ustar} format, use the @option{--format=ustar}
+option in conjunction with @option{--create} (@option{-c}).
@node gnu
@subsection @acronym{GNU} and old @GNUTAR{} format
SunOS and HP-UX @command{tar} fail to accept archives created using
@GNUTAR{} and containing non-@acronym{ASCII} file names, that
-is, file names having characters with the eight bit set, because they
+is, file names having characters with the eighth bit set, because they
use signed checksums, while @GNUTAR{} uses unsigned
checksums while creating archives, as per @acronym{POSIX} standards. On
-reading, @GNUTAR{} computes both checksums and
-accepts any. It is somewhat worrying that a lot of people may go
+reading, @GNUTAR{} computes both checksums and accepts either of them.
+It is somewhat worrying that a lot of people may go
around doing backup of their files using faulty (or at least
non-standard) software, not learning about it until it's time to
restore their missing files with an incompatible file extractor, or
vice versa.
-@GNUTAR{} computes checksums both ways, and accept
-any on read, so @acronym{GNU} tar can read Sun tapes even with their
+@GNUTAR{} computes checksums both ways, and accepts either of them
+on read, so @acronym{GNU} tar can read Sun tapes even with their
wrong checksums. @GNUTAR{} produces the standard
checksum, however, raising incompatibilities with Sun. That is to
say, @GNUTAR{} has not been modified to
started computing checksums wrongly. When they later realized their
mistake, they merely decided to stay compatible with it, and with
themselves afterwards. Presumably, but I do not really know, HP-UX
-has chosen that their @command{tar} archives to be compatible with Sun's.
+has chosen their @command{tar} archives to be compatible with Sun's.
The current standards do not favor Sun @command{tar} format. In any
case, it now falls on the shoulders of SunOS and HP-UX users to get
a @command{tar} able to read the good archives they receive.
projects / debian / tar / blobdiff