1 .\" @(#)tar.1 1.11.1 93/19/22 PJV;
2 .TH TAR 1 "24 Feb 2009"
4 tar \- The GNU version of the tar archiving utility
10 .B A \-\-catenate \-\-concatenate \||\| c \-\-create \||\| d \-\-diff \-\-compare \||\| \-\-delete \||\| r \-\-append \||\| t \-\-list \||\| u \-\-update \||\| x \-\-extract \-\-get
12 .I pathname [ pathname ... ]
15 This manual page documents the GNU version of
17 , an archiving program designed to store and extract files from
18 an archive file known as a
22 may be made on a tape drive, however, it is also common
28 must be one of the options:
30 followed by any optional functions.
31 The final arguments to
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.
41 .B tar \-xvvzf foo.tar.gz
42 extract gzipped foo.tar.gz
44 .B tar \-cvvf foo.tar foo/
45 tar contents of folder foo in foo.tar
46 .SH "FUNCTION LETTERS"
48 .B One of the following options must be used:
50 .B \-A, \-\-catenate, \-\-concatenate
51 append tar files to an archive
56 .B \-d, \-\-diff, \-\-compare
57 find differences between archive and file system
60 delete from the archive (not for use on mag tapes!)
63 append files to the end of an archive
66 list the contents of an archive
69 only append files that are newer than copy in archive
71 .B \-x, \-\-extract, \-\-get
72 extract files from an archive
75 .B \-\-allow\-name\-mangling
76 re-enable handling of GNUTYPE_NAMES which is now disabled by default
79 force exclusion patterns to match initial subsequences
81 .B \-\-atime\-preserve
82 don't change access times on dumped files
84 .B \-a, \-\-auto\-compress
85 with \-\-create, selects compression algorithm basing on the suffix
86 of the archive file name
88 .B \-b, \-\-blocking\-factor N
89 use record size of Nx512 bytes (default N=20)
91 .B \-B, \-\-read\-full\-records
92 reblock as we read (for reading 4.2BSD pipes)
95 back up files instead of overwriting (TYPE=numbered, existing, simple)
97 .B \-C, \-\-directory DIR
98 change to directory DIR
101 print periodic checkpoints
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.
111 enables comparing device numbers. This is the default.
113 .B \-\-no\-check\-device
114 disables comparing device numbers during preparatory stage of an
116 This allows to avoid creating full dumps if the device numbers change
117 (e.g. when using an LVM snapshot)
119 .B \-\-exclude=PATTERN
120 exclude files matching PATTERN
122 .B \-f, \-\-file [HOSTNAME:]F
123 use archive file or device F (otherwise value of TAPE environment variable; if unset, "\-", meaning stdin/stdout)
125 .B \-F, \-\-info\-script F, \-\-new\-volume\-script F
126 run script at end of each tape (implies \-M)
129 archive file is local even if it has a colon
131 .B \-G, \-\-incremental
132 create/list/extract old GNU-format incremental backup
134 .B \-g, \-\-listed\-incremental F
135 create/list/extract new GNU-format incremental backup
138 set group to G while adding files
140 .B \-h, \-\-dereference
141 don't dump symlinks; dump the files they point to
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')
150 .B \-i, \-\-ignore\-zeros
151 ignore blocks of zeros in archive (normally mean EOF)
154 ignore case when excluding files
156 .B \-\-ignore\-failed\-read
157 don't exit with non-zero status on unreadable files
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
166 .B \-k, \-\-keep\-old\-files
167 keep existing files; don't overwrite them from archive
169 .B \-K, \-\-starting\-file F
170 begin at file F in the archive
173 selects LZMA compression algorithm
175 .B \-l, \-\-check\-links
176 print a message if not all links are dumped
178 .B \-L, \-\-tape\-length N
179 change tapes after writing N*1024 bytes
182 filter the archive through lzop
185 don't extract file modified time
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.
196 .B \-M, \-\-multi\-volume
197 create/list/extract multi-volume archive
200 set permissions to M while adding files
202 .B \-N, \-\-after\-date DATE, \-\-newer DATE
203 only store files newer than DATE
205 .B \-\-newer\-mtime DATE
206 only store files whose contents have changed after DATE
209 allow exclusion patterns to match any substring (the default)
211 .B \-\-no\-auto\-compress
212 Cancels the effect of previous \-\-auto\-compress options
214 .B \-\-no\-ignore\-case
215 match patterns case sensitively (the default)
218 cancels the effect of previous \-\-null option
221 do not recurse into subdirectories
223 .B \-o, \-\-no\-same\-owner
224 extract files with owner set to current user (the default for non-root
227 .B \-\-no\-same\-permissions
228 apply umask to extracted files (the default for non-root users)
231 do not use wildcards when excluding files
233 .B \-\-no\-wildcards\-match\-slash
234 don't let wildcards match "/" when excluding files
237 for \-T, use "NUL" instead of newline as filename terminator
239 .B \-\-numeric\-owner
240 always use numbers for user/group names
242 .B \-\-old\-archive, \-\-portability
243 write a V7 format archive, rather than ANSI format. These options are
244 deprecated, please use
248 .B \-\-one\-file\-system
249 stay in local file system when creating an archive
252 set owner to O while adding files
254 .B \-O, \-\-to\-stdout
255 extract files to standard output
257 .B \-p, \-\-same\-permissions, \-\-preserve\-permissions
258 ignore umask when extracting files (the default for root)
260 .B \-P, \-\-absolute\-names
261 don't strip leading `/'s from file names
264 create POSIX compliant archive. This option is deprecated,
272 .B \-R, \-\-block\-number
273 show block number within archive with each message
275 .B \-\-record\-size SIZE
276 use SIZE bytes per record
279 recurse into directories (the default)
281 .B \-\-recursive\-unlink
282 remove existing directories before extracting directories of the same
286 remove files after adding them to the archive
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.
294 handle sparse files efficiently
296 .B \-s, \-\-same\-order, \-\-preserve\-order
297 list of names to extract is sorted to match archive
300 extract files with owner as specified in archive (the default for
303 .B \-\-show\-omitted\-dirs
304 mention directories that are being skipped over
306 .BI \-\-strip\-components " n"
307 Strip the given number of leading directory components
309 .B \-\-strip, \-\-strip\-components N
310 Strips the first N components from archive members' pathnames when
314 append SUFFIX to make backup files (default ~)
316 .B \-T, \-\-files\-from F
317 get names to extract or archive from file F
320 display total bytes written after creating an archive
322 .B \-U, \-\-unlink\-first
323 unlink & recreate files instead of overwriting
325 .B \-\-use\-compress\-program PROG
326 filter the archive through PROG (which must accept \-d)
329 verbosely list files processed
331 .B \-V, \-\-label NAME
332 create archive with volume name NAME
335 print tar program version number
338 keep track of current volume (of a multi-volume archive) in F
340 .B \-w, \-\-interactive, \-\-confirmation
341 ask for confirmation for every action
344 attempt to verify the archive after writing it
347 use wildcards when excluding files (the default)
349 .B \-\-wildcards\-match\-slash
350 allow wildcards to match "/" (the default)
352 .B \-X, \-\-exclude\-from=FILE
353 exclude files matching patterns listed in FILE
355 .B \-Z, \-\-compress, \-\-uncompress
356 filter the archive through compress
358 .B \-z, \-\-gzip, \-\-gunzip, \-\-ungzip
359 filter the archive through gzip
362 specify drive and density
364 The behavior of tar is controlled by the following environment variables,
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.
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.
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.
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.
386 If you want to read the complete documentation for GNU tar, please refer to
387 the online version at
390 <http://www.gnu.org/software/tar/manual/index.html>
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.