X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=e3df0c98b238cfd2326452888048598a91de80ad;hb=f86e0605d0e24d2e0424579a8310f6fb81375b92;hp=ece40f4e7cf3903ae1811e33210c6b5cf4c70e0e;hpb=2af87fa2776c8125a587a9b0c2c4fae3bf921ff7;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index ece40f4..e3df0c9 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -2608,6 +2608,19 @@ tag file, but still dump the directory node itself. 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} @@ -2633,7 +2646,16 @@ Exclude from dump any directory containing file named @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} @@ -3087,15 +3109,17 @@ directories that are on different file systems from the current directory. @opsummary{one-top-level} -@item --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. The -name of the new directory will be equal to the name of the archive with the -extension stripped off. If any archive names (after transformations from -@option{--transform} and @option{--strip-components}) do not already begin with -it, the new directory will be prepended to the names immediately before -extraction. Recognized extensions are @samp{.tar}, @samp{.taz}, @samp{.tbz}, -@samp{.tb2}, @samp{.tgz}, @samp{.tlz} and @samp{.txz}. +(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 @@ -3317,6 +3341,27 @@ The @option{--warning=existing-file} option can be used together with 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 @@ -3625,7 +3670,7 @@ successfully. For example, @w{@samp{tar --version}} might print: @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 . This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. @@ -4028,7 +4073,7 @@ 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 %@var{c} +@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 @@ -7358,6 +7403,77 @@ which is difficult to catch using text editors. 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 @@ -7370,6 +7486,7 @@ However, empty lines are OK. @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