1TAR(1)                          GNU TAR Manual                          TAR(1)
2
3
4

NAME

6       tar - an archiving utility
7

SYNOPSIS

9   Traditional usage
10       tar {A|c|d|r|t|u|x}[GnSkUWOmpsMBiajJzZhPlRvwo] [ARG...]
11
12   UNIX-style usage
13       tar -A [OPTIONS] ARCHIVE ARCHIVE
14
15       tar -c [-f ARCHIVE] [OPTIONS] [FILE...]
16
17       tar -d [-f ARCHIVE] [OPTIONS] [FILE...]
18
19       tar -t [-f ARCHIVE] [OPTIONS] [MEMBER...]
20
21       tar -r [-f ARCHIVE] [OPTIONS] [FILE...]
22
23       tar -u [-f ARCHIVE] [OPTIONS] [FILE...]
24
25       tar -x [-f ARCHIVE] [OPTIONS] [MEMBER...]
26
27   GNU-style usage
28       tar {--catenate|--concatenate} [OPTIONS] ARCHIVE ARCHIVE
29
30       tar --create [--file ARCHIVE] [OPTIONS] [FILE...]
31
32       tar {--diff|--compare} [--file ARCHIVE] [OPTIONS] [FILE...]
33
34       tar --delete [--file ARCHIVE] [OPTIONS] [MEMBER...]
35
36       tar --append [-f ARCHIVE] [OPTIONS] [FILE...]
37
38       tar --list [-f ARCHIVE] [OPTIONS] [MEMBER...]
39
40       tar --test-label [--file ARCHIVE] [OPTIONS] [LABEL...]
41
42       tar --update [--file ARCHIVE] [OPTIONS] [FILE...]
43
44       tar --update [-f ARCHIVE] [OPTIONS] [FILE...]
45
46       tar {--extract|--get} [-f ARCHIVE] [OPTIONS] [MEMBER...]
47

NOTE

49       This manpage is a short description of GNU tar.  For a detailed discus‐
50       sion, including examples and usage recommendations, refer  to  the  GNU
51       Tar Manual available in texinfo format.  If the info reader and the tar
52       documentation are properly installed on your system, the command
53
54           info tar
55
56       should give you access to the complete manual.
57
58       You can also view the manual using the info mode in emacs(1),  or  find
59       it in various formats online at
60
61           http://www.gnu.org/software/tar/manual
62
63       If any discrepancies occur between this manpage and the GNU Tar Manual,
64       the later shall be considered the authoritative source.
65

DESCRIPTION

