TAR(1)

📦
version 1.35 · 4 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, centos-stream 10, debian trixie, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 NAME 🎀

okay bestie, this is the TAR(1) page from the GNU TAR Manual 💖 and tar is literally just "an archiving utility" 📦✨

💅 SYNOPSIS 💅

🧚 Traditional usage

tar {A|c|d|r|t|u|x}[GnSkUWOmpsMBiajJzZhPlRvwo] [ARG...]

🦋 UNIX-style usage

tar -A [OPTIONS] -f ARCHIVE ARCHIVE...

tar -c [-f ARCHIVE] [OPTIONS] [FILE...]

tar -d [-f ARCHIVE] [OPTIONS] [FILE...]

tar -r [-f ARCHIVE] [OPTIONS] [FILE...]

tar -t [-f ARCHIVE] [OPTIONS] [MEMBER...]

tar -u [-f ARCHIVE] [OPTIONS] [FILE...]

tar -x [-f ARCHIVE] [OPTIONS] [MEMBER...]

🌸 GNU-style usage

tar {--catenate|--concatenate} [OPTIONS] --file ARCHIVE ARCHIVE...

tar --create [--file ARCHIVE] [OPTIONS] [FILE...]

tar {--diff|--compare} [--file ARCHIVE] [OPTIONS] [FILE...]

tar --delete [--file ARCHIVE] [OPTIONS] [MEMBER...]

tar --append [--file ARCHIVE] [OPTIONS] [FILE...]

tar --list [--file ARCHIVE] [OPTIONS] [MEMBER...]

tar --test-label [--file ARCHIVE] [OPTIONS] [LABEL...]

tar --update [--file ARCHIVE] [OPTIONS] [FILE...]

tar {--extract|--get} [--file ARCHIVE] [OPTIONS] [MEMBER...]

📝 NOTE 📝

ngl this part is so important 🙈 This manpage is just a short description of GNU tar. If you want the full deep dive, with examples and usage recommendations, go read the GNU Tar Manual, which comes in texinfo format. If the info reader and the tar docs are properly installed on your system, this command

info tar

should pull up the complete manual for you 📖

You can also read the manual through the info mode in emacs(1), or find it in a bunch of formats online at

https://www.gnu.org/software/tar/manual
⚠️ bestie, if this page and the GNU Tar Manual ever disagree, the GNU Tar Manual wins. It's the authoritative source, no debate 💅

🌈 DESCRIPTION 🌈

okay so GNU tar is an archiving program that lets you stash multiple files into a single file (an archive) and then mess around with those archives 📦💖 The archive can be a regular file or a device, like a tape drive (which is literally where the name comes from, it stands for tape archiver 📼). It can live on your local machine or on a remote one, which is giving flexibility 🦋

🎀 Option styles

okay this part is the vibe check for how you actually type options ✨ GNU tar lets you write options in three different styles, and honestly they're all valid, you just need to know which one you're looking at 👀

In the traditional style, the first argument is a cluster of option letters, and every argument after that supplies the arguments for whichever options need them. The arguments get read in the same order as the option letters. Any command line words left over after all the options are processed are treated as non-option arguments, which means file or archive member names 📂

For example, the c option means create the archive, the v option asks for verbose output, and the f option takes an argument that names the archive you're working on. So this command, written in the traditional style, tells tar to store everything from the directory /etc into the archive file etc.tar, and it'll verbosely list each file as it goes 🌸

tar cfv etc.tar /etc

In UNIX or short-option style, every option letter gets a single dash in front, like other command line tools 🧚 If an option takes an argument, that argument follows it, either as its own separate command line word or stuck right after the option. BUT if the option takes an optional argument, the argument has to come right after the option letter with zero whitespace in between, like -g/tmp/snar.db 🙈

You can clump any number of options that don't take arguments together after one dash, like -vkp. An option that does take an argument (mandatory or optional) can sit at the end of that cluster, like -vkpf a.tar 💅

Here's the example command from up top, written in short-option style:

tar -cvf etc.tar /etc

or

tar -c -v -f etc.tar /etc

Then there's the GNU or long-option style, where each option starts with two dashes and has a meaningful name made of lower-case letters and dashes ✨ You can shorten a long option down to its initial letters, as long as that doesn't make it ambiguous. Arguments to long options can be a separate command line word, right after the option, or joined to the option with an equals sign and no whitespace. Optional arguments always have to use the equals-sign method, no exceptions 🫶

Here are a few ways to write the example command in this style:

tar --create --file etc.tar --verbose /etc

or, abbreviating some options:

