NAME

gnutar − GNU tape archiver

SYNOPSIS

tar [ options ] [ name ... ]

DESCRIPTION

gnutar saves and restores multiple files in a single archive (usually a magnetic tape).  It was created by John Gilmore for the GNU Project and distributed by the Free Software Foundation. For complete documentation of gnutar, see the GNU Tape Archiver Manual in /usr/lib/emacs/info/gnutar. 

You can use gnutar in the same way as the UNIX tar command. You specify a single-letter option to perform the following functions: create an archive, extract files from an archive, modify an archive, or list the contents of an archive. The other argument to gnutar is one or more file or directory names specifying which files to dump or restore. In all cases, a directory name refers to the files and (recursively) subdirectories of that directory. 
 
gnutar does not require that you precede an option with a dash (-).  This means that the commands gnutar c and gnutar -c both create an archive. gnutar also provides named options that can be used with a single-letter options or instead of a single-letter option.  A named option is preceded with two dashes (--). Other advantages of gnutar include: path names up to 1024 characters long, archival of device files, and built-in file compression/decompression. 
 

Here are the common single-letter options for gnutar and the UNIX tar command (with the equivalent named options for gnutar also listed):

c --create Create a new tape; writing begins on the beginning of the tape instead of after the last file. 

r --append The named files are written on the end of the tape.  The c function implies this. 

t --list The names of the specified files are listed each time they occur on the tape.  If no file argument is given, all of the names on the tape are listed. 

u --update The named files are added to the tape if either they are not already there or have been modified since last put on the tape. 

x --extract --get The named files are extracted from the tape.  If the named file matches a directory whose contents had been written onto the tape,  this directory is (recursively) extracted.  The owner, modification time, and mode are restored (if possible).  If no file argument is given, the entire content of the tape is extracted.  Note that if multiple entries specifying the same file are on the tape, the last one overwrites all earlier. 

Here are the options that only gnutar supports:

-A --catenate --concatenate
Append tar files to an archive.

-d --diff --compare Find differences between the archive and the file system. 

--delete Delete files from the archive (not used on magnetic tapes). 

--help Display a list of gnutar options. 

You can specify one or more single-letter modifiers (as well as named modifiers) to the options already listed. Here are the common single-letter option modifiers for gnutar and the UNIX tar command (with the equivalent named modifiers for gnutar also listed):

b --block-size gnutar uses the next argument as the blocking factor for tape records. 

B --read-full-blocks Forces input and output blocking so that gnutar can work across a communications channel where the blocking may not be maintained. 

C --directory Allow multiple directories not related by a close common parent to be archived using short relative path names. 

f --file gnutar uses the next argument as the name of the archive instead of a default archive name. If the name of the file is ‘-’, gnutar writes to standard output or reads from standard input, whichever is appropriate. 

h --dereference Force gnutar to follow symbolic links as if they were normal files or directories.  Normally, gnutar does not follow symbolic links. 

l --one-file-system Force gnutar will complain if it cannot resolve all of the links to the files dumped.  If this is not specified, no error messages are printed. 

m --modification-time Force gnutar to not restore the modification times.  The modification time will be the time of extraction. 

o --old-archive --portability
On output, gnutar normally places information specifying owner and modes of directories in the archive. 

p --same-permissions --preserve-permissions
This modifier says to restore files to their original modes, ignoring the present umask(2). Setuid and sticky information will also be restored to the super-user.

v --verbose Normally gnutar does its work silently.  The verbose option makes gnutar print the name of each file it treats preceded by the function letter.  With the t function, the verbose option gives more information about the tape entries than just their names. 

w --interactive --confirmation
gnutar prints the action to be taken followed by file name, then wait for user confirmation. If a word beginning with ‘y’ is given, the action is done. Any other input means don’t do it. 

0, ... ,7 Specify the drive where the magnetic tape is mounted. 

Here are modifiers that only gnutar supports:

--atime-preserve Do not change access times on dumped files. 

--block-compress Block the output of compression program for tapes. 

--checkpoint
Print directory names while reading the archive.

--exclude file
Exclude file. 

--force-local Force the archive file to be local. 

-F --info-script --new-volume-script
Invoke the script script at end of each tape (implies -M). 

-G --incremental Create, list, or extract an old GNU-format incremental backup. 

-g --listed-incremental file
Create, list, or extract a new GNU-format incremental backup.

-i --ignore-zeros Ignore blocks of zeros in the archive (normally means EOF). 

--ignore-failed-read
Do not exit with non-zero status on unreadable files.

-k --keep-old-files Don’t overwrite existing files in the archive. 

-K --starting-file file
Begin at file in the archive. 

-L --tape-length N
Change tapes after writing N∗1024 bytes. 

-M --multi-volume Create, list, or extract a multi-volume archive. 

-N --after-date --newer Store only files newer than date. 

-O --to-stdout Extract files to standard output. 

-P --absolute-paths
Do not strip leading slash marks (//) from file names

--preserve Preserve permissions and file order (like -p -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 the archive.

--same-owner
Create extracted files with the same ownership.

-S --sparse Handle sparse files efficiently. 

--totals Print total bytes written with --create. 

-T --files-from file Get names to extract, or create from file. 

--use-compress-program program
Filter the archive through program (which must accept -d). 

-V --label name Create an archive with volume name name. 

--version Print the gnutar version number

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

-X --exclude-from file
Exclude files listed in file. 

-Z --compress --uncompress
Filter the archive through compress. 

-z --gzip --ungzip
Filter the archive through gzip. 

SEE ALSO

tar(1)

Free Software Foundation, Inc.  —  August 10, 1993