Rowland Industries

tar
Category	Command Line Program
Part Of	GUN Core Utilities
Classification	Tier 1
Official Documentation	GNU tar

1 Description

The tar program is used to create what are called tape archive files. Tape archive files are best used when you want to combine multiple files and or directories into a single file, the resulting file is usually called a tarball. The tarball can then be compressed using the gzip program.

2 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.

3 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.

tar Return Values
Return Value	Description
`0`	Successful termination. `tar` completed successfully.
`1`	Some files differ.
`2`	Fatal error, `tar` was not able to complete.

4 Examples

4.1 How To Create A Compressed Tar File

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.

user-1@vm:~/Documents$ tar czfv archive.tar.gz file_1.txt file_2.txt file_3.txt
file_1.txt
file_2.txt
file_3.txt
user-1@vm:~/Documents$

4.2 How To Extract The Contents Of A Compressed Tar File

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.

user-1@vm:~/Documents$ tar xvf archive.tar.gz
file_1.txt
file_2.txt
file_3.txt
user-1@vm:~/Documents$

4.3 How To List The Contents Of A Compressed Tar File

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.

user-1@vm:~/Documents$ tar tvf archive.tar.gz
-rw-r--r-- user-1/user-1    11 2025-06-27 00:29 file_1.txt
-rw-r--r-- user-1/user-1    11 2025-06-27 00:29 file_2.txt
-rw-r--r-- user-1/user-1    15 2025-06-27 00:29 file_3.txt
user-1@vm:~/Documents$

5 History

5.1 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.

5.2 First Release

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

6 Ancillary Information

6.1 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.

6.2 Related Programs

These programs are related to the tar program and may be of some interest to you.

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

6.3 Bug Reports

Report bugs to bug-tar@gnu.org

tar: The Tape Archive Utility

tar