67       GNU tar is an archiving program designed to store multiple files  in  a
68       single file (an archive), and to manipulate such archives.  The archive
69       can be either a regular file or a device (e.g. a tape drive, hence  the
70       name  of  the  program,  which  stands for tape archiver), which can be
71       located either on the local or on a remote machine.
72
73   Option styles
74       Options to GNU tar can be given in three different styles.   In  tradi‐
75       tional style, the first argument is a cluster of option letters and all
76       subsequent arguments supply arguments to  those  options  that  require
77       them.   The arguments are read in the same order as the option letters.
78       Any command line words that remain after all options has been processed
79       are treated as non-optional arguments: file or archive member names.
80
81       For  example,  the c option requires creating the archive, the v option
82       requests the verbose operation, and the f option takes an argument that
83       sets  the  name of the archive to operate upon.  The following command,
84       written in the traditional style, instructs tar to store all files from
85       the  directory /etc into the archive file etc.tar verbosely listing the
86       files being archived:
87
88       tar cfv etc.tar /etc
89
90       In UNIX or short-option style, each option letter is  prefixed  with  a
91       single  dash,  as  in other command line utilities.  If an option takes
92       argument, the argument follows it, either as a  separate  command  line
93       word,  or  immediately  following  the  option.  However, if the option
94       takes an optional argument, the argument must follow the option  letter
95       without any intervening whitespace, as in -g/tmp/snar.db.
96
97       Any  number  of  options not taking arguments can be clustered together
98       after a single dash, e.g. -vkp.  Options that take  arguments  (whether
99       mandatory  or  optional), can appear at the end of such a cluster, e.g.
100       -vkpf a.tar.
101
102       The example command above written in the short-option style could  look
103       like:
104
105       tar -cvf etc.tar /etc
106       or
107       tar -c -v -f etc.tar /etc
108
109       In GNU or long-option style, each option begins with two dashes and has
110       a meaningful name, consisting of lower-case letters and  dashes.   When
111       used,  the  long option can be abbreviated to its initial letters, pro‐
112       vided that this does not create ambiguity.  Arguments to  long  options
113       are  supplied  either as a separate command line word, immediately fol‐
114       lowing the option, or separated from the option by an equals sign  with
115       no intervening whitespace.  Optional arguments must always use the lat‐
116       ter method.
117
118       Here are several ways of writing the example command in this style:
119
120       tar --create --file etc.tar --verbose /etc
121       or (abbreviating some options):
122       tar --cre --file=etc.tar --verb /etc
123
124       The options in all three styles can be intermixed,  although  doing  so
125       with old options is not encouraged.
126
127   Operation mode
128       The options listed in the table below tell GNU tar what operation it is
129       to perform.  Exactly one of  them  must  be  given.   Meaning  of  non-
130       optional arguments depends on the operation mode requested.
131
132       -A, --catenate, --concatenate
133              Append archive to the end of another archive.  The arguments are
134              treated as the names of archives to append.  All  archives  must
135              be  of the same format as the archive they are appended to, oth‐
136              erwise the resulting archive  might  be  unusable  with  non-GNU
137              implementations of tar.  Notice also that when more than one ar‐
138              chive is given, the members from archives other than  the  first
139              one  will  be  accessible in the resulting archive only if using
140              the -i (--ignore-zeros) option.
141
142              Compressed archives cannot be concatenated.
143
144       -c, --create
145              Create a new archive.  Arguments supply the names of  the  files
146              to  be  archived.   Directories are archived recursively, unless
147              the --no-recursion option is given.
148
149       -d, --diff, --compare
150              Find differences between archive and file system.  The arguments
151              are  optional  and  specify  archive members to compare.  If not
152              given, the current working directory is assumed.
153
154       --delete
155              Delete from the archive.  The arguments supply names of the  ar‐
156              chive  members  to  be  removed.   At least one argument must be
157              given.
158
159              This option does not operate on compressed archives.   There  is
160              no short option equivalent.
161
162       -r, --append
163              Append  files to the end of an archive.  Arguments have the same
164              meaning as for -c (--create).
165
166       -t, --list
167              List the contents of an archive.  Arguments are optional.   When
168              given, they specify the names of the members to list.
169
170       --test-label
171              Test the archive volume label and exit.  When used without argu‐
172              ments, it prints the volume label (if any) and exits with status
173              0.  When one or more command line arguments are given.  tar com‐
174              pares the volume label with each argument.  It exits with code 0
175              if  a  match  is found, and with code 1 otherwise.  No output is
176              displayed, unless used together with the -v (--verbose) option.
177
178              There is no short option equivalent for this option.
179
180       -u, --update
181              Append files which are newer than the corresponding copy in  the
182              archive.   Arguments  have  the  same  meaning as with -c and -r
183              options.  Notice, that newer files don't replace their  old  ar‐
184              chive  copies,  but  instead are appended to the end of archive.
185              The resulting archive can thus contain several  members  of  the
186              same name, corresponding to various versions of the same file.
187
188       -x, --extract, --get
189              Extract  files  from  an archive.  Arguments are optional.  When
190              given,  they  specify  names  of  the  archive  members  to   be
191              extracted.
192
193
194       --show-defaults
195              Show  built-in defaults for various tar options and exit.
196              No arguments are allowed.
197
198       -?, --help
199              Display a short option summary and  exit.   No  arguments
200              allowed.
201
202       --usage
203              Display  a  list of available options and exit.  No argu‐
204              ments allowed.
205
206       --version
207              Print program version and copyright information and exit.
208

OPTIONS