tar --cre --file=etc.tar --verb /etc

Just a heads up: the options in all three styles can be mixed together in one command. That said, mixing them with the old options isn't encouraged 🙈

🍓 Operation mode

The options listed in the table below tell GNU tar what operation it's supposed to perform 💜 You have to give exactly one of them. What the non-option arguments mean depends on which operation mode you picked 👑

  • -A, --catenate, --concatenate — okay so this one appends archives to the end of another archive 📦 The arguments are the names of the archives you want to tack on. All of them have to be the same format as the archive they're getting appended to, otherwise the result might be unusable with non-GNU versions of tar 💀 Also, when you give more than one archive, the members from every archive except the first one will only be accessible in the resulting archive if you use the -i (--ignore-zeros) option.

Compressed archives cannot be concatenated. 🚫

  • -c, --create — make a brand new archive ✨ The arguments are the names of the files you want archived. Directories get archived recursively, unless you pass the --no-recursion option 🌳
  • -d, --diff, --compare — find the differences between the archive and the file system 🔍 The arguments are optional and name the archive members you want compared. If you don't give any, the current working directory is assumed 📁
  • --delete — delete stuff from the archive 🗑️ The arguments are the names of the archive members to remove. You need to give at least one argument, no freebies here.

This option does not work on compressed archives. There's also no short option for it. 🙅‍♀️

  • -r, --append — append files to the end of an archive 💖 The arguments mean the same thing they do for -c (--create).
  • -t, --list — list the contents of an archive 📜 The arguments are optional. If you give some, they name the members you want listed.
  • --test-label — test the archive volume label and then exit 🏷️ Used without arguments, it prints the volume label (if there is one) and exits with status 0. When you give one or more command line arguments, tar compares the volume label against each argument. It exits with code 0 if it finds a match, and with code 1 otherwise. No output is displayed unless you combine it with the -v (--verbose) option.

There's no short option equivalent for this one 🙈

  • -u, --update — append files that are newer than their matching copy in the archive ⏰ The arguments mean the same thing they do for -c and -r. Here's the tea though: newer files don't replace their old copies in the archive. They get appended to the end instead, so the resulting archive can have several members with the same name, one for each version of the file 🦋
  • -x, --extract, --get — extract files from an archive 🎁 The arguments are optional. If you give some, they name the archive members you want extracted.
  • --show-defaults — show the built-in defaults for various tar options and then exit 🧐
  • -?, --help — display a short option summary and exit 💁‍♀️
  • --usage — display a list of the available options and exit 📋
  • --version — print the program version and copyright information, then exit 🌈

👑 OPTIONS 👑

🧁 Operation modifiers

  • --check-device — check device numbers when creating incremental archives. This is the default 🔧
  • -g, --listed-incremental=FILE — handle new GNU-format incremental backups 📸 FILE is the name of a snapshot file, where tar stores extra info it uses to figure out which files changed since the previous incremental dump, and which therefore need to be dumped again. If FILE doesn't exist when you're creating an archive, tar creates it and adds all files to the resulting archive (this is the level 0 dump). To make incremental archives of a non-zero level N, you need a copy of the snapshot file made for level N-1, and you use that copy as FILE 🧠

When you're listing or extracting, the actual content of FILE doesn't get inspected. It's only needed because of syntax requirements, so it's super common to use /dev/null in its place 🕳️

  • --hole-detection=METHOD — use METHOD to detect holes in sparse files 🕳️ This option implies --sparse. The valid values for METHOD are seek and raw. The default is seek, with a fallback to raw when seek isn't applicable.
  • -G, --incremental — handle old GNU-format incremental backups 🗂️
  • --ignore-failed-read — don't exit with a nonzero status just because some files couldn't be read 🙃
  • --level=NUMBER — set the dump level for a created listed-incremental archive 🎚️ Right now, only --level=0 actually means anything. It tells tar to truncate the snapshot file before dumping, which forces a level 0 dump.
  • -n, --seek — assume the archive is seekable 🔎 Normally tar figures out on its own whether the archive can be seeked, but this option is for when that detection goes wrong. It only takes effect if the archive is open for reading (for example, with --list or --extract).
  • --no-check-device — don't check device numbers when creating incremental archives 🙅‍♀️
  • --no-seek — assume the archive is not seekable 🚫
  • --occurrence[=N] — process only the Nth occurrence of each file in the archive 🔢 This option is only valid with one of these subcommands: --delete, --diff, --extract or --list, and only when a list of files is given either on the command line or via the -T option. The default N is 1.
  • --restrict — disable some potentially harmful options 🛡️
  • --sparse-version=MAJOR[.MINOR] — set which version of the sparse format to use 🧩 This option implies --sparse. The valid argument values are 0.0, 0.1 and 1.0. For a detailed discussion of sparse formats, check out the GNU Tar Manual, appendix D, "Sparse Formats". You can read it with the info reader by running this command: info tar 'Sparse Formats' 📖💜

