tar/tar.1

   1 .\" @(#)tar.1 1.11.1 93/19/22 PJV;
   2 .TH TAR 1 "15 May 2006"
   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 \-b, \-\-blocking\-factor N
  85 use record size of Nx512 bytes (default N=20)
  86 .TP
  87 .B \-B, \-\-read\-full\-records
  88 reblock as we read (for reading 4.2BSD pipes)
  89 .TP
  90 .B \-\-backup[\=TYPE]
  91 back up files instead of overwriting (TYPE=numbered, existing, simple)
  92 .TP
  93 .B \-C, \-\-directory DIR
  94 change to directory DIR
  95 .TP
  96 .B \-\-checkpoint
  97 print periodic checkpoints
  98 .TP
  99 .B \-\-exclude=PATTERN
 100 exclude files matching PATTERN
 101 .TP
 102 .B \-f, \-\-file [HOSTNAME:]F
 103 use archive file or device F (default "\-", meaning stdin/stdout)
 104 .TP
 105 .B \-F, \-\-info\-script F, \-\-new\-volume\-script F
 106 run script at end of each tape (implies \-M)
 107 .TP
 108 .B \-\-force\-local
 109 archive file is local even if it has a colon
 110 .TP
 111 .B \-G, \-\-incremental
 112 create/list/extract old GNU-format incremental backup
 113 .TP
 114 .B \-g, \-\-listed\-incremental F
 115 create/list/extract new GNU-format incremental backup
 116 .TP
 117 .B \-\-group G
 118 set group to G while adding files
 119 .TP
 120 .B \-h, \-\-dereference
 121 don't dump symlinks; dump the files they point to
 122 .TP
 123 .B \-\-help
 124 print help message
 125 .TP
 126 .B \-i, \-\-ignore\-zeros
 127 ignore blocks of zeros in archive (normally mean EOF)
 128 .TP
 129 .B \-\-ignore\-case
 130 ignore case when excluding files
 131 .TP
 132 .B \-\-ignore\-failed\-read
 133 don't exit with non-zero status on unreadable files
 134 .TP
 135 .B \-j, \-\-bzip2
 136 filter archive through bzip2, use to decompress .bz2 files.
 137 WARNING: some previous versions of tar used option \-I to
 138 filter through bzip2.  When writing scripts, use \-\-bzip2
 139 instead of \-j so that both older and newer tar versions
 140 will work.
 141 .TP
 142 .B \-k, \-\-keep\-old\-files
 143 keep existing files; don't overwrite them from archive
 144 .TP
 145 .B \-K, \-\-starting\-file F
 146 begin at file F in the archive
 147 .TP
 148 .B \-l, \-\-check\-links
 149 print a message if not all links are dumped
 150 .TP
 151 .B \-L, \-\-tape\-length N
 152 change tapes after writing N*1024 bytes
 153 .TP
 154 .B \-m, \-\-touch
 155 don't extract file modified time
 156 .TP
 157 .B \-M, \-\-multi\-volume
 158 create/list/extract multi-volume archive
 159 .TP
 160 .B \-\-mode M
 161 set permissions to M while adding files
 162 .TP
 163 .B \-N, \-\-after\-date DATE, \-\-newer DATE
 164 only store files newer than DATE
 165 .TP
 166 .B \-\-newer\-mtime DATE
 167 only store files whose contents have changed after DATE
 168 .TP
 169 .B \-\-no\-anchored
 170 allow exclusion patterns to match any substring (the default)
 171 .TP
 172 .B \-\-no\-ignore\-case
 173 match patterns case sensitively (the default)
 174 .TP
 175 .B \-\-no\-recursion
 176 do not recurse into subdirectories
 177 .TP
 178 .B \-o, \-\-no\-same\-owner
 179 extract files with owner set to current user (the default for non-root
 180 users)
 181 .TP
 182 .B \-\-no\-same\-permissions
 183 apply umask to extracted files (the default for non-root users)
 184 .TP
 185 .B \-\-no\-wildcards
 186 do not use wildcards when excluding files
 187 .TP
 188 .B \-\-no\-wildcards\-match\-slash
 189 don't let wildcards match "/" when excluding files
 190 .TP
 191 .B \-\-null
 192 for \-T, use "NUL" instead of newline as filename terminator
 193 .TP
 194 .B \-\-numeric\-owner
 195 always use numbers for user/group names
 196 .TP
 197 .B \-\-old\-archive, \-\-portability
 198 write a V7 format archive, rather than ANSI format.  These options are
 199 deprecated, please use
 200 .B \-\-format\=v7
 201 instead.
 202 .TP
 203 .B \-\-one\-file\-system
 204 stay in local file system when creating an archive
 205 .TP
 206 .B \-\-owner O
 207 set owner to O while adding files
 208 .TP
 209 .B \-O, \-\-to\-stdout
 210 extract files to standard output
 211 .TP
 212 .B \-p, \-\-same\-permissions, \-\-preserve\-permissions
 213 ignore umask when extracting files (the default for root)
 214 .TP
 215 .B \-P, \-\-absolute\-names
 216 don't strip leading `/'s from file names
 217 .TP
 218 .B \-\-posix
 219 create POSIX compliant archive.  This option is deprecated,
 220 please use
 221 .B \-\-format\=posix
 222 instead.
 223 .TP
 224 .B \-\-preserve
 225 like \-p \-s
 226 .TP
 227 .B \-R, \-\-block\-number
 228 show block number within archive with each message
 229 .TP
 230 .B \-\-record\-size SIZE
 231 use SIZE bytes per record
 232 .TP
 233 .B \-\-recursion
 234 recurse into directories (the default)
 235 .TP
 236 .B \-\-recursive\-unlink
 237 remove existing directories before extracting directories of the same
 238 name
 239 .TP
 240 .B \-\-remove\-files
 241 remove files after adding them to the archive
 242 .TP
 243 .B \-\-rsh\-command=CMD
 244 Use remote COMMAND instead of `rsh'.  This option exists so that
 245 people who use something other than the standard `rsh' (e.g., a
 246 Kerberized `rsh') can access a remote device.
 247 .TP
 248 .B \-S, \-\-sparse
 249 handle sparse files efficiently
 250 .TP
 251 .B \-s, \-\-same\-order, \-\-preserve\-order
 252 list of names to extract is sorted to match archive
 253 .TP
 254 .B \-\-same\-owner
 255 extract files with owner as specified in archive (the default for
 256 root)
 257 .TP
 258 .B \-\-show\-omitted\-dirs
 259 mention directories that are being skipped over
 260 .TP
 261 .B \-\-suffix SUFFIX
 262 append SUFFIX to make backup files (default ~)
 263 .TP
 264 .B \-T, \-\-files\-from F
 265 get names to extract or archive from file F
 266 .TP
 267 .B \-\-totals
 268 display total bytes written after creating an archive
 269 .TP
 270 .B \-U, \-\-unlink\-first
 271 unlink & recreate files instead of overwriting
 272 .TP
 273 .B \-\-use\-compress\-program PROG
 274 filter the archive through PROG (which must accept \-d)
 275 .TP
 276 .B \-v, \-\-verbose
 277 verbosely list files processed
 278 .TP
 279 .B \-V, \-\-label NAME
 280 create archive with volume name NAME
 281 .TP
 282 .B \-\-version
 283 print tar program version number
 284 .TP
 285 .B \-\-volno\-file F
 286 keep track of current volume (of a multi-volume archive) in F
 287 .TP
 288 .B \-w, \-\-interactive, \-\-confirmation
 289 ask for confirmation for every action
 290 .TP
 291 .B \-W, \-\-verify
 292 attempt to verify the archive after writing it
 293 .TP
 294 .B \-\-wildcards
 295 use wildcards when excluding files (the default)
 296 .TP
 297 .B \-\-wildcards\-match\-slash
 298 allow wildcards to match "/" (the default)
 299 .TP
 300 .B \-X, \-\-exclude\-from=FILE
 301 exclude files matching patterns listed in FILE
 302 .TP
 303 .B \-Z, \-\-compress, \-\-uncompress
 304 filter the archive through compress
 305 .TP
 306 .B \-z, \-\-gzip, \-\-gunzip, \-\-ungzip
 307 filter the archive through gzip
 308 .TP
 309 .B \-[0\-7][lmh]
 310 specify drive and density
 311 .SH BUGS
 312 .LP
 313 The GNU folks, in general, abhor man pages, and create info documents instead.
 314 Unfortunately, the info document describing tar is licensed under the GFDL with
 315 invariant cover texts, which violates the Debian Free Software Guidelines.  As
 316 a result, the info documentation for tar is not included in the Debian package.
 317
 318 If you want to read the complete documentation for GNU tar, please refer to
 319 the online version at <http://www.gnu.org/software/tar/manual/index.html>.
 320
 321 This man page was created for the Debian distribution.  It does not describe
 322 all of the functionality of tar, and it is often out of date.  Patches to
 323 improve the coverage and/or accuracy of this man page are appreciated, and
 324 should be filed as wishlist severity bugs against the Debian tar package,
 325 not submitted to the GNU tar maintainers.