Create, Inspect and Extract Tar Archives with ptar

ptar is the tar-like archiver built into Perl's Archive::Tar module. This guide builds a small, repeatable workflow around it: make an archive, check its contents, then extract into a directory you actually chose. The examples use ptar from Perl 5.38.2, provided by the Debian package perl on this machine.

Allow about ten minutes. You need a shell, a writable working directory, and files you intend to archive. The examples create files under /tmp; they do not need elevated privileges. Do not run extraction as root unless the destination and archive have been checked first.

1. Check the installed command

Confirm which program will run and read its local help:

$ command -v ptar
/usr/bin/ptar
$ dpkg-query -W -f='${Package} ${Version}\n' perl
perl 5.38.2-3.2ubuntu0.6
$ ptar -h

The command is a tar-like Perl program backed by Archive::Tar. Its operation is selected by exactly one of -c (create), -t (list), or -x (extract). The installed help is the authority if a later package version differs.

Checkpoint: if command -v finds a different executable, stop and check that you are testing the intended package.

2. Create a small archive

Make a disposable test tree, then create an archive with -c. The -f option names the archive. Paths are recorded relative to the current directory, so run the command from the parent of the files you want to store.

$ workdir=$(mktemp -d /tmp/ptar-example.XXXXXX)
$ cd "$workdir"
$ printf '%s\n' 'alpha' > alpha.txt
$ mkdir input
$ printf '%s\n' 'beta' > input/beta.txt
$ ptar -c -v -f bundle.tar alpha.txt input/beta.txt
./alpha.txt
input/beta.txt

-v prints each path as it is added. The leading ./ on a file in the current directory is normal output from this implementation. Creation replaces an existing archive with the same name, so do not point this example at a valuable file.

Checkpoint: confirm that the archive exists before doing anything with it:

$ file bundle.tar
bundle.tar: POSIX tar archive

3. List before extracting

Use -t to inspect names without writing files:

$ ptar -t -f bundle.tar
./alpha.txt
input/beta.txt

Listing is the safest first check for an archive from another person or system. Look for unexpected absolute-looking paths, parent-directory components such as ../, or files that would overwrite something important. This check does not validate every file's contents and does not extract anything.

For a missing archive, ptar exits non-zero and reports the open failure. Treat that as a path or permissions problem, not as an empty archive:

$ ptar -t -f absent.tar
Could not open 'absent.tar' for reading: No such file or directory ...

4. Extract into an empty destination

Create a destination specifically for the archive, list the archive once more, then extract with -x. Change directory yourself before extraction:

In ptar, -C means CPAN mode, which drops permission bits represented by octal 022; it is not an extraction-directory option. Do not copy the option from another tar implementation expecting it to select extracted.

$ cd extracted
$ ptar -x -v -f ../bundle.tar
./alpha.txt
input/beta.txt
$ find . -type f -print
./alpha.txt
./input/beta.txt
$ cd ..

Extraction can create or overwrite paths in the current directory. That is why the example uses a new directory and why the archive listing comes first. If you extracted into the wrong disposable directory, remove that directory only after checking its exact path, then recreate it and extract again. There is no ptar undo operation for files it has overwritten.

5. Use gzip compression

Add -z when creating and listing a zlib-compressed archive:

$ ptar -c -z -f bundle.tar.gz alpha.txt input/beta.txt
$ file bundle.tar.gz
bundle.tar.gz: gzip compressed data, original size modulo 2^32 3072
$ ptar -t -z -f bundle.tar.gz
./alpha.txt
input/beta.txt

Pass -z for extraction too. It is not inferred reliably from the filename alone:

$ mkdir compressed-extracted
$ cd compressed-extracted
$ ptar -x -z -f ../bundle.tar.gz
$ test -f alpha.txt && test -f input/beta.txt
$ printf '%s\n' 'compressed extraction verified'
compressed extraction verified
$ cd ..

The manpage describes compression as not always available. If your installed Perl lacks the required zlib support, use an uncompressed archive or install the package support through your normal system administration process.

6. Stream an archive or read a file list

Use -f - for archive standard output or input. The position matters: a bare trailing - in the create file list is treated as a file name, not as the archive stream.

$ ptar -c -f - alpha.txt input/beta.txt > stream.tar
$ ptar -t -f - < stream.tar
./alpha.txt
input/beta.txt
$ mkdir streamed
$ cd streamed
$ ptar -x -f - < ../stream.tar
$ cd ..

For many input paths, put one name per line in a file and pass it with -T:

$ printf '%s\n' alpha.txt input/beta.txt > names.txt
$ ptar -c -T names.txt -f selected.tar
$ ptar -t -f selected.tar
./alpha.txt
input/beta.txt

Review the list before creating the archive. A file-list entry is a path supplied to ptar, not a shell command, so shell expansion and quoting do not happen inside names.txt.

Done means