borg/docs/man/borg-find.1

.\" Man page generated from reStructuredText
.\" by the Docutils 0.22.4 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-find" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-find \- Find files across archives.
.SH SYNOPSIS
.sp
borg [common options] find [options] [PATH...]
.SH DESCRIPTION
.sp
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 \fBborg list\fP, 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.
.sp
This makes it easy to answer questions like \(dqwhich archives contain this file?\(dq
or \(dqwhere did that file end up?\(dq:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ borg find home/user/file.txt          # in which archives is this file?
$ borg find \(aqsh:**/*.jpg\(aq \-\-last 3      # all jpg files in the last 3 archives
.EE
.UNINDENT
.UNINDENT
.sp
The given PATHs match like in \fBborg list\fP or \fBborg extract\fP: a plain path
matches the item with that path as well as everything below it, and the pattern
styles (\fBfm:\fP, \fBsh:\fP, \fBre:\fP, \fBpp:\fP, \fBpf:\fP) are supported as well.
For more help on include/exclude patterns, see the output of \fIborg_patterns\fP\&.
.sp
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.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B PATH
paths to find; patterns are supported
.UNINDENT
.SS options
.INDENT 0.0
.TP
.BI \-\-format \ FORMAT
specify format for file listing (default: \(dq{archiveid:.8} {archivename} {mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}\(dq)
.TP
.B  \-\-json\-lines
Format output as JSON Lines. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text.
.UNINDENT
.SS Archive filters
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
.TP
.BI \-\-first \ N
consider the first N archives after other filters are applied
.TP
.BI \-\-last \ N
consider the last N archives after other filters are applied
.TP
.BI \-\-oldest \ TIMESPAN
consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SS Include/Exclude options
.INDENT 0.0
.TP
.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
exclude paths matching PATTERN
.TP
.BI \-\-exclude\-from \ EXCLUDEFILE
read exclude patterns from EXCLUDEFILE, one per line
.TP
.BI \-\-pattern \ PATTERN
include/exclude paths matching PATTERN
.TP
.BI \-\-patterns\-from \ PATTERNFILE
read include/exclude patterns from PATTERNFILE, one per line
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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 \(aqsh:**/*.jpg\(aq \-\-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 \(aq{archiveid:.8} {archivename} {path}{NL}\(aq home/user/file.txt
41a2ed21 docs home/user/file.txt
20e70e3a docs home/user/file.txt
.EE
.UNINDENT
.UNINDENT
.SH NOTES
.SS The FORMAT specifier syntax
.sp
The \fB\-\-format\fP option uses Python\(aqs format string syntax \%<https://\:docs\:.python\:.org/\:3\:.11/\:library/\:string\:.html#\:formatstrings>\&.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# only print the archive and the path, nothing else
$ borg find \-\-format \(aq{archiveid:.8} {archivename} {path}{NL}\(aq \(aqsh:**/*.jpg\(aq
20e70e3a photos photos/paris/eiffel.jpg
\&...
.EE
.UNINDENT
.UNINDENT
.sp
{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).
.sp
The following keys are always available:
.INDENT 0.0
.IP \(bu 2
NEWLINE: OS dependent line separator
.IP \(bu 2
NL: alias of NEWLINE
.IP \(bu 2
NUL: NUL character for creating print0 / xargs \-0 like output
.IP \(bu 2
SPACE: space character
.IP \(bu 2
TAB: tab character
.IP \(bu 2
CR: carriage return character
.IP \(bu 2
LF: line feed character
.UNINDENT
.sp
Keys available only when finding files in an archive:
.INDENT 0.0
.IP \(bu 2
type: file type (file, dir, symlink, ...)
.IP \(bu 2
mode: file mode (as in stat)
.IP \(bu 2
uid: user id of file owner
.IP \(bu 2
gid: group id of file owner
.IP \(bu 2
user: user name of file owner
.IP \(bu 2
group: group name of file owner
.IP \(bu 2
path: file path
.IP \(bu 2
target: link target for symlinks
.IP \(bu 2
hlid: hard link identity (same if hardlinking same fs object)
.IP \(bu 2
inode: inode number
.IP \(bu 2
flags: file flags
.IP \(bu 2
size: file size
.IP \(bu 2
num_chunks: number of chunks in this file
.IP \(bu 2
mtime: file modification time
.IP \(bu 2
ctime: file change time
.IP \(bu 2
atime: file access time
.IP \(bu 2
isomtime: file modification time (ISO 8601 format)
.IP \(bu 2
isoctime: file change time (ISO 8601 format)
.IP \(bu 2
isoatime: file access time (ISO 8601 format)
.IP \(bu 2
fingerprint: Fingerprint of the file content (may have false negatives), format: H(conditions)\-H(chunk_ids)
.IP \(bu 2
blake2b
.IP \(bu 2
blake2s
.IP \(bu 2
blake3
.IP \(bu 2
md5
.IP \(bu 2
sha1
.IP \(bu 2
sha224
.IP \(bu 2
sha256
.IP \(bu 2
sha384
.IP \(bu 2
sha3_224
.IP \(bu 2
sha3_256
.IP \(bu 2
sha3_384
.IP \(bu 2
sha3_512
.IP \(bu 2
sha512
.IP \(bu 2
archiveid: internal ID of the archive
.IP \(bu 2
archivename: name of the archive
.IP \(bu 2
extra: prepends {target} with \(dq \-> \(dq for soft links and \(dq link to \(dq for hard links
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH Author
The Borg Collective
.\" End of generated man page.