-S, --sparse

Okay so this one is for the files with secret empty holes in them 🕳️✨ Some files in your file system have segments that were never actually written (usually database files made by stuff like DBM 💀). With this option, tar tries to figure out whether the file is sparse before archiving it, and if it is, it skips dumping those empty parts so the archive comes out smaller. Efficiency is giving 💅

✨ Overwrite control ✨

These options decide what tar does when you're extracting a file and there's already a copy of it sitting on disk. Major decision-making energy 👑

  • -k, --keep-old-files — Don't replace existing files when extracting. Your old stuff stays put 🧸
  • --keep-newer-files — Don't replace existing files that are newer than their archive copies. If your version is fresher, tar leaves it alone 🫶
  • --keep-directory-symlink — Don't replace existing symlinks to directories when extracting 🔗
  • --no-overwrite-dir — Preserve metadata of existing directories 📁
  • --one-top-level[=DIR] — Extract everything into DIR. If you use it with no argument, tar makes a subdirectory named after the archive's base name, with the standard compression suffixes that --auto-compress recognizes chopped off 🌸
  • --overwrite — Overwrite existing files when extracting 🔥
  • --overwrite-dir — Overwrite metadata of existing directories when extracting (this is the default) 💖
  • --recursive-unlink — Recursively remove all files in the directory before extracting it. Full clean sweep 🧹
  • --remove-files — Remove files from disk after adding them to the archive. Gone after archiving, no cap 💀
  • --skip-old-files — Don't replace existing files when extracting, and silently skip over them. No drama, no notification 🙈
  • -U, --unlink-first — Remove each file before extracting over it 🦋
  • -W, --verify — Verify the archive after writing it. Double-checking is a whole vibe ✨

✨ Output stream selection ✨

Where do the files end up? Let's talk destinations 🎀

  • --ignore-command-error — Ignore subprocess exit codes 🙃
  • --no-ignore-command-error — Treat non-zero exit codes of children as errors (this is the default) 🚨
  • -O, --to-stdout — Extract files to standard output 📤
  • --to-command=COMMAND — Pipe extracted files into COMMAND. The argument is the pathname of an external program, and you can add command line arguments too. That program gets invoked, and the contents of the file being extracted get fed to it on its standard input. Extra info comes through these environment variables 🧚
    • TAR_FILETYPE — The type of the file, given as a single letter with this meaning:
f           Regular file
d           Directory
l           Symbolic link
h           Hard link
b           Block device
c           Character device

Currently only regular files are supported. 🥺

  • TAR_MODE — The file mode, as an octal number 🔢
  • TAR_FILENAME — The name of the file 📝
  • TAR_REALNAME — The name of the file as stored in the archive 🗂️
  • TAR_UNAME — The name of the file owner 👤
  • TAR_GNAME — The name of the file owner's group 👥
  • TAR_ATIME — The time of last access. It's a decimal number of seconds since the Epoch. If the archive stores times with nanosecond precision, the nanoseconds get tacked on after a decimal point ⏰
  • TAR_MTIME — The time of last modification 🕰️
  • TAR_CTIME — The time of last status change 🕒
  • TAR_SIZE — The size of the file 📏
  • TAR_UID — The UID of the file owner 🆔
  • TAR_GID — The GID of the file owner 🆔

Plus, these variables tell you about the tar operation mode and the archive being processed. Extra context, extra iconic 🌈

  • TAR_VERSION — The GNU tar version number 🏷️
  • TAR_ARCHIVE — The name of the archive tar is processing 📦
  • TAR_BLOCKING_FACTOR — The current blocking factor, meaning the number of 512-byte blocks in a record 🧱
  • TAR_VOLUME — The ordinal number of the volume tar is processing (only set when reading a multi-volume archive) 📚
  • TAR_FORMAT — The format of the archive being processed. One of: gnu, oldgnu, posix, ustar, v7 🗃️
  • TAR_SUBCOMMAND — A short option (with a leading dash) describing the operation tar is currently running 🏃‍♀️

✨ Handling of file attributes ✨

