ggttaarr -- Command

Archiving/backup utility
ggttaarr _o_p_t_i_o_n_s

ggttaarr is the GNU version of  the archiving utility ttaarr. It copies files into
or out of a ttaarr archive,  reads the contents of a ttaarr 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.

ggttaarr works in either of two modes:

_C_o_p_y-_i_n _M_o_d_e
     ggttaarr 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f (described below)  to name the file  or device that
     holds the archive you want read.

     ggttaarr 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,
     ggttaarr extracts all files.

_C_o_p_y-_o_u_t _M_o_d_e
     ggttaarr copies files  into an archive.  By default, ggttaarr  reads a list of
     file names,  one per line,  from the standard input.   However, if the
     command  line contains  non-option arguments, ggttaarr  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  ggttaarr recursively
     copies all files within that directory into the archive.

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

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

_O_p_t_i_o_n_s
ggttaarr 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 ggttaarr works:

-AA
--ccaatteennaattee
--ccoonnccaatteennaattee
     Append files onto an archive.

-cc
--ccrreeaattee
     Create a new archive.

-dd
--ddiiffff
--ccoommppaarree
     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.

--ddeelleettee
     Delete files  from the archive.   Do not for  use this option  with an
     archive that is on a magnetic tape.

-rr
--aappppeenndd
     Replace files within  an archive.  If a file does  not exist within an
     archive, append it onto the archive.

-tt
--lliisstt
     List the contents of an archive.

-uu
--uuppddaattee
     Append  a  file  onto an  archive  only  if  it  is younger  than  the
     identically named file within the archive.

--uussee-ccoommpprreessss-pprrooggrraamm
     Specify the compression program to use.  By default, ggttaarr invokes ggzziipp
     to compress files.

-xx
--eexxttrraacctt
--ggeett
     Extract files from the archive.

The following options modify other aspects of ggttaarr's behavior:

--aattiimmee-pprreesseerrvvee
     Do not change  the access times on files, whether  copying into or out
     of an archive.

-bb _N
--bblloocckk-ssiizzee _N
     Use a block size of _Nx512  bytes.  By default, ggttaarr uses an _N of 20 --
     that is, a block size of ten kilobytes.

-BB
--rreeaadd-ffuullll-bblloocckkss
     Tell ggttaarr to reblock as it  reads.  This is required for reading pipes
     under Berkeley UNIX release 4.2, and does not apply to COHERENT.

--bblloocckk-ccoommpprreessss [ccoommpprreessss|ggzziipp]
     Block the output of the  compression program for tapes.  You must name
     one of the compression options to use: either ccoommpprreessss or ggzziipp.

-CC _d_i_r_e_c_t_o_r_y
--ddiirreeccttoorryy _d_i_r_e_c_t_o_r_y
     Change to _d_i_r_e_c_t_o_r_y.

--cchheecckkppooiinntt
     Print directory names while reading the archive.

--eexxcclluuddee _f_i_l_e
     Do not include _f_i_l_e when archiving or de-archiving files.  _f_i_l_e can be
     a regular expression.

-ff _f_i_l_e
--ffiillee _f_i_l_e
     Read the  input from, or write  the output to, _f_i_l_e.  _f_i_l_e 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, ggttaarr by  default reads from
     the standard input and writes to the standard output.

--ffoorrccee-llooccaall
     The archive  file is local  even if its  name contains a  colon.  ggttaarr
     usually interprets a file name that  contains a colon as naming a file
     on a remote system that is connected via a network.

-FF _s_c_r_i_p_t
--iinnffoo-ssccrriipptt _s_c_r_i_p_t
--nneeww-vvoolluummee-ssccrriipptt _s_c_r_i_p_t
     At the end  of each tape (or disk), run  _s_c_r_i_p_t. Note that this option
     implies that you are also using option -MM.

-GG [_f_i_l_e ...]
--iinnccrreemmeennttaall
     Create, list, or  extract every _f_i_l_e that is in  an archive written in
     the format  of the old GNU  incremental backup.  If no  _f_i_l_e is named,
     all ggttaarr extracts all files.

-gg
--lliisstteedd-iinnccrreemmeennttaall
     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i
--iiggnnoorree-zzeerrooss
     Ignore blocks of zeros in archive.

--iiggnnoorree-ffaaiilleedd-rreeaadd
     ggttaarr  normally  exits  with  non-zero  status  when it  encounters  an
     unreadable file.   With this option, ggttaarr  ignores the unreadable file
     and continues to work.

-kk
--kkeeeepp-oolldd-ffiilleess
     If a  file being  extracted from an  archive has an  identically named
     analogue in the file system,  ggttaarr normally overwrites the file in the
     file system  with the  file withdrawn  from the archive.   This option
     tells ggttaarr to rename the file  that is in the file system, rather than
     overwrite it.

-KK ffiillee
--ssttaarrttiinngg-ffiillee _f_i_l_e
     Keep option: begin work with _f_i_l_e in the archive.

-ll
--oonnee-ffiillee-ssyysstteemm
     Stay in the local file system when creating an archive.

-LL _N
--ttaappee-lleennggtthh _N
     Change  tapes after  writing _Nx1,024  bytes.   ggttaarr 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m
--mmooddiiffiiccaattiioonn-ttiimmee
     Do not extract file modified time.

-MM
--mmuullttii-vvoolluummee
     Create, list,  or extract  a multi-volume  archive.  You can  use this
     option  with multiple  -ff options.   ggttaarr 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 ggttaarr is  writing to the other.
     Note that if  you are using this option to  create an archive, be _v_e_r_y
     careful to label  disks or tapes correctly to note  the order in which
     they were written.

