borg-find(1)

📦 version 2.0.0b25, in ubuntu stonking

💖 borg-find(1) — find files across archives 💖

okay bestie, this is the manual page for borg-find, one of the commands in the borg backup tool. Sit down, get comfy, we're gonna find literally every file. 🦋

✨ NAME ✨

borg-find — find files across archives, fr fr.

🌸 SYNOPSIS 🌸

borg [common options] find [options] [PATH...]

💅 DESCRIPTION 💅

So what this command does is it finds files matching the paths or patterns you give it, inside the archives that got picked by the usual archive filter options (and if you gave no filters at all, bestie, it's all archives, no cap). It iterates over the matching archives from newest to oldest, goes over all items of each archive, and outputs one line per match — kinda like borg list, except each line is prefixed with a short archive ID and the archive name. And here's the tea: the archives of a series all share the same name, so only the archive ID uniquely identifies the archive. 👑

This makes it super easy to answer questions like "which archives contain this file?" or "where did that file end up?" — the way that this just works is iconic:

$ borg find home/user/file.txt          # in which archives is this file?
$ borg find 'sh:**/*.jpg' --last 3      # all jpg files in the last 3 archives

The PATHs you pass match like in borg list or borg extract: a plain path matches the item with that path as well as everything below it, and the pattern styles (fm:, sh:, re:, pp:, pf:) are supported too. For more help on include/exclude patterns, go look at the output of borg_patterns.

Note: there is no extra index for the file paths, so this command reads the metadata of all selected archives, which may take a while for many/big archives. 😭 Not me waiting on a huge backup... but that's the trade-off, bestie.

🎀 OPTIONS 🎀

See borg-common(1) for common options of Borg commands.

arguments

  • PATH — paths to find; patterns are supported 💫

options

  • --format FORMAT — specify format for file listing (default: "{archiveid:.8} {archivename} {mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}")
  • --json-lines — Format output as JSON Lines. The form of --format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text.

Archive filters

  • -a PATTERN, --match-archives PATTERN — only consider archives matching all patterns. See borg help match-archives.
  • --sort-by KEYS — Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
  • --first N — consider the first N archives after other filters are applied
  • --last N — consider the last N archives after other filters are applied
  • --oldest TIMESPAN — consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
  • --newest TIMESPAN — consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g., 7d or 12m.
  • --older TIMESPAN — consider archives older than (now - TIMESPAN), e.g., 7d or 12m.
  • --newer TIMESPAN — consider archives newer than (now - TIMESPAN), e.g., 7d or 12m.

Include/Exclude options

  • -e PATTERN, --exclude PATTERN — exclude paths matching PATTERN
  • --exclude-from EXCLUDEFILE — read exclude patterns from EXCLUDEFILE, one per line
  • --pattern PATTERN — include/exclude paths matching PATTERN
  • --patterns-from PATTERNFILE — read include/exclude patterns from PATTERNFILE, one per line

🔥 EXAMPLES 🔥

# In which archives is this file? Searched / printed from newest to oldest archive.
$ borg find home/user/file.txt
41a2ed21 docs -rw-rw-r-- user   user       1522 Sun, 2022-02-06 21:02:18 +0100 home/user/file.txt
20e70e3a docs -rw-rw-r-- user   user       1440 Sun, 2022-01-30 20:47:32 +0100 home/user/file.txt

# Find all jpg files in the last 3 archives.
$ borg find 'sh:**/*.jpg' --last 3
39c8956e photos -rw-rw-r-- user   user     919337 Sat, 2022-01-01 14:20:21 +0100 photos/paris/eiffel.jpg
39c8956e photos -rw-rw-r-- user   user    1023881 Sun, 2022-02-06 09:12:44 +0100 photos/rome/colosseum.jpg
04061a53 photos -rw-rw-r-- user   user     919337 Sat, 2022-01-01 14:20:21 +0100 photos/paris/eiffel.jpg

# Only print the archive and the path, nothing else.
$ borg find --format '{archiveid:.8} {archivename} {path}{NL}' home/user/file.txt
41a2ed21 docs home/user/file.txt
20e70e3a docs home/user/file.txt

🧚 NOTES 🧚

The FORMAT specifier syntax

The --format option uses Python's format string syntax https://docs.python.org/3.11/library/string.html#formatstrings.

Examples:

# only print the archive and the path, nothing else
$ borg find --format '{archiveid:.8} {archivename} {path}{NL}' 'sh:**/*.jpg'
20e70e3a photos photos/paris/eiffel.jpg
...

{archiveid:.8} prints a short archive ID (use {archiveid} for the full ID), {archivename} the archive name (the archives of a series all share the name).

The following keys are always available:

  • NEWLINE: OS dependent line separator
  • NL: alias of NEWLINE
  • NUL: NUL character for creating print0 / xargs -0 like output
  • SPACE: space character
  • TAB: tab character
  • CR: carriage return character
  • LF: line feed character

Keys available only when finding files in an archive:

  • type: file type (file, dir, symlink, ...)
  • mode: file mode (as in stat)
  • uid: user id of file owner
  • gid: group id of file owner
  • user: user name of file owner
  • group: group name of file owner
  • path: file path
  • target: link target for symlinks
  • hlid: hard link identity (same if hardlinking same fs object)
  • inode: inode number
  • flags: file flags
  • size: file size
  • num_chunks: number of chunks in this file
  • mtime: file modification time
  • ctime: file change time
  • atime: file access time
  • isomtime: file modification time (ISO 8601 format)
  • isoctime: file change time (ISO 8601 format)
  • isoatime: file access time (ISO 8601 format)
  • fingerprint: Fingerprint of the file content (may have false negatives), format: H(conditions)-H(chunk_ids)
  • blake2b
  • blake2s
  • blake3
  • md5
  • sha1
  • sha224
  • sha256
  • sha384
  • sha3_224
  • sha3_256
  • sha3_384
  • sha3_512
  • sha512
  • archiveid: internal ID of the archive
  • archivename: name of the archive
  • extra: prepends {target} with " -> " for soft links and " link to " for hard links

🌈 SEE ALSO 🌈

borg-common(1)

👑 AUTHOR 👑

The Borg Collective

and that's the whole page, bestie!! 🫶 this version of the borg-find(1) page is dated 2026-10-07, and yes it's still literally borg-find(1). go forth and find ur files. periodt. 💜✨

📦 where this page comes from