This is the glow-up section, where we get into how files look and who they belong to 🪞💅

  • --atime-preserve[=METHOD] — Preserve access times on dumped files. You can do this either by restoring the times after reading (METHOD=replace, which is the default) or by not setting the times in the first place (METHOD=system) ⏳
  • --delay-directory-restore — Delay setting modification times and permissions of extracted directories until the end of extraction. Use this one when you're extracting from an archive with unusual member ordering 🧩
  • --group=NAME[:GID] — Force NAME as the group for added files. If GID isn't supplied, NAME can be either a user name or a numeric GID. In that case, the missing part (the GID or the name) gets inferred from the current host's group database 👯

When used with --group-map=FILE, this only affects files whose owner group isn't listed in FILE 🎯

  • --group-map=FILE — Read the group translation map from FILE. Empty lines get ignored. Comments start with a # sign and run to the end of the line. Each non-empty line in FILE defines a translation for a single group. Each line has to contain two fields, separated by any amount of whitespace:
OLDGRP NEWGRP[:NEWGID]

OLDGRP is either a valid group name or a GID prefixed with +. Unless NEWGID is supplied, NEWGRP also has to be either a valid group name or a +GID. Otherwise, neither NEWGRP nor NEWGID needs to be in the system group database. 🗺️

The result: every input file with owner group OLDGRP gets stored in the archive with owner group NEWGRP and GID NEWGID 🔁

  • --mode=CHANGES — Force the symbolic mode CHANGES onto added files 🎨
  • --mtime=DATE-OR-FILE — Set the mtime for added files. DATE-OR-FILE is either a date/time in almost any format you can think of, or the name of an existing file. If it's a file, that file's mtime gets used 📅
  • -m, --touch — Don't extract file modified time 🫥
  • --no-delay-directory-restore — Cancel the effect of the earlier --delay-directory-restore option 🙅‍♀️
  • --no-same-owner — Extract files as yourself (this is the default for ordinary users) 🙋‍♀️
  • --no-same-permissions — Apply the user's umask when extracting permissions from the archive (this is the default for ordinary users) 🛡️
  • --numeric-owner — Always use numbers for user/group names 🔢
  • --owner=NAME[:UID] — Force NAME as the owner for added files. If UID isn't supplied, NAME can be either a user name or a numeric UID. In that case, the missing part (the UID or the name) gets inferred from the current host's user database 🪪

When used with --owner-map=FILE, this only affects files whose owner isn't listed in FILE 🎯

  • --owner-map=FILE — Read the owner translation map from FILE. Empty lines get ignored. Comments start with a # sign and run to the end of the line. Each non-empty line in FILE defines a translation for a single UID. Each line has to contain two fields, separated by any amount of whitespace:
OLDUSR NEWUSR[:NEWUID]

OLDUSR is either a valid user name or a UID prefixed with +. Unless NEWUID is supplied, NEWUSR also has to be either a valid user name or a +UID. Otherwise, neither NEWUSR nor NEWUID needs to be in the system user database. 🗺️

The result: every input file owned by OLDUSR gets stored in the archive with owner name NEWUSR and UID NEWUID 🔁

  • -p, --preserve-permissions, --same-permissions — Set the permissions of extracted files to whatever is recorded in the archive (this is the default for the superuser) 🔐
  • --same-owner — Try extracting files with the same ownership they have in the archive (this is the default for the superuser) 👑
  • -s, --preserve-order, --same-order — Tell tar that the list of file names to process is sorted in the same order as the files in the archive 📋
  • --sort=ORDER — When creating an archive, sort directory entries according to ORDER, which is one of none, name, or inode 🗂️

The default is --sort=none, which stores archive members in whatever order the operating system returns them 🤷‍♀️

--sort=name makes the member ordering in the created archive uniform and reproducible 🔁

--sort=inode cuts down on the number of disk seeks made while creating the archive, so it can seriously speed things up 🏎️ This sorting order only works if the underlying system provides the information it needs ⚠️

✨ Extended file attributes ✨

The extra stuff that rides along with your files 💜

  • --acls — Enable POSIX ACLs support 🧾
  • --no-acls — Disable POSIX ACLs support 🚫
  • --selinux — Enable SELinux context support 🛡️
  • --no-selinux — Disable SELinux context support 🙅‍♀️
  • --xattrs — Enable extended attributes support 🏷️
  • --no-xattrs — Disable extended attributes support 🙈
  • --xattrs-exclude=PATTERN — Specify the exclude pattern for xattr keys. PATTERN is a globbing pattern, for example --xattrs-exclude='user.*' to include only attributes from the user namespace 🧐
  • --xattrs-include=PATTERN — Specify the include pattern for xattr keys. PATTERN is a globbing pattern 🎯

