tar
Packing directories into an archive and unpacking — .tar, .tar.gz, .tar.xz, listing and selective extraction
tar glues files and directories into a single archive, preserving the structure, permissions, owners and modification times. tar itself doesn't compress — compression is added with an option: z (gzip, .tar.gz/.tgz), J (xz, .tar.xz).
Syntax
tar -c [options] -f archive.tar files… # create
tar -t [options] -f archive.tar [files…] # list contents
tar -x [options] -f archive.tar [files…] # extract
Exactly one mode is chosen. Options can be bundled: tar -czf = tar -c -z -f. The old form without a dash (tar czf) works too.
Modes
| Mode | What it does |
|---|---|
-c | create a new archive |
-t | list the files in the archive |
-x | extract |
-r | append files to the end of the archive (uncompressed .tar only) |
-u | append files that are newer than their copies in the archive (.tar only) |
-A | append the contents of another .tar to the archive |
--delete | delete files from the archive (.tar only) |
-d | compare the archive with the files on disk: what differs |
Archive and compression
| Option | What it does |
|---|---|
-f archive | archive file name; -f - — stdout/stdin |
-z | gzip (.tar.gz, .tgz) |
-J | xz (.tar.xz) — stronger but slower |
-j / --zstd | bzip2 / zstd — need the programs of the same name on the system |
-a | pick compression from the archive name's extension (when creating) |
-I 'command' | compress with any program: -I 'gzip -9', -I 'xz -T0' |
When reading (-t, -x) you don't have to specify the compression: tar -xf archive.tar.xz detects it itself.
Which files to take
| Option | What it does |
|---|---|
-C directory | change to the directory before working: where to take files from or where to extract |
--exclude='pattern' | don't include matching files and directories at any level (put it before the file list) |
--anchored | match the following --excludes against the start of the path in the archive |
-X file | exclusion patterns from a file, one per line |
--exclude-vcs | don't include .git, .svn and the like |
-T list | take file names from a file (-T - — from stdin); with --null — separated by a null byte |
--newer-mtime='2024-01-01' | only files modified after the date (directories are always included) |
-g snapshot | incremental archive: next time, with the same snapshot, only changes are included |
-h | put the files that links point to into the archive, not the links themselves |
--one-file-system | don't cross into other file systems |
--remove-files | delete the source files after packing |
-P | keep absolute paths (leading /) — usually not needed |
How to extract
| Option | What it does |
|---|---|
--strip-components=N | cut off the first N levels of the path |
--transform='s,^app,app-1.0,' | rename paths with a sed-like expression (works when creating too) |
--wildcards | allow * patterns in names with -t/-x |
-O | extract to stdout instead of disk |
-k | don't overwrite existing files (an error for each) |
--skip-old-files | silently skip existing files |
--keep-newer-files | don't overwrite files that are newer on disk |
-m | don't restore the modification time — set the current one |
-p | restore permissions exactly, ignoring umask (on by default for root) |
--no-same-owner | don't restore owners — everything will belong to you |
Owners in the archive and output
| Option | What it does |
|---|---|
-v | print file names; -vv or -tv — in detail |
--owner=root --group=root | record a different owner in the archive |
--numeric-owner | write and read owners as numbers only |
--totals | print how many bytes were written at the end |
-W | verify the archive after creating it |
A tar -tvf line: permissions, owner/group, size in bytes, modification date and time, path. For links — name -> target.
-rw-r--r-- alice/devs 2048 2024-05-01 12:00 app/config.yml
Examples
# pack a directory with gzip compression; paths in the archive start with app/
tar -czf app.tar.gz -C /srv app
# an archive with the date in its name
tar -czf "backup-$(date +%F).tar.gz" -C /srv app
# leave out the junk: exclusions go before the file list
tar -czf app.tar.gz --exclude=node_modules --exclude='*.log' --exclude-vcs -C /srv app
# view the contents without extracting (tar detects the compression itself)
tar -tf app.tar.gz
tar -tvf app.tar.gz
# extract into a given directory (it must exist)
mkdir -p /tmp/restore && tar -xzf app.tar.gz -C /tmp/restore
# extract without the archive's top-level directory
tar -xzf app.tar.gz -C /srv/app --strip-components=1
# extract one directory or files by pattern
tar -xzf app.tar.gz app/logs
tar -xzf app.tar.gz --wildcards '*.conf'
# print one file to the screen
tar -xOf app.tar.gz app/config.yml
# compare the archive with the files on disk
tar -df app.tar.gz -C /srv
# pack a list of files found by find
find /etc -name '*.conf' -mtime -7 -print0 | tar -czf recent-conf.tgz --null -T -
# a full backup and then only the changes
tar -czf full.tgz -g /var/backups/app.snar -C /srv app
tar -czf incr-1.tgz -g /var/backups/app.snar -C /srv app
# strong xz compression on all cores
tar -I 'xz -T0' -cf app.tar.xz -C /srv app
# archive through a pipe — e.g. straight to another machine
tar -czf - -C /srv app | ssh backup@example.com 'cat > app.tar.gz'
Pitfalls
-fmust come last in a bundle. The archive name follows it:tar -cfz app.tar appcreates an archive namedzand tries to packapp.taras a file.- Absolute paths.
tar -czf a.tgz /srv/appstrips the leading/and storessrv/app/…— on extraction you get./srv/app. Use-C /srv appto get a short path in the archive. --excludeafter the file list has no effect. GNU tar warns ("has no effect") and packs everything; the archive is still created, but the exit code is non-zero.--excludeisn't anchored to the start of the path.--exclude=cacheexcludes bothapp/cacheandapp/lib/cache— any path component with that name. To exclude onlyapp/cache, add--anchoredbefore--exclude=app/cache.- Patterns when extracting.
tar -xf a.tar '*.log'without--wildcardslooks for a file literally named*.logand reports "Not found in archive". - Extraction silently overwrites files. Look at the list first (
-t), extract into an empty directory, or add-k/--skip-old-files. - A compressed archive can't be modified.
-r,-u,-A,--deletework only on an uncompressed.tar: "Cannot update compressed archives". - An empty file list gives the error "Cowardly refusing to create an empty archive". This happens when
findfor-Tfound nothing. - Owners. When extracting, root restores the owners from the archive. A regular user gets all files owned by themselves.
- bzip2 and zstd may be missing.
tar -jand--zstdcall external programs and fail with "not found" without them.