Scroll to navigation

borg-find(1) borg backup tool borg-find(1)

Name

borg-find - Find files across archives.

SYNOPSIS

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

DESCRIPTION

This command finds files matching the given paths or patterns in the archives selected by the usual archive filter options (all archives, if no filters are given). It iterates over the matching archives from newest to oldest, over all items of each archive, and outputs one line per match, like borg list, but prefixed with a short archive ID and the archive name. As the archives of a series all share the same name, only the archive ID uniquely identifies the archive.

This makes it easy to answer questions like "which archives contain this file?" or "where did that file end up?":

$ 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 given PATHs 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 as well. For more help on include/exclude patterns, see 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.

OPTIONS

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

arguments

paths to find; patterns are supported

options

specify format for file listing (default: "{archiveid:.8} {archivename} {mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}")
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

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

Include/Exclude options

exclude paths matching PATTERN
read exclude patterns from EXCLUDEFILE, one per line
include/exclude paths matching PATTERN
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

2026-09-26