gtar -- Command

Archiving/backup utility
gtar options

gtar is the GNU version of  the archiving utility tar. It copies files into
or out of a tar archive,  reads the contents of a tar archive, and replaces
files  within an  archive.  It  can also perform  additional tasks  such as
compressing files as they are added to an archive, or uncompressing them as
they are read out.

gtar works in either of two modes:

Copy-in Mode
     gtar copies files from an archive or lists the archive's contents.  By
     default, it  reads the archive  from the standard input;  you can also
     use the  option -f (described below)  to name the file  or device that
     holds the archive you want read.

     gtar regards any non-option argument as a shell wild-card pattern; and
     it copies from  the archive only those files whose  names match one or
     more of  those patterns.  Unlike the  shell, an initial `.'  in a file
     name matches a wildcard at the start of a pattern, and a `/' in a file
     name can  match a wildcard.  If the command  line contains no pattern,
     gtar extracts all files.

Copy-out Mode
     gtar copies files  into an archive.  By default, gtar  reads a list of
     file names,  one per line,  from the standard input.   However, if the
     command  line contains  non-option arguments, gtar  regards each  as a
     shell wild-card pattern that names one  or more files to copy into the
     archive.   If an  argument names  a  directory, then  gtar recursively
     copies all files within that directory into the archive.

     By  default,  gtar writes  its  newly built  archive  to the  standard
     output.  However, you can use  the option -f (described below) to name
     the file or device into gtar writes the new archive.

     gtar normally writes into the  local directory all files that it reads
     from an  archive.  If files  were archived using  absolute path names,
     gtar by default drops the leading  `/' from the path name; to suppress
     this behavior,  use the option  -P, described below.  If  a file being
     extracted  resides  within a  directory  that does  not  exist in  the
     current directory,  gtar will create that  directory.  gtar will fail,
     of  course,  if  you do  not  have  write  permission  in the  current
     directory.

Options

gtar recognizes  the following options.  Please note  that not every option
applies to both modes.

Please note, too, that some options  have more than one name.  Every option
has  a multi-character  name that  begins  with with  two hyphens  --; some
commonly used  options also  have a one-character  name that begins  with a
single  hyphen.  This  convention  may appear  clumsy, but  it does  permit
option names to have hyphens embedded within them.

The following command-line options govern the mode in which gtar works:

-A
--catenate
--concatenate
     Append files onto an archive.

-c
--create
     Create a new archive.

-d
--diff
--compare
     Find  the  differences  between  the  files  in  an  archive  and  the
     identically named  files in the  file system.  This is  very useful in
     verifying that a new archive was built correctly.

--delete
     Delete files  from the archive.   Do not for  use this option  with an
     archive that is on a magnetic tape.

-r
--append
     Replace files within  an archive.  If a file does  not exist within an
     archive, append it onto the archive.

-t
--list
     List the contents of an archive.

-u
--update
     Append  a  file  onto an  archive  only  if  it  is younger  than  the
     identically named file within the archive.

--use-compress-program
     Specify the compression program to use.  By default, gtar invokes gzip
     to compress files.

-x
--extract
--get
     Extract files from the archive.

The following options modify other aspects of gtar's behavior:

--atime-preserve
     Do not change  the access times on files, whether  copying into or out
     of an archive.

-b N
--block-size N
     Use a block  size of N×512 bytes.  By default,  gtar uses an N of
     20 -- that is, a block size of ten kilobytes.

-B
--read-full-blocks
     Tell gtar to reblock as it  reads.  This is required for reading pipes
     under Berkeley UNIX release 4.2, and does not apply to COHERENT.

--block-compress [compress|gzip]
     Block the output of the  compression program for tapes.  You must name
     one of the compression options to use: either compress or gzip.

-C directory
--directory directory
     Change to directory.

--checkpoint
     Print directory names while reading the archive.

--exclude file
     Do not include file when archiving or de-archiving files.  file can be
     a regular expression.

-f file
--file file
     Read the  input from, or write  the output to, file.  file can name an
     ordinary file or a device.  File name `-' indicates the standard input
     or standard output (depending upon whether an archive is being read or
     written).  When  this option is  not used, gtar by  default reads from
     the standard input and writes to the standard output.

