git.cworth.org Git - tar/blob - debian/tar.1

   1 .\" @(#)tar.1 1.11.1 93/19/22 PJV;
   2 .TH TAR 1 "24 Feb 2009"
   3 .SH NAME
   4 tar \- The GNU version of the tar archiving utility
   5 .SH SYNOPSIS
   6 .B tar
   7 [
   8 .B \-
   9 ]
  10 .B A \-\-catenate \-\-concatenate \||\| c \-\-create \||\| d \-\-diff \-\-compare \||\| \-\-delete \||\| r \-\-append \||\| t \-\-list \||\| u \-\-update \||\| x \-\-extract \-\-get
  11 .I [ options ]
  12 .I pathname [ pathname ... ]
  13 .SH DESCRIPTION
  14 .LP
  15 This manual page documents the GNU version of
  16 .B tar
  17 , an archiving program designed to store and extract files from
  18 an archive file known as a
  19 .IR tarfile.
  20 A
  21 .IR tarfile
  22 may be made on a tape drive, however, it is also common
  23 to write a
  24 .IR tarfile
  25 to a normal file.
  26 The first argument to
  27 .B tar
  28 must be one of the options:
  29 .BR Acdrtux ,
  30 followed by any optional functions.
  31 The final arguments to
  32 .B tar
  33 are the names of the files or directories which should be archived. The use
  34 of a directory name always implies that the subdirectories below should be
  35 included in the archive.
  36 .SH EXAMPLES
  37 .TP
  38 .B tar \-xvvf foo.tar
  39 extract foo.tar
  40 .TP
  41 .B tar \-xvvzf foo.tar.gz
  42 extract gzipped foo.tar.gz
  43 .TP
  44 .B tar \-cvvf foo.tar foo/
  45 tar contents of folder foo in foo.tar
  46 .SH "FUNCTION LETTERS"
  47 .TP
  48 .B One of the following options must be used:
  49 .TP
  50 .B \-A, \-\-catenate, \-\-concatenate
  51 append tar files to an archive
  52 .TP
  53 .B \-c, \-\-create
  54 create a new archive
  55 .TP
  56 .B \-d, \-\-diff, \-\-compare
  57 find differences between archive and file system
  58 .TP
  59 .B \-\-delete
  60 delete from the archive (not for use on mag tapes!)
  61 .TP
  62 .B \-r, \-\-append
  63 append files to the end of an archive
  64 .TP
  65 .B \-t, \-\-list
  66 list the contents of an archive
  67 .TP
  68 .B \-u, \-\-update
  69 only append files that are newer than copy in archive
  70 .TP
  71 .B \-x, \-\-extract, \-\-get
  72 extract files from an archive
  73 .SH "OTHER OPTIONS"
  74 .TP
  75 .B \-\-allow\-name\-mangling
  76 re-enable handling of GNUTYPE_NAMES which is now disabled by default
  77 .TP
  78 .B \-\-anchored
  79 force exclusion patterns to match initial subsequences
  80 .TP
  81 .B \-\-atime\-preserve
  82 don't change access times on dumped files
  83 .TP
  84 .B \-a, \-\-auto\-compress
  85 with \-\-create, selects compression algorithm basing on the suffix
  86 of the archive file name
  87 .TP
  88 .B \-b, \-\-blocking\-factor N
  89 use record size of Nx512 bytes (default N=20)
  90 .TP
  91 .B \-B, \-\-read\-full\-records
  92 reblock as we read (for reading 4.2BSD pipes)
  93 .TP
  94 .B \-\-backup[\=TYPE]
  95 back up files instead of overwriting (TYPE=numbered, existing, simple)
  96 .TP
  97 .B \-C, \-\-directory DIR
  98 change to directory DIR
  99 .TP
 100 .B \-\-checkpoint
 101 print periodic checkpoints
 102 .TP
 103 .B \-\-checkpoint\-action
 104 this action allows to specify an action to be executed upon hitting a
 105 checkpoint.  Recognized actions are: dot, echo (the default),
 106 echo\=string, ttyout\=string, exec\=cmdline, and sleep\=value.  Any number
 107 of `\-\-checkpoint\-action' options can be specified, the actions will be
 108 executed in order of their appearance in the command line.
 109 .TP
 110 .B \-\-check\-device
 111 enables comparing device numbers.  This is the default.
 112 .TP
 113 .B \-\-no\-check\-device
 114 disables comparing device numbers during preparatory stage of an
 115 incremental dump.
 116 This allows to avoid creating full dumps if the device numbers change
 117 (e.g. when using an LVM snapshot)
 118 .TP
 119 .B \-\-exclude=PATTERN
 120 exclude files matching PATTERN
 121 .TP
 122 .B \-f, \-\-file [HOSTNAME:]F
 123 use archive file or device F (otherwise value of TAPE environment variable; if unset, "\-", meaning stdin/stdout)
 124 .TP
 125 .B \-F, \-\-info\-script F, \-\-new\-volume\-script F
 126 run script at end of each tape (implies \-M)
 127 .TP
 128 .B \-\-force\-local
 129 archive file is local even if it has a colon
 130 .TP
 131 .B \-G, \-\-incremental
 132 create/list/extract old GNU-format incremental backup
 133 .TP
 134 .B \-g, \-\-listed\-incremental F
 135 create/list/extract new GNU-format incremental backup
 136 .TP
 137 .B \-\-group G
 138 set group to G while adding files
 139 .TP
 140 .B \-h, \-\-dereference
 141 don't dump symlinks; dump the files they point to
 142 .TP
 143 .B \-\-hard\-dereference
 144 during archive creation, dereferences hard links and stores the files
 145 they refer to, instead of creating usual hard link members (type '1')
 146 .TP
 147 .B \-\-help
 148 print help message
 149 .TP
 150 .B \-i, \-\-ignore\-zeros
 151 ignore blocks of zeros in archive (normally mean EOF)
 152 .TP
 153 .B \-\-ignore\-case
 154 ignore case when excluding files
 155 .TP
 156 .B \-\-ignore\-failed\-read
 157 don't exit with non-zero status on unreadable files
 158 .TP
 159 .B \-j, \-\-bzip2
 160 filter archive through bzip2, use to decompress .bz2 files.
 161 WARNING: some previous versions of tar used option \-I to
 162 filter through bzip2.  When writing scripts, use \-\-bzip2
 163 instead of \-j so that both older and newer tar versions
 164 will work.
 165 .TP
 166 .B \-k, \-\-keep\-old\-files
 167 keep existing files; don't overwrite them from archive
 168 .TP
 169 .B \-K, \-\-starting\-file F
 170 begin at file F in the archive
 171 .TP
 172 .B \-J, \-\-lzma
 173 selects LZMA compression algorithm
 174 .TP
 175 .B \-l, \-\-check\-links
 176 print a message if not all links are dumped
 177 .TP
 178 .B \-L, \-\-tape\-length N
 179 change tapes after writing N*1024 bytes
 180 .TP
 181 .B \-\-lzop
 182 filter the archive through lzop
 183 .TP
 184 .B \-m, \-\-touch
 185 don't extract file modified time
 186 .TP
 187 .BI \-\-transform " expr"
 188 applies filename transformations.
 189 The argument to this option can be a list of replace expressions, separated
 190 by semicolon (as in `sed').
 191 Filename transformations are applied to symbolic link targets during both
 192 creation and extraction.
 193 This option may be specified any number of
 194 times, the specified transofrmations will be applied in turn.
 195 .TP
 196 .B \-M, \-\-multi\-volume
 197 create/list/extract multi-volume archive
 198 .TP
 199 .B \-\-mode M
 200 set permissions to M while adding files
 201 .TP
 202 .B \-N, \-\-after\-date DATE, \-\-newer DATE
 203 only store files newer than DATE
 204 .TP
 205 .B \-\-newer\-mtime DATE
 206 only store files whose contents have changed after DATE
 207 .TP
 208 .B \-\-no\-anchored
 209 allow exclusion patterns to match any substring (the default)
 210 .TP
 211 .B \-\-no\-auto\-compress
 212 Cancels the effect of previous \-\-auto\-compress options
 213 .TP
 214 .B \-\-no\-ignore\-case
 215 match patterns case sensitively (the default)
 216 .TP
 217 .B \-\-no\-null
 218 cancels the effect of previous \-\-null option
 219 .TP
 220 .B \-\-no\-recursion
 221 do not recurse into subdirectories
 222 .TP
 223 .B \-o, \-\-no\-same\-owner
 224 extract files with owner set to current user (the default for non-root
 225 users)
 226 .TP
 227 .B \-\-no\-same\-permissions
 228 apply umask to extracted files (the default for non-root users)
 229 .TP
 230 .B \-\-no\-wildcards
 231 do not use wildcards when excluding files
 232 .TP
 233 .B \-\-no\-wildcards\-match\-slash
 234 don't let wildcards match "/" when excluding files
 235 .TP
 236 .B \-\-null
 237 for \-T, use "NUL" instead of newline as filename terminator
 238 .TP
 239 .B \-\-numeric\-owner
 240 always use numbers for user/group names
 241 .TP
 242 .B \-\-old\-archive, \-\-portability
 243 write a V7 format archive, rather than ANSI format.  These options are
 244 deprecated, please use
 245 .B \-\-format\=v7
 246 instead.
 247 .TP
 248 .B \-\-one\-file\-system
 249 stay in local file system when creating an archive
 250 .TP
 251 .B \-\-owner O
 252 set owner to O while adding files
 253 .TP
 254 .B \-O, \-\-to\-stdout
 255 extract files to standard output
 256 .TP
 257 .B \-p, \-\-same\-permissions, \-\-preserve\-permissions
 258 ignore umask when extracting files (the default for root)
 259 .TP
 260 .B \-P, \-\-absolute\-names
 261 don't strip leading `/'s from file names
 262 .TP
 263 .B \-\-posix
 264 create POSIX compliant archive.  This option is deprecated,
 265 please use
 266 .B \-\-format\=posix
 267 instead.
 268 .TP
 269 .B \-\-preserve
 270 like \-p \-s
 271 .TP
 272 .B \-R, \-\-block\-number
 273 show block number within archive with each message
 274 .TP
 275 .B \-\-record\-size SIZE
 276 use SIZE bytes per record
 277 .TP
 278 .B \-\-recursion
 279 recurse into directories (the default)
 280 .TP
 281 .B \-\-recursive\-unlink
 282 remove existing directories before extracting directories of the same
 283 name
 284 .TP
 285 .B \-\-remove\-files
 286 remove files after adding them to the archive
 287 .TP
 288 .B \-\-rsh\-command=CMD
 289 Use remote COMMAND instead of `rsh'.  This option exists so that
 290 people who use something other than the standard `rsh' (e.g., a
 291 Kerberized `rsh') can access a remote device.
 292 .TP
 293 .B \-S, \-\-sparse
 294 handle sparse files efficiently
 295 .TP
 296 .B \-s, \-\-same\-order, \-\-preserve\-order
 297 list of names to extract is sorted to match archive
 298 .TP
 299 .B \-\-same\-owner
 300 extract files with owner as specified in archive (the default for
 301 root)
 302 .TP
 303 .B \-\-show\-omitted\-dirs
 304 mention directories that are being skipped over
 305 .TP
 306 .BI \-\-strip\-components " n"
 307 Strip the given number of leading directory components
 308 .TP
 309 .B \-\-strip, \-\-strip\-components N
 310 Strips the first N components from archive members' pathnames when
 311 unpacking.
 312 .TP
 313 .B \-\-suffix SUFFIX
 314 append SUFFIX to make backup files (default ~)
 315 .TP
 316 .B \-T, \-\-files\-from F
 317 get names to extract or archive from file F
 318 .TP
 319 .B \-\-totals
 320 display total bytes written after creating an archive
 321 .TP
 322 .B \-U, \-\-unlink\-first
 323 unlink & recreate files instead of overwriting
 324 .TP
 325 .B \-\-use\-compress\-program PROG
 326 filter the archive through PROG (which must accept \-d)
 327 .TP
 328 .B \-v, \-\-verbose
 329 verbosely list files processed
 330 .TP
 331 .B \-V, \-\-label NAME
 332 create archive with volume name NAME
 333 .TP
 334 .B \-\-version
 335 print tar program version number
 336 .TP
 337 .B \-\-volno\-file F
 338 keep track of current volume (of a multi-volume archive) in F
 339 .TP
 340 .B \-w, \-\-interactive, \-\-confirmation
 341 ask for confirmation for every action
 342 .TP
 343 .B \-W, \-\-verify
 344 attempt to verify the archive after writing it
 345 .TP
 346 .B \-\-wildcards
 347 use wildcards when excluding files (the default)
 348 .TP
 349 .B \-\-wildcards\-match\-slash
 350 allow wildcards to match "/" (the default)
 351 .TP
 352 .B \-X, \-\-exclude\-from=FILE
 353 exclude files matching patterns listed in FILE
 354 .TP
 355 .B \-Z, \-\-compress, \-\-uncompress
 356 filter the archive through compress
 357 .TP
 358 .B \-z, \-\-gzip, \-\-gunzip, \-\-ungzip
 359 filter the archive through gzip
 360 .TP
 361 .B \-[0\-7][lmh]
 362 specify drive and density
 363 .SH ENVIRONMENT
 364 The behavior of tar is controlled by the following environment variables,
 365 among others:
 366 .TP
 367 .B TAPE
 368 Device or file to use for the archive if \fB--file\fR is not specified.
 369 If this environment variable is unset, use stdin or stdout instead.
 370 .TP
 371 .B TAR_OPTIONS
 372 Options to prepend to those specified on the command line, separated by
 373 whitespace.  Embedded backslashes may be used to escape whitespace or
 374 backslashes within an option.
 375 .LP
 376 In addition, the value of the blocking factor is made available to info
 377 and checkpoint scripts via environment variable
 378 .B TAR_BLOCKING_FACTOR.
 379 .SH BUGS
 380 .LP
 381 The GNU folks, in general, abhor man pages, and create info documents instead.
 382 Unfortunately, the info document describing tar is licensed under the GFDL with
 383 invariant cover texts, which violates the Debian Free Software Guidelines.  As
 384 a result, the info documentation for tar is not included in the Debian package.
 385
 386 If you want to read the complete documentation for GNU tar, please refer to
 387 the online version at
 388 .PP
 389 .ce 1
 390 <http://www.gnu.org/software/tar/manual/index.html>
 391 .PP
 392 This man page was created for the Debian distribution.  It does not describe
 393 all of the functionality of tar, and it is often out of date.  Patches to
 394 improve the coverage and/or accuracy of this man page are appreciated, and
 395 should be filed as wishlist severity bugs against the Debian tar package,
 396 not submitted to the GNU tar maintainers.