Find Matching Files Inside a tar Archive with ptargrep

ptargrep searches inside a tar archive for a pattern, without unpacking the whole thing first. A backup lands in your lap and you need to know if it contains a particular config file, a stray password, or an old SSH host key, before you commit to extracting anything. This guide gets you searching, then extracting safely, with the ptargrep supplied by Perl 5.38.2 on the system used here. Allow about ten minutes, plus time to inspect the archive before extracting anything.

Before you start

• You need: a Linux shell, the perl package, and a tar archive you are allowed to inspect.
• No elevated privileges: nothing in this guide needs sudo.
• Pick a scratch directory: use a working directory where creating files is harmless.

Set the archive path to your own file. Quoting the variable matters when a path contains spaces:

archive='/path/to/config-backup.tar'
test -r "$archive" && command -v ptargrep

Expected output is the path to ptargrep, such as /usr/bin/ptargrep. If the first command fails, correct the path or permissions before continuing.

1. List matches without extracting anything

Start with --list-only. It prints the pathname of every archive member whose contents contain a matching line, and creates no files. This is the safest first pass:

ptargrep --list-only 'Host' "$archive"

A configuration archive might produce output like this:

/etc/sshd_config

• It is a Perl regular expression, not a literal search. Host here matches only that capitalisation.
• A file counts as a match if one line matches. The command prints the filename, not the matching line itself.

2. Make the search case-insensitive

Add --ignore-case, or its short form -i, when capitalisation should not matter:

ptargrep --list-only --ignore-case 'host' "$archive"

This finds both Host and host. Quote the pattern so the shell leaves its punctuation alone when you reach for regular-expression features:

ptargrep --list-only -i '^(host|hostname)[[:space:]]' "$archive"

3. Extract matches into a disposable directory

Without --list-only, the default action is to extract every matching file. Change into a new directory before doing that:

mkdir -p ./ptargrep-review
cd ./ptargrep-review
ptargrep 'Host' "$archive"
find . -type f -print

With an archive member named etc/sshd_config, the final command should show:

./etc/sshd_config

Directory paths are kept by default, so similarly named files stay apart and the extracted copy is easy to relate back to the archive. Extraction happens in the directory you run ptargrep from, so check pwd first if the destination matters.

4. Flatten paths only after checking for collisions

The --basename option, or -b, discards archive directories during extraction:

mkdir -p ./ptargrep-flat
cd ./ptargrep-flat
ptargrep --basename 'Host' "$archive"
find . -maxdepth 1 -type f -print

A member such as etc/sshd_config becomes ./sshd_config. Handy for a small, known archive, but it changes the safety boundary: if two matching members share a basename, the later extraction overwrites the earlier one.

rm -rf -- ./ptargrep-flat

That removal is irreversible for files created there, so confirm the path with pwd and find ./ptargrep-flat -maxdepth 2 -type f before using it. If the directory holds anything else, move what you need out first and remove only the generated files.

5. Search more than one archive

Pass multiple tar filenames after the pattern. Each archive is processed in turn:

ptargrep --list-only -i 'password|token' \
  '/path/to/backup-2026-01.tar' \
  '/path/to/backup-2026-02.tar'

This reports matching archive paths to standard output, but without an archive label attached. Search one archive at a time when you need an unambiguous audit record, or record the command and its input filenames alongside the output.

Common traps

• Unexpected extraction. Omitting --list-only extracts matches by default. Make listing your first command, every time.
• Missing lowercase matches. Matching is case-sensitive unless --ignore-case is present.
• Wrong destination. Extraction uses the current directory, not the directory containing the archive. Verify it with pwd.
• Overwritten basenames. --basename can replace an earlier match with the same filename. Keep archive paths unless flattening is necessary.
• Regex errors. Patterns use Perl regular-expression syntax. Quote shell metacharacters and test a small expression with --list-only first.
• Confusing output. Matching prints filenames, not matching lines. Extract a selected file, or run a separate tool on the extracted copy, when you need the lines themselves.