tar (gnutar)

Create, add files to, or extract files from an archive file in gnutar format, called a tarfile. Tape ARchiver; manipulate "tar" archive files.

       tar [[-]function] [options] filenames...

       tar [[-]function] [options] -C directory-name...

   Command-line arguments that specify files to add to, extract from,
   or list from an archive can be given as shell pattern matching strings.

       Exactly one of the following functions must be specified.
       (append, create, difference, replace, table of contents, update, and extract)

     --concatenate  Append the contents of named file, which must itself be a
                gnutar archive, to the end of the archive (erasing the old
                end-of-archive block).  This has the effect of adding the
                files contained in the named file to the first archive,
                rather than adding the second archive as an element of the
                first.  Note: This option requires a rewritable tarfile,
                and therefore does not work on quarter-inch cartridge
                tapes.  (see notes below)
     --create   Create a new archive (or truncates an old one) and writes
                the named files to it.
     --compare  Find differences between files in the archive and corresponding
                files in the file system.

     --delete   Delete named files from the archive.  (Does not work on
                quarter-inch tapes).
     --append   Append files to the end of an archive.  (Does not work on
                quarter-inch tapes).
     --list     List the contents of an archive; if filename arguments are
                given, only those files are listed, otherwise the entire
                table of contents is listed.
     --update   Append the named files if the on-disk version has a modification
                date more recent than their copy in the archive
                (if any).  Does not work on quarter-inch tapes.
     --get      Extract files from an archive.  The owner, modification
                time, and file permissions are restored, if possible.  If
                no file arguments are given, extract all the files in the
                archive.  If a filename argument matches the name of a
                directory on the tape, that directory and its contents are
                extracted (as well as all directories under that direc-
                tory).  If the archive contains multiple entries corre-
                sponding to the same file (see the --append command
                above), the last one extracted will overwrite all earlier

You can specify an argument for the `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option whenever you use `tar'; this option determines the name of the archive file that `tar' will work on.

If you don't specify this argument, then `tar' will use a default, usually some physical tape drive attached to your machine. If there is no tape drive attached, or the default is not meaningful, then `tar' will print an error message. The error message might look roughly like one of the following:

     tar: can't open /dev/rmt8 : No such device or address
     tar: can't open /dev/rsmt0 : I/O error

To avoid confusion, we recommend that you always specify an archive file name by using `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') when writing your `tar' commands.

     --verbose' (`-v') shows details about the results of running `tar'.

This can be especially useful when the results might not be obvious. For example, if you want to see the progress of `tar' as it writes files into the archive, you can use the `--verbose' option. In the beginning, you may find it useful to use `--verbose' at all times; when you are more accustomed to `tar', you will likely want to use it at certain times but not at others.