✨ Device selection and switching ✨

Picking where your archive lives, and letting it travel 🧚✨

  • -f, --file=ARCHIVE — Use the archive file or device ARCHIVE. If you don't give this option, tar first checks the environment variable TAPE. If that's set, its value becomes the archive name. Otherwise, tar falls back on the compiled-in default. You can check that default with the --show-defaults option, or at the end of the tar --help output 🎀

An archive name with a colon in it points to a file or device on a remote machine. The part before the colon is the machine name or IP address, and the part after it is the file or device pathname, like this:

--file=remotehost:/dev/sr0

You can also put a username in front of the hostname, with an @ sign between them 💌

By default, the remote host gets accessed through the rsh(1) command 🔌 but nowadays ssh(1) is the go-to, so you can switch with this line:

--rsh-command=/usr/bin/ssh

The remote machine should have the rmt(8) command installed 🖥️ If its pathname doesn't match tar's default, just tell tar the right one with the --rmt-command option. Easy peasy 💅

  • --force-local — treats the archive file as local, even if its name has a colon in it 🫶
  • -F, --info-script=COMMAND, --new-volume-script=COMMAND — runs COMMAND at the end of each tape (this one implies -M) ✨ The command can take arguments too. When it kicks off, it inherits tar's environment plus these bestie variables:
    • TAR_VERSION — the GNU tar version number 🔢
    • TAR_ARCHIVE — the name of the archive tar is processing 📦
    • TAR_BLOCKING_FACTOR — the current blocking factor, aka how many 512-byte blocks fit in a record 🧱
    • TAR_VOLUME — the ordinal number of the volume tar is processing (only set when reading a multi-volume archive) 📚
    • TAR_FORMAT — the format of the archive being processed. One of: gnu, oldgnu, posix, ustar, v7 🎀
    • TAR_SUBCOMMAND — a short option (with a leading dash) describing what tar is doing right now 🏃‍♀️
    • TAR_FD — a file descriptor you can use to tell tar the new volume name 🦋
If the info script fails, tar exits. Otherwise, it moves on and starts writing the next volume. 😭
  • -L, --tape-length=N — changes tape after writing Nx1024 bytes 📼 If N has a size suffix (see the subsection Size suffixes below), that suffix sets the multiplicative factor instead of 1024.

This option implies -M.

  • -M, --multi-volume — create, list, or extract a multi-volume archive 🗂️
  • --rmt-command=COMMAND — uses COMMAND instead of rmt when accessing remote archives 🛰️ See the description of the -f option, above.
  • --rsh-command=COMMAND — uses COMMAND instead of rsh when accessing remote archives 🔐 See the description of the -f option, above.
  • --volno-file=FILE — when used together with --multi-volume, tar keeps track of which volume of a multi-volume archive it's on, storing that in FILE 🧾

✨ Device blocking ✨

  • -b, --blocking-factor=BLOCKS — sets the record size to BLOCKSx512 bytes 🧩
  • -B, --read-full-records — when listing or extracting, accepts incomplete input records after the end-of-file marker 🙈
  • -i, --ignore-zeros — ignores zeroed blocks in the archive 🧊 Normally, two consecutive 512-blocks filled with zeroes mean EOF, and tar stops reading once it hits them. This option tells it to keep reading, which is handy when reading archives made with the -A option.
  • --record-size=NUMBER — sets the record size 📏 NUMBER is the number of bytes per record, and it must be a multiple of 512. You can add a size suffix, like --record-size=10K for 10 Kilobytes. Check the subsection Size suffixes for the list of valid suffixes 💫

🦋 Archive format selection 🦋

  • -H, --format=FORMAT — creates an archive in the given format 🎞️ Valid formats are:
    • gnu — GNU tar 1.13.x format
    • oldgnu — GNU format as per tar <= 1.12
    • pax, posix — POSIX 1003.1-2001 (pax) format
    • ustar — POSIX 1003.1-1988 (ustar) format
    • v7 — old V7 tar format 🦕
  • --old-archive, --portability — same as --format=v7 🕰️
  • --pax-option=keyword[[:]=value][,keyword[[:]=value]]... — controls pax keywords when creating PAX archives (-H pax) 🌸 This is equivalent to the -o option of the pax(1) utility.
  • --posix — same as --format=posix 📮
  • -V, --label=TEXT — creates an archive with the volume name TEXT 🏷️ When listing or extracting, TEXT is used as a globbing pattern for the volume name 🔍