210   Operation modifiers
211       --check-device
212              Check device numbers when creating  incremental  archives
213              (default).
214
215       -g, --listed-incremental=FILE
216              Handle  new  GNU-format incremental backups.  FILE is the
217              name of a snapshot  file,  where  tar  stores  additional
218              information  which  is used to decide which files changed
219              since the previous incremental  dump  and,  consequently,
220              must be dumped again.  If FILE does not exist when creat‐
221              ing an archive, it will be created and all files will  be
222              added  to  the  resulting archive (the level 0 dump).  To
223              create incremental archives of non-zero level N, create a
224              copy  of  the snapshot file created during the level N-1,
225              and use it as FILE.
226
227              When listing or extracting, the actual contents  of  FILE
228              is  not  inspected,  it is needed only due to syntactical
229              requirements.  It is therefore  common  practice  to  use
230              /dev/null in its place.
231
232       --hole-detection=METHOD
233              Use  METHOD to detect holes in sparse files.  This option
234              implies --sparse.  Valid values for METHOD are  seek  and
235              raw.   Default  is  seek  with  fallback  to raw when not
236              applicable.
237
238       -G, --incremental
239              Handle old GNU-format incremental backups.
240
241       --ignore-failed-read
242              Do not exit with nonzero on unreadable files.
243
244       --level=NUMBER
245              Set dump level for  created  listed-incremental  archive.
246              Currently  only --level=0 is meaningful: it instructs tar
247              to truncate the snapshot  file  before  dumping,  thereby
248              forcing a level 0 dump.
249
250       -n, --seek
251              Assume  the archive is seekable.  Normally tar determines
252              automatically whether the archive can be seeked  or  not.
253              This option is intended for use in cases when such recog‐
254              nition fails.  It takes effect only  if  the  archive  is
255              open for reading (e.g. with --list or --extract options).
256
257       --no-check-device
258              Do not check device numbers when creating incremental ar‐
259              chives.
260
261       --no-seek
262              Assume the archive is not seekable.
263
264       --occurrence[=N]
265              Process only the Nth occurrence of each file in  the  ar‐
266              chive.   This  option is valid only when used with one of
267              the following subcommands: --delete, --diff, --extract or
268              --list  and  when  a list of files is given either on the
269              command line or via the -T option.  The default N is 1.
270
271       --restrict
272              Disable the use of some potentially harmful options.
273
274       --sparse-version=MAJOR[.MINOR]
275              Set  version  of  the  sparse  format  to  use   (implies
276              --sparse).  This option implies --sparse.  Valid argument
277              values are 0.0, 0.1, and 1.0.  For a detailed  discussion
278              of  sparse formats, refer to the GNU Tar Manual, appendix
279              D, "Sparse  Formats".   Using  info  reader,  it  can  be
280              accessed  running the following command: info tar 'Sparse
281              Formats'.
282
283       -S, --sparse
284              Handle sparse files efficiently.  Some files in the  file
285              system  may have segments which were actually never writ‐
286              ten (quite often these are database files created by such
287              systems as DBM).  When given this option, tar attempts to
288              determine if the file is sparse prior  to  archiving  it,
289              and  if  so,  to reduce the resulting archive size by not
290              dumping empty parts of the file.
291
292   Overwrite control
293       These options control tar actions when extracting a file over an
294       existing copy on disk.
295
296       -k, --keep-old-files
297              Don't replace existing files when extracting.
298
299       --keep-newer-files
300              Don't  replace  existing  files that are newer than their
301              archive copies.
302
303       --keep-directory-symlink
304              Don't  replace  existing  symlinks  to  directories  when
305              extracting.
306
307       --no-overwrite-dir
308              Preserve metadata of existing directories.
309
310       --one-top-level[=DIR]
311              Extract all files into DIR, or, if used without argument,
312              into a subdirectory named by the base name of the archive
313              (minus  standard  compression  suffixes  recognizable  by
314              --auto-compress).
315
316       --overwrite
317              Overwrite existing files when extracting.
318
319       --overwrite-dir
320              Overwrite metadata of existing directories when  extract‐
321              ing (default).
322
323       --recursive-unlink
324              Recursively  remove  all  files in the directory prior to
325              extracting it.
326
327       --remove-files
328              Remove files from disk after adding them to the archive.
329
330       --skip-old-files
331              Don't replace existing files  when  extracting,  silently
332              skip over them.
333
334       -U, --unlink-first
335              Remove each file prior to extracting over it.
336
337       -W, --verify
338              Verify the archive after writing it.
339
340   Output stream selection
341       --ignore-command-error
342
343       Ignore subprocess exit codes.
344
345       --no-ignore-command-error
346              Treat non-zero exit codes of children as error (default).
347
348       -O, --to-stdout
349              Extract files to standard output.
350
351       --to-command=COMMAND
352              Pipe  extracted  files  to  COMMAND.  The argument is the
353              pathname of an external program, optionally with  command
354              line arguments.  The program will be invoked and the con‐
355              tents of the file being extracted supplied to it  on  its
356              standard input.  Additional data will be supplied via the
357              following environment variables:
358
359              TAR_FILETYPE
360                     Type of the file. It is a single letter  with  the
361                     following meaning:
362
363                             f           Regular file
364                             d           Directory
365                             l           Symbolic link
366                             h           Hard link
367                             b           Block device
368                             c           Character device
369
370                     Currently only regular files are supported.
371
372              TAR_MODE
373                     File mode, an octal number.
374
375              TAR_FILENAME
376                     The name of the file.
377
378              TAR_REALNAME
379                     Name of the file as stored in the archive.
380
381              TAR_UNAME
382                     Name of the file owner.
383
384              TAR_GNAME
385                     Name of the file owner group.
386
387              TAR_ATIME
388                     Time  of last access. It is a decimal number, rep‐
389                     resenting seconds since the Epoch.  If the archive
390                     provides  times  with  nanosecond  precision,  the
391                     nanoseconds are appended to the timestamp after  a
392                     decimal point.
393
394              TAR_MTIME
395                     Time of last modification.
396
397              TAR_CTIME
398                     Time of last status change.
399
400              TAR_SIZE
401                     Size of the file.
402
403              TAR_UID
404                     UID of the file owner.
405
406              TAR_GID
407                     GID of the file owner.
408
409              Additionally, the following variables contain information
410              about tar operation mode and the archive being processed:
411
412              TAR_VERSION
413                     GNU tar version number.
414
415              TAR_ARCHIVE
416                     The name of the archive tar is processing.
417
418              TAR_BLOCKING_FACTOR
419                     Current blocking factor, i.e. number  of  512-byte
420                     blocks in a record.
421
422              TAR_VOLUME
423                     Ordinal  number  of  the  volume tar is processing
424                     (set if reading a multi-volume archive).
425
426              TAR_FORMAT
427                     Format of the archive being  processed.   One  of:
428                     gnu,  oldgnu,  posix, ustar, v7.  TAR_SUBCOMMAND A
429                     short option (with a leading dash) describing  the
430                     operation tar is executing.
431
432   Handling of file attributes
433       --atime-preserve[=METHOD]
434              Preserve  access times on dumped files, either by restor‐
435              ing the times after reading (METHOD=replace, this is  the
436              default)  or  by not setting the times in the first place
437              (METHOD=system)
438
439       --delay-directory-restore
440              Delay  setting  modification  times  and  permissions  of
441              extracted  directories  until the end of extraction.  Use
442              this option when extracting from  an  archive  which  has
443              unusual member ordering.
444
445       --group=NAME[:GID]
446              Force  NAME as group for added files.  If GID is not sup‐
447              plied, NAME can be either a user name or numeric GID.  In
448              this case the missing part (GID or name) will be inferred
449              from the current host's group database.
450
451              When used with --group-map=FILE, affects only those files
452              whose owner group is not listed in FILE.
453
454       --group-map=FILE
455              Read  group  translation  map from FILE.  Empty lines are
456              ignored.  Comments are introduced with # sign and  extend
457              to  the end of line.  Each non-empty line in FILE defines
458              translation for a single group.  It must consist  of  two
459              fields, delimited by any amount of whitespace:
460
461              OLDGRP NEWGRP[:NEWGID]
462
463              OLDGRP  is  either  a  valid group name or a GID prefixed
464              with +.  Unless NEWGID is supplied, NEWGRP must  also  be
465              either  a  valid  group  name or a +GID.  Otherwise, both
466              NEWGRP and NEWGID need not be listed in the system  group
467              database.
468
469              As a result, each input file with owner group OLDGRP will
470              be stored in archive with  owner  group  NEWGRP  and  GID
471              NEWGID.
472
473       --mode=CHANGES
474              Force symbolic mode CHANGES for added files.
475
476       --mtime=DATE-OR-FILE
477              Set  mtime  for  added  files.   DATE-OR-FILE is either a
478              date/time in almost arbitrary format, or the name  of  an
479              existing file.  In the latter case the mtime of that file
480              will be used.
481
482       -m, --touch
483              Don't extract file modified time.
484
485       --no-delay-directory-restore
486              Cancel the effect of the prior  --delay-directory-restore
487              option.
488
489       --no-same-owner
490              Extract files as yourself (default for ordinary users).
491
492       --no-same-permissions
493              Apply  the  user's umask when extracting permissions from
494              the archive (default for ordinary users).
495
496       --numeric-owner
497              Always use numbers for user/group names.
498
499       --owner=NAME[:UID]
500              Force NAME as owner for added files.  If UID is not  sup‐
501              plied, NAME can be either a user name or numeric UID.  In
502              this case the missing part (UID or name) will be inferred
503              from the current host's user database.
504
505              When used with --owner-map=FILE, affects only those files
506              whose owner is not listed in FILE.
507
508       --owner-map=FILE
509              Read owner translation map from FILE.   Empty  lines  are
510              ignored.   Comments are introduced with # sign and extend
511              to the end of line.  Each non-empty line in FILE  defines
512              translation  for  a  single  UID.  It must consist of two
513              fields, delimited by any amount of whitespace:
514
515              OLDUSR NEWUSR[:NEWUID]
516
517              OLDUSR is either a valid user name or a UID prefixed with
518              +.  Unless NEWUID is supplied, NEWUSR must also be either
519              a valid user name or a +UID.  Otherwise, both NEWUSR  and
520              NEWUID need not be listed in the system user database.
521
522              As  a  result,  each  input  file owned by OLDUSR will be
523              stored in archive with owner name NEWUSR and UID NEWUID.
524
525       -p, --preserve-permissions, --same-permissions
526              extract information about file permissions  (default  for
527              superuser)
528
529       --same-owner
530              Try extracting files with the same ownership as exists in
531              the archive (default for superuser).
532
533       -s, --preserve-order, --same-order
534              Sort names to extract to match archive
535
536       --sort=ORDER
537              When creating an archive, sort directory entries  accord‐
538              ing to ORDER, which is one of none, name, or inode.
539
540              The  default is --sort=none, which stores archive members
541              in the same order as returned by the operating system.
542
543              Using --sort=name ensures the member ordering in the cre‐
544              ated archive is uniform and reproducible.
545
546              Using  --sort=inode reduces the number of disk seeks made
547              when creating the archive and thus can considerably speed
548              up  archivation.  This sorting order is supported only if
549              the underlying system provides the necessary information.
550
551   Extended file attributes
552       --acls Enable POSIX ACLs support.
553
554       --no-acls
555              Disable POSIX ACLs support.
556
557       --selinux
558              Enable SELinux context support.
559
560       --no-selinux
561              Disable SELinux context support.
562
563       --xattrs
564              Enable extended attributes support.
565
566       --no-xattrs
567              Disable extended attributes support.
568
569       --xattrs-exclude=PATTERN
570              Specify the exclude pattern for xattr keys.  PATTERN is a
571              POSIX regular expression, e.g. --xattrs-exclude='^user.',
572              to exclude attributes from the user namespace.
573
574       --xattrs-include=PATTERN
575              Specify the include pattern for xattr keys.  PATTERN is a
576              POSIX regular expression.
577
578   Device selection and switching
579       -f, --file=ARCHIVE
580              Use  archive  file  or device ARCHIVE.  If this option is
581              not given, tar will first examine the  environment  vari‐
582              able `TAPE'.  If it is set, its value will be used as the
583              archive name.  Otherwise, tar will assume the compiled-in
584              default.  The default value can be inspected either using
585              the --show-defaults option, or at  the  end  of  the  tar
586              --help output.
587
588              An  archive  name that has a colon in it specifies a file
589              or device on a remote machine.  The part before the colon
590              is  taken as the machine name or IP address, and the part
591              after it as the file or device pathname, e.g.:
592
593              --file=remotehost:/dev/sr0
594
595              An optional username can be  prefixed  to  the  hostname,
596              placing a @ sign between them.
597
598              By  default,  the  remote host is accessed via the rsh(1)
599              command.  Nowadays it is common to  use  ssh(1)  instead.
600              You  can  do  so  by  giving  the  following command line
601              option:
602
603              --rsh-command=/usr/bin/ssh
604
605              The  remote  machine  should  have  the  rmt(8)   command
606              installed.  If its pathname does not match tar's default,
607              you can inform tar about the correct pathname  using  the
608              --rmt-command option.
609
610       --force-local
611              Archive file is local even if it has a colon.
612
613       -F, --info-script=COMMAND, --new-volume-script=COMMAND
614              Run  COMMAND  at  the end of each tape (implies -M).  The
615              command can include arguments.   When  started,  it  will
616              inherit tar's environment plus the following variables:
617
618              TAR_VERSION
619                     GNU tar version number.
620
621              TAR_ARCHIVE
622                     The name of the archive tar is processing.
623
624              TAR_BLOCKING_FACTOR
625                     Current  blocking  factor, i.e. number of 512-byte
626                     blocks in a record.
627
628              TAR_VOLUME
629                     Ordinal number of the  volume  tar  is  processing
630                     (set if reading a multi-volume archive).
631
632              TAR_FORMAT
633                     Format  of  the  archive being processed.  One of:
634                     gnu, oldgnu, posix, ustar, v7.
635
636              TAR_SUBCOMMAND
637                     A short option (with a  leading  dash)  describing
638                     the operation tar is executing.
639
640              TAR_FD File  descriptor  which can be used to communicate
641                     the new volume name to tar.
642
643              If the info script fails, tar exits; otherwise, it begins
644              writing the next volume.
645
646       -L, --tape-length=N
647              Change tape after writing Nx1024 bytes.  If N is followed
648              by a  size  suffix  (see  the  subsection  Size  suffixes
649              below), the suffix specifies the multiplicative factor to
650              be used instead of 1024.
651
652              This option implies -M.
653
654       -M, --multi-volume
655              Create/list/extract multi-volume archive.
656
657       --rmt-command=COMMAND
658              Use COMMAND instead of  rmt  when  accessing  remote  ar‐
659              chives.  See the description of the -f option, above.
660
661       --rsh-command=COMMAND
662              Use  COMMAND  instead  of  rsh  when accessing remote ar‐
663              chives.  See the description of the -f option, above.
664
665       --volno-file=FILE
666              When this option is used in conjunction with --multi-vol‐
667              ume,  tar will keep track of which volume of a multi-vol‐
668              ume archive it is working in FILE.
669
670   Device blocking
671       -b, --blocking-factor=BLOCKS
672              Set record size to BLOCKSx512 bytes.
673
674       -B, --read-full-records
675              When  listing  or  extracting,  accept  incomplete  input
676              records after end-of-file marker.
677
678       -i, --ignore-zeros
679              Ignore  zeroed  blocks in archive.  Normally two consecu‐
680              tive 512-blocks filled with zeroes mean EOF and tar stops
681              reading  after  encountering them.  This option instructs
682              it to read further and is useful  when  reading  archives
683              created with the -A option.
684
685       --record-size=NUMBER
686              Set  record  size.   NUMBER  is  the  number of bytes per
687              record.  It must be multiple of 512.  It can can be  suf‐
688              fixed  with a size suffix, e.g. --record-size=10K, for 10
689              Kilobytes.  See the subsection Size suffixes, for a  list
690              of valid suffixes.
691
692   Archive format selection
693       -H, --format=FORMAT
694              Create archive of the given format.  Valid formats are:
695
696              gnu    GNU tar 1.13.x format
697
698              oldgnu GNU format as per tar <= 1.12.
699
700              pax, posix
701                     POSIX 1003.1-2001 (pax) format.
702
703              ustar  POSIX 1003.1-1988 (ustar) format.
704
705              v7     Old V7 tar format.
706
707       --old-archive, --portability
708              Same as --format=v7.
709
710       --pax-option=keyword[[:]=value][,keyword[[:]=value]]...
711              Control pax keywords when creating PAX archives (-H pax).
712              This option  is  equivalent  to  the  -o  option  of  the
713              pax(1)utility.
714
715       --posix
716              Same as --format=posix.
717
718       -V, --label=TEXT
719              Create  archive  with  volume  name  TEXT.  If listing or
720              extracting, use TEXT as a  globbing  pattern  for  volume
721              name.
722
723   Compression options
724       -a, --auto-compress
725              Use archive suffix to determine the compression program.
726
727       -I, --use-compress-program=COMMAND
728              Filter  data  through  COMMAND.   It  must  accept the -d
729              option, for decompression.  The argument can contain com‐
730              mand line options.
731
732       -j, --bzip2
733              Filter the archive through bzip2(1).
734
735       -J, --xz
736              Filter the archive through xz(1).
737
738       --lzip Filter the archive through lzip(1).
739
740       --lzma Filter the archive through lzma(1).
741
742       --lzop Filter the archive through lzop(1).
743
744       --no-auto-compress
745              Do  not  use  archive suffix to determine the compression
746              program.
747
748       -z, --gzip, --gunzip, --ungzip
749              Filter the archive through gzip(1).
750
751       -Z, --compress, --uncompress
752              Filter the archive through compress(1).
753
754       --zstd Filter the archive through zstd(1).
755
756   Local file selection
757       --add-file=FILE
758              Add FILE to the archive (useful if its name starts with a
759              dash).
760
761       --backup[=CONTROL]
762              Backup  before  removal.   The  CONTROL argument, if sup‐
763              plied, controls the backup policy.  Its valid values are:
764
765              none, off
766                     Never make backups.
767
768              t, numbered
769                     Make numbered backups.
770
771              nil, existing
772                     Make numbered backups if numbered  backups  exist,
773                     simple backups otherwise.
774
775              never, simple
776                     Always make simple backups
777
778              If CONTROL is not given, the value is taken from the VER‐
779              SION_CONTROL environment variable.  If  it  is  not  set,
780              existing is assumed.
781
782       -C, --directory=DIR
783              Change  to  DIR  before  performing any operations.  This
784              option is order-sensitive, i.e. it  affects  all  options
785              that follow.
786
787       --exclude=PATTERN
788              Exclude  files matching PATTERN, a glob(3)-style wildcard
789              pattern.
790
791       --exclude-backups
792              Exclude backup and lock files.
793
794       --exclude-caches
795              Exclude   contents   of   directories   containing   file
796              CACHEDIR.TAG, except for the tag file itself.
797
798       --exclude-caches-all
799              Exclude  directories containing file CACHEDIR.TAG and the
800              file itself.
801
802       --exclude-caches-under
803              Exclude   everything   under    directories    containing
804              CACHEDIR.TAG
805
806       --exclude-ignore=FILE
807              Before  dumping a directory, see if it contains FILE.  If
808              so, read exclusion patterns from this file.  The patterns
809              affect only the directory itself.
810
811       --exclude-ignore-recursive=FILE
812              Same  as --exclude-ignore, except that patterns from FILE
813              affect both the directory and all its subdirectories.
814
815       --exclude-tag=FILE
816              Exclude contents of directories containing  FILE,  except
817              for FILE itself.
818
819       --exclude-tag-all=FILE
820              Exclude directories containing FILE.
821
822       --exclude-tag-under=FILE
823              Exclude everything under directories containing FILE.
824
825       --exclude-vcs
826              Exclude version control system directories.
827
828       --exclude-vcs-ignores
829              Exclude  files that match patterns read from VCS-specific
830              ignore files.  Supported files are:  .cvsignore,  .gitig‐
831              nore, .bzrignore, and .hgignore.
832
833       -h, --dereference
834              Follow  symlinks;  archive  and dump the files they point
835              to.
836
837       --hard-dereference
838              Follow hard links; archive and dump the files they  refer
839              to.
840
841       -K, --starting-file=MEMBER
842              Begin at the given member in the archive.
843
844       --newer-mtime=DATE
845              Work on files whose data changed after the DATE.  If DATE
846              starts with / or . it is taken to be  a  file  name;  the
847              mtime of that file is used as the date.
848
849       --no-null
850              Disable the effect of the previous --null option.
851
852       --no-recursion
853              Avoid descending automatically in directories.
854
855       --no-unquote
856              Do not unquote input file or member names.
857
858       --no-verbatim-files-from
859              Treat  each line read from a file list as if it were sup‐
860              plied in the command line.  I.e.,  leading  and  trailing
861              whitespace is removed and, if the resulting string begins
862              with a dash, it is treated as tar command line option.
863
864              This  is   the   default   behavior.    The   --no-verba‐
865              tim-files-from  option is provided as a way to restore it
866              after --verbatim-files-from option.
867
868              This option is positional: it  affects  all  --files-from
869              options   that   occur   after   it  in,  until  --verba‐
870              tim-files-from option or end of  line,  whichever  occurs
871              first.
872
873              It is implied by the --no-null option.
874
875       --null Instruct  subsequent  -T  options to read null-terminated
876              names verbatim (disables special handling of  names  that
877              start with a dash).
878
879              See also --verbatim-files-from.
880
881       -N, --newer=DATE, --after-date=DATE
882              Only  store files newer than DATE.  If DATE starts with /
883              or . it is taken to be a file name;  the  ctime  of  that
884              file is used as the date.
885
886       --one-file-system
887              Stay in local file system when creating archive.
888
889       -P, --absolute-names
890              Don't strip leading slashes from file names when creating
891              archives.
892
893       --recursion
894              Recurse into directories (default).
895
896       --suffix=STRING
897              Backup before removal, override  usual  suffix.   Default
898              suffix  is  ~,  unless overridden by environment variable
899              SIMPLE_BACKUP_SUFFIX.
900
901       -T, --files-from=FILE
902              Get names to extract or create from FILE.
903
904              Unless specified otherwise, the FILE must contain a  list
905              of  names separated by ASCII LF (i.e. one name per line).
906              The names read are handled the same way as  command  line
907              arguments.   They  undergo  quote removal and word split‐
908              ting, and any string that starts with a - is  handled  as
909              tar command line option.
910
911              If  this  behavior  is  undesirable, it can be turned off
912              using the --verbatim-files-from option.
913
914              The --null option instructs tar that the  names  in  FILE
915              are  separated by ASCII NUL character, instead of LF.  It
916              is useful if the list is  generated  by  find(1)  -print0
917              predicate.
918
919       --unquote
920              Unquote file or member names (default).
921
922       --verbatim-files-from
923              Treat each line obtained from a file list as a file name,
924              even if it starts with a dash.  File lists  are  supplied
925              with  the --files-from (-T) option.  The default behavior
926              is to handle names supplied in file lists as if they were
927              typed in the command line, i.e. any names starting with a
928              dash  are  treated  as   tar   options.    The   --verba‐
929              tim-files-from option disables this behavior.
930
931              This  option  affects all --files-from options that occur
932              after it in the command line.  Its effect is reverted  by
933              the --no-verbatim-files-from} option.
934
935              This option is implied by the --null option.
936
937              See also --add-file.
938
939       -X, --exclude-from=FILE
940              Exclude files matching patterns listed in FILE.
941
942   File name transformations
943       --strip-components=NUMBER
944              Strip  NUMBER  leading  components  from  file  names  on
945              extraction.
946
947       --transform=EXPRESSION, --xform=EXPRESSION
948              Use sed replace EXPRESSION to transform file names.
949
950   File name matching options
951       These options affect both exclude and include patterns.
952
953       --anchored
954              Patterns match file name start.
955
956       --ignore-case
957              Ignore case.
958
959       --no-anchored
960              Patterns match after any / (default for exclusion).
961
962       --no-ignore-case
963              Case sensitive matching (default).
964
965       --no-wildcards
966              Verbatim string matching.
967
968       --no-wildcards-match-slash
969              Wildcards do not match /.
970
971       --wildcards
972              Use wildcards (default for exclusion).
973
974       --wildcards-match-slash
975              Wildcards match / (default for exclusion).
976
977   Informative output
978       --checkpoint[=N]
979              Display progress messages every Nth record (default 10).
980
981       --checkpoint-action=ACTION
982              Run ACTION on each checkpoint.
983
984       --clamp-mtime
985              Only set time when the file is more recent than what  was
986              given with --mtime.
987
988       --full-time
989              Print file time to its full resolution.
990
991       --index-file=FILE
992              Send verbose output to FILE.
993
994       -l, --check-links
995              Print a message if not all links are dumped.
996
997       --no-quote-chars=STRING
998              Disable quoting for characters from STRING.
999
1000       --quote-chars=STRING
1001              Additionally quote characters from STRING.
1002
1003       --quoting-style=STYLE
1004              Set  quoting style for file and member names.  Valid val‐
1005              ues for STYLE are literal,  shell,  shell-always,  c,  c-
1006              maybe, escape, locale, clocale.
1007
1008       -R, --block-number
1009              Show block number within archive with each message.
1010
1011       --show-omitted-dirs
1012              When listing or extracting, list each directory that does
1013              not match search criteria.
1014
1015       --show-transformed-names, --show-stored-names
1016              Show  file  or  archive  names  after  transformation  by
1017              --strip and --transform options.
1018
1019       --totals[=SIGNAL]
1020              Print  total bytes after processing the archive.  If SIG‐
1021              NAL is given, print  total  bytes  when  this  signal  is
1022              delivered.  Allowed signals are: SIGHUP, SIGQUIT, SIGINT,
1023              SIGUSR1, and SIGUSR2.  The SIG prefix can be omitted.
1024
1025       --utc  Print file modification times in UTC.
1026
1027       -v, --verbose
1028              Verbosely list files processed.  Each  instance  of  this
1029              option  on the command line increases the verbosity level
1030              by one.   The  maximum  verbosity  level  is  3.   For  a
1031              detailed  discussion  of  how  various  verbosity  levels
1032              affect tar's output, please refer to GNU Tar Manual, sub‐
1033              section 2.5.1 "The --verbose Option".
1034
1035       --warning=KEYWORD
1036              Enable or disable warning messages identified by KEYWORD.
1037              The messages are suppressed if KEYWORD is  prefixed  with
1038              no- and enabled otherwise.
1039
1040              Multiple --warning messages accumulate.
1041
1042              Keywords controlling general tar operation:
1043
1044              all    Enable all warning messages.  This is the default.
1045
1046              none   Disable all warning messages.
1047
1048              filename-with-nuls
1049                     "%s: file name read contains nul character"
1050
1051              alone-zero-block
1052                     "A lone zero block at %s"
1053
1054              Keywords applicable for tar --create:
1055
1056              cachedir
1057                     "%s: contains a cache directory tag %s; %s"
1058
1059              file-shrank
1060                     "%s: File shrank by %s bytes; padding with zeros"
1061
1062              xdev   "%s:  file  is  on  a  different  filesystem;  not
1063                     dumped"
1064
1065              file-ignored
1066                     "%s: Unknown file type; file ignored"
1067                     "%s: socket ignored"
1068                     "%s: door ignored"
1069
1070              file-unchanged
1071                     "%s: file is unchanged; not dumped"
1072
1073              ignore-archive
1074                     "%s: file is the archive; not dumped"
1075
1076              file-removed
1077                     "%s: File removed before we read it"
1078
1079              file-changed
1080                     "%s: file changed as we read it"
1081
1082              failed-read
1083                     Suppresses  warnings  about  unreadable  files  or
1084                     directories.  This  keyword  applies  only if used
1085                     together with the --ignore-failed-read option.
1086
1087              Keywords applicable for tar --extract:
1088
1089              existing-file
1090                     "%s: skipping existing file"
1091
1092              timestamp
1093                     "%s: implausibly old time stamp %s"
1094                     "%s: time stamp %s is %s s in the future"
1095
1096              contiguous-cast
1097                     "Extracting contiguous files as regular files"
1098
1099              symlink-cast
1100                     "Attempting extraction of symbolic links  as  hard
1101                     links"
1102
1103              unknown-cast
1104                     "%s:  Unknown  file type '%c', extracted as normal
1105                     file"
1106
1107              ignore-newer
1108                     "Current %s is newer or same age"
1109
1110              unknown-keyword
1111                     "Ignoring unknown extended header keyword '%s'"
1112
1113              decompress-program
1114                     Controls verbose description of failures occurring
1115                     when  trying  to run alternative decompressor pro‐
1116                     grams.   This  warning  is  disabled  by   default
1117                     (unless  --verbose  is used).  A common example of
1118                     what you can get when using this warning is:
1119
1120                     $ tar --warning=decompress-program -x -f archive.Z
1121                     tar (child): cannot run compress: No such file or directory
1122                     tar (child): trying gzip
1123
1124                     This means that tar first tried to decompress  ar‐
1125                     chive.Z  using  compress,  and,  when that failed,
1126                     switched to gzip.
1127
1128              record-size
1129                     "Record size = %lu blocks"
1130
1131              Keywords controlling incremental extraction:
1132
1133              rename-directory
1134                     "%s: Directory has been renamed from %s"
1135                     "%s: Directory has been renamed"
1136
1137              new-directory
1138                     "%s: Directory is new"
1139
1140              xdev   "%s: directory is on a different device: not purg‐
1141                     ing"
1142
1143              bad-dumpdir
1144                     "Malformed dumpdir: 'X' never used"
1145
1146       -w, --interactive, --confirmation
1147              Ask for confirmation for every action.
1148
1149   Compatibility options
1150       -o     When  creating,  same as --old-archive.  When extracting,
1151              same as --no-same-owner.
1152
1153   Size suffixes
1154               Suffix    Units                   Byte Equivalent
1155               b         Blocks                  SIZE x 512
1156               B         Kilobytes               SIZE x 1024
1157               c         Bytes                   SIZE
1158               G         Gigabytes               SIZE x 1024^3
1159               K         Kilobytes               SIZE x 1024
1160               k         Kilobytes               SIZE x 1024
1161               M         Megabytes               SIZE x 1024^2
1162               P         Petabytes               SIZE x 1024^5
1163               T         Terabytes               SIZE x 1024^4
1164               w         Words                   SIZE x 2
1165

RETURN VALUE

1167       Tar exit code indicates whether it was able to successfully per‐
1168       form  the  requested  operation,  and if not, what kind of error
1169       occurred.
1170
1171       0      Successful termination.
1172
1173       1      Some files differ.  If tar was invoked with the --compare
1174              (--diff,  -d)  command  line option, this means that some
1175              files in the archive differ from their disk counterparts.
1176              If  tar  was  given  one  of  the  --create,  --append or
1177              --update options, this exit code means  that  some  files
1178              were  changed  while  being archived and so the resulting
1179              archive does not contain the exact copy of the file set.
1180
1181       2      Fatal error.  This means that some  fatal,  unrecoverable
1182              error occurred.
1183
1184       If  a  subprocess  that  had  been  invoked by tar exited with a
1185       nonzero exit code, tar itself exits  with  that  code  as  well.
1186       This  can happen, for example, if a compression option (e.g. -z)
1187       was used and the external compressor  program  failed.   Another
1188       example is rmt failure during backup to a remote device.
1189

SEE ALSO

1191       bzip2(1),  compress(1),  gzip(1), lzma(1), lzop(1), rmt(8), sym‐
1192       link(7), xz(1), zstd(1).
1193
1194       Complete tar manual: run info tar or use emacs(1) info  mode  to
1195       read it.
1196
1197       Online copies of GNU tar documentation in various formats can be
1198       found at:
1199
1200           http://www.gnu.org/software/tar/manual
1201

BUG REPORTS

1203       Report bugs to <bug-tar@gnu.org>.
1204
1206       Copyright © 2013 Free Software Foundation, Inc.
1207       License GPLv3+: GNU GPL version 3 or later
1208       <http://gnu.org/licenses/gpl.html>
1209       This  is  free software: you are free to change and redistribute
1210       it.  There is NO WARRANTY, to the extent permitted by law.
1211
1212
1213
1214TAR                            February 4, 2019                         TAR(1)
Impressum