Sometimes, a single instance of `--verbose' on the command line will show a full, `ls' style listing of an archive or files, giving sizes, owners, and similar information. Other times, `--verbose' will only show files or members that the particular operation is operating on at the time. In the latter case, you can use `--verbose' twice in a command to get a listing such as that in the former case.


The other options to gnutar may be combined arbitrarily; single-letter options may be bundled in with the command word. Verbose options which take arguments will be followed by the argument; single-letter options will consume successive command line arguments (see the EXAMPLES below).
gnutar will properly handle option arguments passed either with or without a leading `=` (i.e. either --option=arg or --option arg).

     --help               Prints a message listing and briefly describing
                          all the command options to gnutar.
     --atime-preserve     Restore the access times on files which are writ-
                          ten to tape (note that this will change the
                          inode-change time!).
     --block-size number
     --blocking-factor number
     --record-size size   Sets the block size for reading or writing to
                          number * 512-byte blocks. Or sets block size for
                          reading or writing to size bytes which must be a
                          multiple of 512.
     --read-full-records  Re-assemble short reads into full records (for
                          reading 4.2BSD pipes).

     --backup control     Backup files before removal.  Optionally, the
                          user can specify a control argument to control
                          how gnutar performs the backups.  Supported values
                          are listed bellow in the ENVIRONMENT section.
     --suffix suffix      Backup files before removal.  Override the normal
                          backup suffix (default: '~'), using suffix instead.

     -C directory
     --directory directory   Change to directory before processing the remaining
                             arguments. (see notes below)

     --checkpoint         Print number of buffer reads/writes while reading/writing the archive.

     -f [hostname:]file
     --file [hostname:]file  Read or write the specified file (default is
                              /dev/sa0).   If a hostname is specified, gnutar

           will use rmt(8) to read or write the specified
           file on a remote machine.  `-' may be used as a
           filename, for reading or writing to/from

     --force-local        Archive file is local even if it has a colon.

     -F file
     --info-script file
     --new-volume-script file
                          Run a script at the end of each archive volume
                          (implies -M).
     --incremental        Create/list/extract old GNU-format incremental backup.
     -g file
     --listed-incremental file
                          Create/list/extract new GNU-format incremental backup.

     --group name         Force group as group for added files.
     --dereference        Don't write symlinks as symlinks; write the data
                          of the files they name.
     --ignore-zeros       Ignore blocks of zeroes in archive (usually means
     --ignore-failed-read  Don't exit with non-zero status on unreadable
     --bzip2              Filter the archive through bzip2(1).
     --keep-old-files     Keep files which already exist on disk; don't
                          overwrite them from the archive.
     -K file
     --starting-file file Begin at file in the archive.
     --one-file-system    Stay in local file system when creating an
                          archive (do not cross mount points).
     -L number
     --tape-length number Change tapes after writing number * 1024 bytes.
     --mode changes       Force changes to file mode of added files.
     --modification-time  Don't extract file modified time.
     --multi-volume      Create/list/extract multi-volume archive.
     --no-recursion      Don't recurse into subdirectories when creating.
     --volno-file file   File name with volume number to start with.
     -N date
     --after-date date
     --newer date       Only store files with creation time newer than
     --newer-mtime date   Only store files with modification time newer than date.

     --no-same-owner   Do not preserve ownership when extracting files.
                       Extract them all as owned by the current user.
     --no-same-permissions   Do not extract permission information.  Extract
                       them using the default permissions for the cur-
                       rent user.
     --numeric-owner   Use numbers instead of names for owner/group names.
     --portability     Write a V7 format archive, rather than POSIX format.

     --to-stdout       Extract files to standard output.
     --owner name      Force name as owner for added files.
     --overwrite       Overwrite existing files when extracting.
     --overwrite-dir   Overwrite directory metadata when extracting.

     --preserve-permissions  Extract all permission information.
     --preserve        Has the effect of -p -s.

     --absolute-names  Don't strip leading `/' from file names.
     --posix           Instructs gnutar to create a POSIX compliant
                      `tar' archive.

     --block-number      Show record number within archive with each message.
     --remove-files      Remove files after adding them to the archive.
     --rsh-command command   Use command instead of rsh for remote archives/files.

     --preserve-order  List of names to extract is sorted to match archive.
     --same-owner      Try to preserve ownership when extracting files.
     --show-omitted-dirs   Show directories which were omitted while processing the archive.

     --sparse         Handle `sparse' files efficiently.
     -T file
     --files-from file   Get names of files to extract or create from
                         file, one per line.
     --null           Modifies behavior of -T to expect null-terminated
                      names; disables -C.
     --totals         Prints total bytes written with --create.
     --unlink-first      Unlink files before creating them.
     --recursive-unlink  Empty hierarchies prior to extracting directory.
     --verbose        Lists files written to archive with --create or
                      extracted with --extract; lists file protection
                      information along with file names with --list.
     -V volume-name
     --label volume-name     Create archive with the given volume-name.  When
                      used with list or extract, volume-name is used as
                      a globing pattern.
     --version        Print gnutar program version number.
     --confirmation   Ask for confirmation for every action.
     --verify       Attempt to verify the archive after writing it.
     --exclude pattern      Exclude files matching the pattern (don't extract
        them, don't add them, don't list them).
     -X file
     --exclude-from file     Exclude files listed in file.
     --anchored        Exclude patterns match file name start (default).
     --no-anchored     Exclude patterns match after any /.
     --ignore-case     Exclude patterns ignore case.
     --no-ignore-case  Exclude patterns are case sensitive (default).
     --wildcards       Exclude patterns use wildcards (default).
     --no-wildcards    Exclude patterns are plain strings.
                       Exclude pattern wildcards match '/' (default).
        Exclude pattern wildcards do not match '/'.
     --uncompress      Filter the archive through compress(1).
     --gunzip       Filter the archive through gzip(1).
     --use-compress-program program
                    Filter the archive through program (which must
                    accept -d to mean `decompress').
     -[0-7][lmh]    Specify tape drive and density.


To tar and zip a file

  tar -czvf MyArchive.tgz Source_file 
or in full
  tar --create --gzip --verbose --file=MyArchive.tgz Source_file

To tar a folder (with all sub-folders and files)

  tar czf /volumes/myexternaldrive/backup01.tgz myfolder

The reverse process to extract the file

  tar -xzvf MyArchive.tgz Destination_file 
  tar --extract --gunzip --verbose --file=MyArchive.tgz Destination_file

  tar xzvf /volumes/myexternaldrive/backup01.tgz myfolder/subfolder/thefiletorestore

Extract a file, autodetecting the format, in this case an xz archive:

  tar -xf some.tar.xz

To extract all the C sources and headers from an archive named backup.tar:

  tar xf backup.tar '*.[ch]'

Note that the pattern must be quoted to prevent the shell from attempting to expand it according the files in the current working directory (the shell does not have access to the list of files in the archive, of course).

To move file hierarchies, use a command line like this:

  tar -cf - -C srcdir . | tar xpf - -C destdir

To create a compressed archive on diskette, using gzip(1), use a command-line like:

  tar --block-compress -z -c -v -f /dev/fd1a -b 36 tar/

Note that you cannot mix bundled flags and --style flags; you can use single-letter flags in the manner above, rather than having to type tar --block-compress --gzip --verbose --file /dev/fd1a --block-size 20 tar/

The above-created diskette can be listed with
tar tvfbz /dev/fd1a 36

To join two gnutar archives into a single archive, use

tar Af archive1.tar archive2.tar

which will add the files contained in archive2.tar onto the end of
archive1.tar (note that this can't be done by simply typing:

cat archive2.tar >> archive1.tar

because of the end-of-file block at the end of a gnutar archive).

To archive all files from the directory srcdir, which were modified after
Feb. 9th 1997, 13:00 h, use

   tar -c -f backup.tar --newer-mtime 'Feb 9 13:15 1997' srcdir/

Other possible time specifications are `02/09/97 13:15', `1997-02-09
13:15', `13:15 9 Feb 1997', `9 Feb 1997 13:15', `Feb. 9, 1997 1:15pm',
`09-Feb', `3 weeks ago' or `May first Sunday'.  To specify the correct
time zone use either e.g. `13:15 CEST' or `13:15+200'.


Always tar -t before tar -x to check if the archive contents have been placed inside one subdirectory or will just spill all over the current directory.

The -C feature does not work like historical gnutar programs, and is probably untrustworthy.

The -A command should work to join an arbitrary number of gnutar archives together, but it does not; attempting to do so leaves the end-of-archive blocks in place for the second and subsequent archives.

The gnutar file format is a semi fixed width field format, and the field for device numbers were designed for 16 bit (8 major, 8 minor) and can not absorb our 32 bit (8 major, 16+8 minor) numbers.

Environment Variables

     POSIXLY_CORRECT  Normally, gnutar will process flag arguments that appear
        in the file list.  If set in the environment, this
        causes gnutar to consider the first non-flag argument to
        terminate flag processing, as per the POSIX specification.

     SHELL       In interactive mode, a permissible response to the
        prompt is to request to spawn a subshell, which will be
        /bin/sh unless the SHELL variable is set.

        Sets the backup suffix used by gnutar.  Default is '~'.

     TAPE       Changes gnutar's default tape drive /dev/sa0 (which is still
        overridden by the -f flag).

     TAR_OPTIONS      The environment variable TAR_OPTIONS can hold a set of
        default options for gnutar.  These options are inter-
        preted first and can be overwritten by explicit command
        line parameters.

     TAR_RSH       The TAR_RSH environment variable allows you to override
        the default shell used as the transport for gnutar.

     VERSION_CONTROL  Sets the backup method used by gnutar.  Possible values:

        t, numbered      Make numbered backups

        nil, existing    Numbered if numbered backups exist,
           simple otherwise

        never, simple    Always make simple backups
        Default behaviour is 'existing'.

"To disarm the bomb simply enter a valid tar command on your first try. No Googling" ~ XKCD

Related macOS commands:

cpio - Copy files to and from archives.
compress - compress and expand data.
gzip - Compress or decompress files.
rmt - remote magtape protocol module.
info tar

Copyright © SS64.com 1999-2019
Some rights reserved