🗜️ Compression options 🗜️

  • -a, --auto-compress — uses the archive suffix to figure out which compression program to use 🪄
  • -I, --use-compress-program=COMMAND — filters data through COMMAND 🧃 It must accept the -d option (for decompression), and the argument can include command line options.
  • -j, --bzip2 — filters the archive through bzip2(1) 🍓
  • -J, --xz — filters the archive through xz(1) 💜
  • --lzip — filters the archive through lzip(1) 🌊
  • --lzma — filters the archive through lzma(1) 🌙
  • --lzop — filters the archive through lzop(1) 🫧
  • --no-auto-compress — don't use the archive suffix to pick the compression program 🙅‍♀️
  • -z, --gzip, --gunzip, --ungzip — filters the archive through gzip(1) 🍭
  • -Z, --compress, --uncompress — filters the archive through compress(1) 🫠
  • --zstd — filters the archive through zstd(1) ⚡

🌈 Local file selection 🌈

  • --add-file=FILE — adds FILE to the archive. Super useful if its name starts with a dash 🪽
  • --backup[=CONTROL] — makes a backup before removal 🛟 The CONTROL argument, if you give it, sets the backup policy. Its valid values are:
    • none, off — never make backups 🚫
    • t, numbered — make numbered backups 🔢
    • nil, existing — make numbered backups if numbered backups already exist, simple backups otherwise 🤔
    • never, simple — always make simple backups 🫶

If CONTROL isn't given, the value comes from the VERSION_CONTROL environment variable. If that isn't set either, existing is assumed.

  • -C, --directory=DIR — changes to DIR before doing anything else 📂 This option is order-sensitive, meaning it affects all the options that come after it.
  • --exclude=PATTERN — excludes files matching PATTERN, a glob(3)-style wildcard pattern 🚷
  • --exclude-backups — excludes backup and lock files 🔒
  • --exclude-caches — excludes the contents of directories containing the file CACHEDIR.TAG, except for the tag file itself 🗑️
  • --exclude-caches-all — excludes directories containing the file CACHEDIR.TAG, along with the file itself 💀
  • --exclude-caches-under — excludes everything under directories containing CACHEDIR.TAG 🙃
  • --exclude-ignore=FILE — before dumping a directory, checks whether it contains FILE. If it does, exclusion patterns get read from that file. The patterns only affect the directory itself 🪞
  • --exclude-ignore-recursive=FILE — same as --exclude-ignore, except the patterns from FILE affect both the directory and all of its subdirectories 🌳
  • --exclude-tag=FILE — excludes the contents of directories containing FILE, except for FILE itself 🏷️
  • --exclude-tag-all=FILE — excludes directories containing FILE 🚪
  • --exclude-tag-under=FILE — excludes everything under directories containing FILE 🧹
  • --exclude-vcs — excludes version control system directories 🙅‍♀️
  • --exclude-vcs-ignores — excludes files matching patterns read from VCS-specific ignore files. The supported files are: .cvsignore, .gitignore, .bzrignore, and .hgignore 🫧
  • -h, --dereference — follows symlinks, archiving and dumping the files they point to 🔗
  • --hard-dereference — follows hard links, archiving and dumping the files they refer to 🪢
  • -K, --starting-file=MEMBER — begins at the given member in the archive 🏁
  • --newer-mtime=DATE — works on files whose data changed after DATE 🕑 If DATE starts with / or ., it's taken to be a file name, and that file's mtime is used as the date.
  • --no-null — disables the effect of the previous --null option 🙅‍♀️
  • --no-recursion — stops tar from automatically descending into directories 🛑
  • --no-unquote — doesn't unquote input file or member names 🫥
  • --no-verbatim-files-from — treats each line read from a file list as if it were typed on the command line 📝 That means leading and trailing whitespace gets removed, and if the resulting string starts with a dash, it's treated as a tar command line option.

This is the default behavior. The --no-verbatim-files-from option exists so you can restore it after using --verbatim-files-from 🔁

This option is positional: it affects all --files-from options that come after it, until a --verbatim-files-from option or the end of the line, whichever shows up first 📍

It's implied by the --no-null option.

  • --null — tells subsequent -T options to read null-terminated names verbatim, which disables the special handling of names that start with a dash 🫧

See also --verbatim-files-from.

  • -N, --newer=DATE, --after-date=DATE — only stores files newer than DATE 🗓️ If DATE starts with / or ., it's taken to be a file name, and that file's mtime is used as the date.
  • --one-file-system — stays in the local file system when creating an archive 🏠
  • -P, --absolute-names — doesn't strip leading slashes from file names when creating archives ⚠️
  • --recursion — recurses into directories (this is the default) 🌀
  • --suffix=STRING — makes a backup before removal, overriding the usual suffix 🩹 The default suffix is ~, unless you override it with the SIMPLE_BACKUP_SUFFIX environment variable.
  • -T, --files-from=FILE — gets the names to extract or create from FILE 📜