--force-local
     The archive  file is local  even if its  name contains a  colon.  gtar
     usually interprets a file name that  contains a colon as naming a file
     on a remote system that is connected via a network.

-F script
--info-script script
--new-volume-script script
     At the end  of each tape (or disk), run  script. Note that this option
     implies that you are also using option -M.

-G [file ...]
--incremental
     Create, list, or  extract every file that is in  an archive written in
     the format  of the old GNU  incremental backup.  If no  file is named,
     all gtar extracts all files.

-g
--listed-incremental
     Create, list, or  extract files that are in an  archive written in the
     format  of the  new GNU  incremental backup.   create/list/extract new
     GNU-format incremental backup

-i
--ignore-zeros
     Ignore blocks of zeros in archive.

--ignore-failed-read
     gtar  normally  exits  with  non-zero  status  when it  encounters  an
     unreadable file.   With this option, gtar  ignores the unreadable file
     and continues to work.

-k
--keep-old-files
     If a  file being  extracted from an  archive has an  identically named
     analogue in the file system,  gtar normally overwrites the file in the
     file system  with the  file withdrawn  from the archive.   This option
     tells gtar to rename the file  that is in the file system, rather than
     overwrite it.

-K file
--starting-file file
     Keep option: begin work with file in the archive.

-l
--one-file-system
     Stay in the local file system when creating an archive.

-L N
--tape-length N
     Change tapes after writing N×1,024 bytes.  gtar normally reads or
     writes until  it reaches the end  of the medium, then  prompts for the
     name of  the next device.   This option, of course,  normally does not
     apply to archives being written to or read from disk.

-m
--modification-time
     Do not extract file modified time.

-M
--multi-volume
     Create, list,  or extract  a multi-volume  archive.  You can  use this
     option  with multiple  -f options.   gtar uses  the output  devices in
     sequence, then  wraps around  to the  beginning.  This lets  you, say,
     write output  to two different tape drives  or floppy-disk drives; you
     can loading blank  media into one while gtar is  writing to the other.
     Note that if  you are using this option to  create an archive, be very
     careful to label  disks or tapes correctly to note  the order in which
     they were written.

-N date
--after-date date
--newer date
     Only store files newer than date.

-o
--old-archive
--portability
     Write a V7-format archive, rather than an ANSI-format archive.

-O
--to-stdout
     Write files to the standard output.

-p
--same-permissions
--preserve-permissions
     Preserve the permissions that the file had originally.