-NN _d_a_t_e
--aafftteerr-ddaattee _d_a_t_e
--nneewweerr _d_a_t_e
     Only store files newer than _d_a_t_e.

-oo
--oolldd-aarrcchhiivvee
--ppoorrttaabbiilliittyy
     Write a V7-format archive, rather than an ANSI-format archive.

-OO
--ttoo-ssttddoouutt
     Write files to the standard output.

-pp
--ssaammee-ppeerrmmiissssiioonnss
--pprreesseerrvvee-ppeerrmmiissssiioonnss
     Preserve the permissions that the file had originally.

-PP
--aabbssoolluuttee-ppaatthhss
     Do not strip leading `/'s from file names.

--pprreesseerrvvee
     This option is identical to -pp plus -ss.

-RR
--rreeccoorrdd-nnuummbbeerr
     Show record number within archive with each message.

--rreemmoovvee-ffiilleess
     Remove files after adding them to the archive.

-ss
--ssaammee-oorrddeerr
--pprreesseerrvvee-oorrddeerr
     Sort the  list of  names to  extract to match  their order  within the
     archive.

--ssaammee-oowwnneerr
     Create extracted  files with  the same  ownership they had  within the
     archive.

-SS
--ssppaarrssee
     Handle sparse  files efficiently.  For a description  of what a _s_p_a_r_s_e
     _f_i_l_e is, see the Lexicon entry for cchhssiizzee().

--sshhooww-oommiitttteedd-ddiirrss
     Print the names of directories omitted from the archive.

-TT ffiillee
--ffiilleess-ffrroomm _f_i_l_e
     Read from _f_i_l_e the names of all files to archive or extract.

--nnuullll
     Modify option -TT so  that it reads null-terminated names.  This option
     disables option -CC.

--ttoottaallss
     Print the number of bytes written with option -cc.

--uussee-ccoommpprreessss-pprrooggrraamm _p_r_o_g_r_a_m
     Filter  the archive  through _p_r_o_g_r_a_m.  Note  that _p_r_o_g_r_a_m  must accept
     option -dd.

-vv
--vveerrbboossee
     Write the names of all files archived or extracted.  When you also use
     the option -ff, ggttaarr writes  the names to the standard output; however,
     when you do not use -ff, it writes them to the standard error.

-VV _n_a_m_e
--llaabbeell _n_a_m_e
     Name the  archive _n_a_m_e. When used with the  option --eexxttrraacctt, _n_a_m_e can
     be a regular expression.

--vveerrssiioonn
     Print the version of ggttaarr that you are using.

--vvoollnnoo-ffiillee _f_i_l_e
     Read from  _f_i_l_e the volume number used when  prompting the user.  Note
     that ggttaarr  does not use  the contents of  _f_i_l_e when it  records volume
     identifiers on the archive.

-ww
--iinntteerraaccttiivvee
--ccoonnffiirrmmaattiioonn
     Ask the user to confirm every action.

-WW
--vveerriiffyy
     Attempt to verify the archive after writing it.

-XX _f_i_l_e
--eexxcclluuddee-ffrroomm _f_i_l_e
     Do _n_o_t archive or de-archive all of the files named in _f_i_l_e.

-ZZ
--ccoommpprreessss
--uunnccoommpprreessss
     Filter files being archived or de-archived through ccoommpprreessss.

-zz
--ggzziipp
--uunnggzziipp
     Filter files being archived or de-archived through ggzziipp.

_E_x_a_m_p_l_e_s
The first example archives ppiiggggyy, into archive ppiiggggyy.ttaarr:

    gtar -cf piggy.tar piggy

To simultaneously compress ppiiggggyy with the utility ggzziipp, use the command:

    gtar -czf piggy.gtz piggy

Note that  the suffix  .ggttzz 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z option to de-archive a  compress archive, ggttaarr will
fail.   So, to  extract file  ppiiggggyy  from its  compressed archive,  use the
command:

    gtar -xzf piggy.gtz piggy

The -z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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 ffddffoorrmmaatt, but does not need  to have a COHERENT
file system on it; in fact, ggttaarr will overwrite all file-system information
that may reside  on a disk.  For example, to  write file ppiiggggyy onto a high-
density, 5.25-inch,  formatted floppy  disk in  drive 0, use  the following
command:

    gtar -czf /dev/fha0 piggy

To copy ppiiggggyy back from this archive, use the command:

    gtar -xzf /dev/fha0

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

As noted above,  if you name a directory on  ggttaarr's command line, ggttaarr 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v tells ggttaarr  to name every  file that it is  copying into its
archive.  Note, too, that ggttaarr 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  ccppiioo instead:  it is
somewhat easier to use when you are handling multiple-volume archives.

To copy directory  ssrrcc to the SCSI tape device  with SCSI identifier 2, use
the command:

    tar cvzf /dev/rStp2 src

To archive ssrrcc 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 ssrrcc from its tape, use the command:

    tar xvzf /dev/rStp2

ggttaarr 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p. For example, to restore ssrrcc
and restore  the original ownership  and permissions of its  files, use the
command:

    tar xvpzf /dev/rStp2

_S_e_e _A_l_s_o
ccoommmmaannddss, ggnnuuccppiioo, ttaarr
POSIX Standard, section 10.1.1

_N_o_t_e_s
COHERENT does  not yet support networking.  The  above descriptions of host
addressing do not yet apply.

ggttaarr is  released under  the conditions  of the Free  Software Foundation's
``copyleft''.   Full source  code is  available  through the  Mark Williams
bulletin board.