Unless specified otherwise, FILE must contain a list of names separated by ASCII LF (so one name per line). The names read are handled the same way as command line arguments: they undergo quote removal and word splitting, and any string that starts with a - is handled as a tar command line option.

If that behavior is undesirable, you can turn it off with the --verbatim-files-from option 🙅‍♀️

The --null option tells tar that the names in FILE are separated by the ASCII NUL character instead of LF. It's useful if the list is generated by the find(1) -print0 predicate 🧚

  • --unquote — unquotes file or member names (this is the default) 🎀
  • --verbatim-files-from — treats each line from a file list as a file name, even if it starts with a dash 💅 File lists are supplied with the --files-from (-T) option. By default, names in file lists are handled as if they were typed on the command line, so any name starting with a dash is treated as a tar option. The --verbatim-files-from option turns that behavior off ✨

This bit of OPTIONS was already covered, so I'll pick up right where the verbatim files stuff leaves off 🎀

Okay so this option changes how every --files-from option that comes after it on the command line gets handled 💅. Its effect gets undone by --no-verbatim-files-from.

The --null option implies this one, so you don't need to add it yourself when you're already using --null ✨

Also check out --add-file for the related vibes 🦋

  • -X, --exclude-from=FILE — Skip any files that match the patterns listed inside FILE 🙈

🌸 File name transformations

  • --strip-components=NUMBER — Chop off NUMBER leading components from file names when you extract 🔪
  • --transform=EXPRESSION, --xform=EXPRESSION — Run a sed replace EXPRESSION to reshape file names into whatever look you want 💖

🧚 File name matching options

These options affect both exclude and include patterns, so they're kind of a whole team 🫶

  • --anchored — Patterns only match from the very start of a file name 📌
  • --ignore-case — Ignore case, no judgement 🌈
  • --no-anchored — Patterns can match after any /. This is the default for exclusion 🍓
  • --no-ignore-case — Matching is case sensitive. This is the default 💅
  • --no-wildcards — Verbatim string matching, no wildcard drama 🦋
  • --no-wildcards-match-slash — Wildcards are not allowed to match / 🚫
  • --wildcards — Use wildcards. This is the default for exclusion ✨
  • --wildcards-match-slash — Wildcards are allowed to match /. This is the default for exclusion 🌸

📣 Informative output

  • --checkpoint[=N] — Show a progress message every Nth record. The default is 10 📍
  • --checkpoint-action=ACTION — Run ACTION on each checkpoint 🎬
  • --clamp-mtime — Only set the time when the file is more recent than whatever you gave with --mtime 🕰️
  • --full-time — Print file times at their full resolution, no shortcuts 🕒
  • --index-file=FILE — Send the verbose output over to FILE 📂
  • -l, --check-links — Print a message if not all links got dumped 🔗
  • --no-quote-chars=STRING — Turn off quoting for the characters in STRING 🙅‍♀️
  • --quote-chars=STRING — Also quote the characters in STRING 💬
  • --quoting-style=STYLE — Set the quoting style for file and member names. Valid values for STYLE are literal, shell, shell-always, c, c-maybe, escape, locale, clocale 🎨
  • -R, --block-number — Show the block number within the archive alongside each message 🔢
  • --show-omitted-dirs — When listing or extracting, list every directory that doesn't match your search criteria 📁
  • --show-transformed-names, --show-stored-names — Show file or archive names after they've been transformed by the --strip and --transform options 👀
  • --totals[=SIGNAL] — Print the total bytes after processing the archive. If SIGNAL is given, print the total bytes when that signal gets delivered. Allowed signals are: SIGHUP, SIGQUIT, SIGINT, SIGUSR1, and SIGUSR2. The SIG prefix can be omitted 📊
  • --utc — Print file modification times in UTC 🌍
  • -v, --verbose — Verbosely list the files processed. Each time you use this option on the command line, the verbosity level goes up by one. The maximum verbosity level is 3. For a deep dive into how the different levels change tar's output, check out GNU Tar Manual, subsection 2.5.2 "The '--verbose' Option" 📖
  • --warning=KEYWORD — Enable or disable the warning messages identified by KEYWORD. The messages get suppressed if KEYWORD is prefixed with no-, and enabled otherwise ⚠️
