1 .\" @(#)tar.1 1.11.1 93/19/22 PJV;
2 .TH TAR 1 "29 Aug 2007"
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 don't extract file modified time
184 .BI \-\-transform " expr"
185 applies filename transformations.
186 The argument to this option can be a list of replace expressions, separated
187 by semicolon (as in `sed').
188 Filename transformations are applied to symbolic link targets during both
189 creation and extraction.
190 This option may be specified any number of
191 times, the specified transofrmations will be applied in turn.
193 .B \-M, \-\-multi\-volume
194 create/list/extract multi-volume archive
197 set permissions to M while adding files
199 .B \-N, \-\-after\-date DATE, \-\-newer DATE
200 only store files newer than DATE
202 .B \-\-newer\-mtime DATE
203 only store files whose contents have changed after DATE
206 allow exclusion patterns to match any substring (the default)
208 .B \-\-no\-ignore\-case
209 match patterns case sensitively (the default)
212 do not recurse into subdirectories
214 .B \-o, \-\-no\-same\-owner
215 extract files with owner set to current user (the default for non-root
218 .B \-\-no\-same\-permissions
219 apply umask to extracted files (the default for non-root users)
222 do not use wildcards when excluding files
224 .B \-\-no\-wildcards\-match\-slash
225 don't let wildcards match "/" when excluding files
228 for \-T, use "NUL" instead of newline as filename terminator
230 .B \-\-numeric\-owner
231 always use numbers for user/group names
233 .B \-\-old\-archive, \-\-portability
234 write a V7 format archive, rather than ANSI format. These options are
235 deprecated, please use
239 .B \-\-one\-file\-system
240 stay in local file system when creating an archive
243 set owner to O while adding files
245 .B \-O, \-\-to\-stdout
246 extract files to standard output
248 .B \-p, \-\-same\-permissions, \-\-preserve\-permissions
249 ignore umask when extracting files (the default for root)
251 .B \-P, \-\-absolute\-names
252 don't strip leading `/'s from file names
255 create POSIX compliant archive. This option is deprecated,
263 .B \-R, \-\-block\-number
264 show block number within archive with each message
266 .B \-\-record\-size SIZE
267 use SIZE bytes per record
270 recurse into directories (the default)
272 .B \-\-recursive\-unlink
273 remove existing directories before extracting directories of the same
277 remove files after adding them to the archive
279 .B \-\-rsh\-command=CMD
280 Use remote COMMAND instead of `rsh'. This option exists so that
281 people who use something other than the standard `rsh' (e.g., a
282 Kerberized `rsh') can access a remote device.
285 handle sparse files efficiently
287 .B \-s, \-\-same\-order, \-\-preserve\-order
288 list of names to extract is sorted to match archive
291 extract files with owner as specified in archive (the default for
294 .B \-\-show\-omitted\-dirs
295 mention directories that are being skipped over
297 .BI \-\-strip\-components " n"
298 Strip the given number of leading directory components
300 .B \-\-strip, \-\-strip\-components N
301 Strips the first N components from archive members' pathnames when
305 append SUFFIX to make backup files (default ~)
307 .B \-T, \-\-files\-from F
308 get names to extract or archive from file F
311 display total bytes written after creating an archive
313 .B \-U, \-\-unlink\-first
314 unlink & recreate files instead of overwriting
316 .B \-\-use\-compress\-program PROG
317 filter the archive through PROG (which must accept \-d)
320 verbosely list files processed
322 .B \-V, \-\-label NAME
323 create archive with volume name NAME
326 print tar program version number
329 keep track of current volume (of a multi-volume archive) in F
331 .B \-w, \-\-interactive, \-\-confirmation
332 ask for confirmation for every action
335 attempt to verify the archive after writing it
338 use wildcards when excluding files (the default)
340 .B \-\-wildcards\-match\-slash
341 allow wildcards to match "/" (the default)
343 .B \-X, \-\-exclude\-from=FILE
344 exclude files matching patterns listed in FILE
346 .B \-Z, \-\-compress, \-\-uncompress
347 filter the archive through compress
349 .B \-z, \-\-gzip, \-\-gunzip, \-\-ungzip
350 filter the archive through gzip
353 specify drive and density
355 The behavior of tar is controlled by the following environment variables,
359 Device or file to use for the archive if \fB--file\fR is not specified.
360 If this environment variable is unset, use stdin or stdout instead.
363 Options to prepend to those specified on the command line, separated by
364 whitespace. Embedded backslashes may be used to escape whitespace or
365 backslashes within an option.
367 In addition, the value of the blocking factor is made available to info
368 and checkpoint scripts via environment variable
369 .B TAR_BLOCKING_FACTOR.
372 The GNU folks, in general, abhor man pages, and create info documents instead.
373 Unfortunately, the info document describing tar is licensed under the GFDL with
374 invariant cover texts, which violates the Debian Free Software Guidelines. As
375 a result, the info documentation for tar is not included in the Debian package.
377 If you want to read the complete documentation for GNU tar, please refer to
378 the online version at
381 <http://www.gnu.org/software/tar/manual/index.html>
383 This man page was created for the Debian distribution. It does not describe
384 all of the functionality of tar, and it is often out of date. Patches to
385 improve the coverage and/or accuracy of this man page are appreciated, and
386 should be filed as wishlist severity bugs against the Debian tar package,
387 not submitted to the GNU tar maintainers.
projects / tar / blob