-P
--absolute-paths
     Do not strip leading `/'s from file names.

--preserve
     This option is identical to -p plus -s.

-R
--record-number
     Show record number within archive with each message.

--remove-files
     Remove files after adding them to the archive.

-s
--same-order
--preserve-order
     Sort the  list of  names to  extract to match  their order  within the
     archive.

--same-owner
     Create extracted  files with  the same  ownership they had  within the
     archive.

-S
--sparse
     Handle sparse  files efficiently.  For a description  of what a sparse
     file is, see the Lexicon entry for chsize().

--show-omitted-dirs
     Print the names of directories omitted from the archive.

-T file
--files-from file
     Read from file the names of all files to archive or extract.

--null
     Modify option -T so  that it reads null-terminated names.  This option
     disables option -C.

--totals
     Print the number of bytes written with option -c.

--use-compress-program program
     Filter  the archive  through program.  Note  that program  must accept
     option -d.

-v
--verbose
     Write the names of all files archived or extracted.  When you also use
     the option -f, gtar writes  the names to the standard output; however,
     when you do not use -f, it writes them to the standard error.

-V name
--label name
     Name the  archive name. When used with the  option --extract, name can
     be a regular expression.

--version
     Print the version of gtar that you are using.

--volno-file file
     Read from  file the volume number used when  prompting the user.  Note
     that gtar  does not use  the contents of  file when it  records volume
     identifiers on the archive.

-w
--interactive
--confirmation
     Ask the user to confirm every action.

-W
--verify
     Attempt to verify the archive after writing it.

-X file
--exclude-from file
     Do not archive or de-archive all of the files named in file.

-Z
--compress
--uncompress
     Filter files being archived or de-archived through compress.

-z
--gzip
--ungzip
     Filter files being archived or de-archived through gzip.

Examples

The first example archives piggy, into archive piggy.tar:

    gtar -cf piggy.tar piggy

To simultaneously compress piggy with the utility gzip, use the command:

    gtar -czf piggy.gtz piggy

Note that  the suffix  .gtz is  used by convention  to mark  archives whose
contents are  compressed.  This is not  required, but it is  a good idea to
use this or some similar suffix  to mark compressed archives: if you do not
remember to use  the -z option to de-archive a  compress archive, gtar will
fail.   So, to  extract file  piggy  from its  compressed archive,  use the
command:

    gtar -xzf piggy.gtz piggy

The -z is recommended: it speeds  archiving of large files or file systems,
and increases their accuracy -- because the archives are smaller, there are
fewer opportunities for errors to occur.

To write  an archive onto a  device, use the option -f  to name that device
instead of  a file.   You must,  of course, have  write permission  on that
device.  If  you are writing  onto a floppy  disk, the disk  must have been
formatted with the  command fdformat, but does not need  to have a COHERENT
file system on it; in fact, gtar will overwrite all file-system information
that may reside  on a disk.  For example, to  write file piggy onto a high-
density, 5.25-inch,  formatted floppy  disk in  drive 0, use  the following
command:

    gtar -czf /dev/fha0 piggy

To copy piggy back from this archive, use the command:

    gtar -xzf /dev/fha0

As noted above, you must remember  to use the -z option to de-archive files
from a compressed archive.

As noted above,  if you name a directory on  gtar's command line, gtar will
archive  or  de-archive that  directory  and all  files  that it  contains,
including its sub-directories  and their contents.  For example, to archive
all of your personal files, use the command:

    gtar -cvzf backup.gtz $HOME

The option  -v tells gtar  to name every  file that it is  copying into its
archive.  Note, too, that gtar is  smart enough not to copy an archive into
itself, so you  can execute the above command while  still within your home
directory.

The following  backs up your  personal files onto  a high-density, 3.5-inch
disk in drive 0:

    gtar -cvzf /dev/fva0 $HOME

NB,  if you  are backing  up a  directory that will  require more  than one
floppy  disk, you  should consider  using the utility  cpio instead:  it is
somewhat easier to use when you are handling multiple-volume archives.

To copy directory  src to the SCSI tape device  with SCSI identifier 2, use
the command:

    tar cvzf /dev/rStp2 src

To archive src to a tape and then confirm it, use the command

    tar cvzf /dev/rStp2 src ; tar dvzf /dev/rStp2 src

Note that  this can be  time consuming, but  will confirm the  integrity of
backups of vital files.  To restore src from its tape, use the command:

    tar xvzf /dev/rStp2

gtar by default saves files with their original ownerships and permissions;
however, when it restores files, it may modify them.  To restore files with
their original permissions, use the  option -p. For example, to restore src
and restore  the original ownership  and permissions of its  files, use the
command:

    tar xvpzf /dev/rStp2

See Also

commands,
compression,
gnucpio,
tar
POSIX Standard, §10.1.1

Notes

COHERENT does  not yet support networking.  The  above descriptions of host
addressing do not yet apply.

gtar is  released under  the conditions  of the Free  Software Foundation's
``copyleft''.   Full source  code is  available  through the  Mark Williams
bulletin board.

© 2012 by Stephen A. Ness