Multiple --warning options accumulate, so stack them as much as you want 💜

Here's the keyword breakdown, bestie 🫶

Keywords controlling general tar operation:

  • all — Enable all warning messages. This is the default ✅
  • none — Disable all warning messages 🙅
  • filename-with-nuls — "%s: file name read contains nul character"
  • alone-zero-block — "A lone zero block at %s"

Keywords applicable for tar --create:

  • cachedir — "%s: contains a cache directory tag %s; %s"
  • file-shrank — "%s: File shrank by %s bytes; padding with zeros"
  • xdev — "%s: file is on a different filesystem; not dumped"
  • file-ignored — "%s: Unknown file type; file ignored", "%s: socket ignored", "%s: door ignored"
  • file-unchanged — "%s: file is unchanged; not dumped"
  • ignore-archive — "%s: archive cannot contain itself; not dumped"
  • file-removed — "%s: File removed before we read it"
  • file-changed — "%s: file changed as we read it"
  • failed-read — Suppresses warnings about unreadable files or directories. This keyword only applies if it's used together with the --ignore-failed-read option 🙈

Keywords applicable for tar --extract:

  • existing-file — "%s: skipping existing file"
  • timestamp — "%s: implausibly old time stamp %s", "%s: time stamp %s is %s s in the future"
  • contiguous-cast — "Extracting contiguous files as regular files"
  • symlink-cast — "Attempting extraction of symbolic links as hard links"
  • unknown-cast — "%s: Unknown file type '%c', extracted as normal file"
  • ignore-newer — "Current %s is newer or same age"
  • unknown-keyword — "Ignoring unknown extended header keyword '%s'"
  • decompress-program — Controls the verbose description of failures that happen when tar tries to run alternative decompressor programs. This warning is disabled by default (unless --verbose is used). A common example of what you can get with this warning looks like:
$ tar --warning=decompress-program -x -f archive.Z
tar (child): cannot run compress: No such file or directory
tar (child): trying gzip

This means tar first tried to decompress archive.Z using compress, and when that failed, it switched to gzip 🔄

  • record-size — "Record size = %lu blocks"

Keywords controlling incremental extraction:

  • rename-directory — "%s: Directory has been renamed from %s", "%s: Directory has been renamed"
  • new-directory — "%s: Directory is new"
  • xdev — "%s: directory is on a different device: not purging"
  • bad-dumpdir — "Malformed dumpdir: 'X' never used"
  • -w, --interactive, --confirmation — Ask for confirmation before every single action 🤨

🎀 Compatibility options

  • -o — When creating, this is the same as --old-archive. When extracting, it's the same as --no-same-owner 🧸

📏 Size suffixes

Suffix    Units                   Byte Equivalent
b         Blocks                  SIZE x 512
B         Kilobytes               SIZE x 1024
c         Bytes                   SIZE
G         Gigabytes               SIZE x 1024^3
K         Kilobytes               SIZE x 1024
k         Kilobytes               SIZE x 1024
M         Megabytes               SIZE x 1024^2
P         Petabytes               SIZE x 1024^5
T         Terabytes               SIZE x 1024^4
w         Words                   SIZE x 2

👑 RETURN VALUE 👑

Tar's exit code tells you whether it managed to pull off the requested operation, and if it didn't, what kind of error happened 💀

  • 0 — Successful termination. Slay ✨
  • 1 — Some files differ. If tar was invoked with the --compare (--diff, -d) command line option, this means some files in the archive differ from their disk counterparts. If tar was given one of the --create, --append or --update options, this exit code means some files were changed while being archived, so the resulting archive does not contain the exact copy of the file set 😬
  • 2 — Fatal error. Some fatal, unrecoverable error happened 😭

If a subprocess that tar invoked exited with a nonzero exit code, tar itself exits with that code too. This can happen, for example, if a compression option (e.g. -z) was used and the external compressor program failed. Another example is rmt failure during backup to a remote device 🫠

🦋 SEE ALSO 🦋

bzip2(1), compress(1), gzip(1), lzma(1), lzop(1), rmt(8), symlink(7), xz(1), zstd(1).

Want the full tar manual? Run info tar or use emacs(1) info mode to read it 📚

Online copies of GNU tar documentation in various formats can be found at:

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

🐛 BUG REPORTS 🐛

Report bugs to <bug-tar@gnu.org> 🫶

Copyright © 2023 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

And that's a wrap on tar, bestie 🎀✨ Thanks for sticking with me through all four parts! The TAR(1) page, dated July 11, 2022, is officially iconic 👑💖

📦 where this page comes from