Documentation Reference Number: #0004

tar

I. Arguments

Operation Arguments

The table below lists the command line options which control what operation tar will perform.

tar is only able to perform a single operation at a time. If you try to perform multiple different operations at the same time tar will return an error.

Argument Description
Short Long
-r --append Append files to the end of an existing archive file. Arguments are the files to be added to the archive.
-A --catenate, --concatenate Append one archive file to the end of another archive file. The arguments are the names of the archives to append. All archive files must be the same format as the archive they are appended to, otherwise the resulting archive may be unusable with non-GNU implementations of tar. Compressed archives cannot be concatenated.
-c --create Will create a new archive file. The arguments provide the names of the files and or directories which will be archived. Directories will be archived recursively, to disable recursive archiving use the --no-recursion option.
--delete Delete files from the specified archive. The arguments declare the names of the archive members to be deleted. At least one argument must be given. This option cannot be used on compressed archives. There is no short option equivalent to --delete.
-d --diff, --compare Find the differences between an archive and a directory. The arguments are optional; arguments specify what archive members to compare. When no arguments are given the current working directory is assumed.
-x --extract, --get Extract files from an archive. When no arguments are given ALL FILES in the archive are extracted. When arguments are given ONLY MATCHING FILES are extracted from the archive.
-? --help Print the help page to STDOUT.
-t --list Print a list of files contained in the archive, arguments are optional. When arguments are given they specify the names of the archive files that will be listed.
--show-defaults Print a list of the default values for various tar options and then exit. Arguments will be ignored.
--test-label Test the archive volume label and exit. When used without arguments, it prints the volume label (if any) and exits with status 0. When one or more command line arguments are given. tar will compare the volume label with each argument given. It will exit with code 0 if a match is found, and it will exit with code 1 if no match is found. No output is printed to STDOUT, unless the --verbose option is given.
-u --update Append files which are newer than the corresponding copy in the archive. The copy which is appended does not replace the copy in the archive, instead it is appended to the end of the archive, thus there may be multiple versions of the same file in the same archive.
--usage Print all options to STDOUT. This is useful if you want to see a list of all options instead of trying to read through the whole man page for tar and remember each option as you go along.
--version Print information about which version of tar is installed, and copyright information to STDOUT, then exit.

II. Return Values

Return Values

The tar exit code indicates whether it successfully completed the requested operaton or, if an error occured, what type of error.

Return Values
Return Value Description
0 Successful termination. Tar completed successfully.
1 Some files differ.
2 Fatal error. This means that a fatal error occured and tar was unable to complete.

III. How To Create A Compressed Tar File

Explanation

The example below demonstrates how to create a compressed tar file (which is a file that ends in .tar.gz) that contains three text files: file_1.txt, file_2.txt, and file_3.txt.

Example 3.1

Creating a compressed tar archive file called archive.tar.gz.
john@comp:~$ tar czfv archive.tar.gz file_1.txt file_2.txt file_3.txt

IV. How To Extract The Contents Of A Compressed Tar File

Explanation

The example below demonstrates how to extract the contents of a compressed tar file called 'archive.tar.gz'. In this example the contents of archive.tar.gz will be placed into the current working directory.

Example 4.1

Extracting the contents of a compressed tar archive file called archive.tar.gz
john@comp:~$ tar xvf archive.tar.gz

V. How To List The Contents Of A Compressed Tar File

Explanation

The example below demonstrates how to list the contents of a compressed tar archive file, but not extract the contents of the archive. This is useful if you want to inspect what is in an archive file without unpacking it.

Example 5.1

Listing the contents of a compressed tar archive file called archive.tar.gz
john@comp:~$ tar tvf archive.tar.gz

VI. History

Name

The name 'tar' comes from the abbreviation of the two words 'tape' and 'archive'. The original primary function of the 'tar' command was to create a file which would then be written to a storage device which used magnetic tape to store binary information, these storage devices were referred to as 'tape drives'. Tape drives are not commonly used anymore but at one point in the history of computers they were the primary means of storing binary data, or a common backup way to store binary data.

Initial Release

The first 'tar' program was created by Bell Laboratories. The first release of the tar program was in January 1979.

VII. Ancillary Information

Major Implementations

Below is a list of the most common implementations of the tar program. These implementations are commonly included with various popular Linux distributions.

Related Programs

These programs may also be of interest.

Name Description
bzip2 A block-sorting file compressor
gzip A file compressor
ln A program for creating soft, or hard links between files
xz A file compressor for xz and lzma files

External Links

The official GNU tar documentation can be found at:

http://www.gnu.org/software/tar/manual

Bug Reports

Report bugs to bug-tar@gnu.org

Examples

The examples provided on this page were generated on 2024-JULY-27 using the Linux based operating system Debian 12.6. The tar program comes installed by default on Debian 12.6.

This page was last updated: .