borg/docs/man/borg-list.1

.\" Man page generated from reStructuredText.
.
.
.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-LIST" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-list \- List archive or repository contents
.SH SYNOPSIS
.sp
borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
.SH DESCRIPTION
.sp
This command lists the contents of a repository or an archive.
.sp
For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY_OR_ARCHIVE
repository or archive to list contents of
.TP
.B PATH
paths to list; patterns are supported
.UNINDENT
.SS options
.INDENT 0.0
.TP
.B  \-\-consider\-checkpoints
Show checkpoint archives in the repository contents list (default: hidden).
.TP
.B  \-\-short
only print file/directory names, nothing else
.TP
.BI \-\-format \ FORMAT
specify format for file or archive listing (default for files: \(dq{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}\(dq; for archives: \(dq{archive:<36} {time} [{id}]{NL}\(dq)
.TP
.B  \-\-json
Only valid for listing repository contents. Format output as JSON. 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. A \(dqbarchive\(dq key is therefore not available.
.TP
.B  \-\-json\-lines
Only valid for listing archive contents. 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. A \(dqbpath\(dq key is therefore not available.
.UNINDENT
.SS Archive filters
.INDENT 0.0
.TP
.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
only consider archive names starting with this prefix. (deprecated)
.TP
.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see \(dqborg help patterns\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
.TP
.BI \-\-first \ N
consider first N archives after other filters were applied
.TP
.BI \-\-last \ N
consider last N archives after other filters were applied
.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
$ borg list /path/to/repo
Monday                               Mon, 2016\-02\-15 19:15:11
repo                                 Mon, 2016\-02\-15 19:26:54
root\-2016\-02\-15                      Mon, 2016\-02\-15 19:36:29
newname                              Mon, 2016\-02\-15 19:50:19
\&...

$ borg list /path/to/repo::root\-2016\-02\-15
drwxr\-xr\-x root   root          0 Mon, 2016\-02\-15 17:44:27 .
drwxrwxr\-x root   root          0 Mon, 2016\-02\-15 19:04:49 bin
\-rwxr\-xr\-x root   root    1029624 Thu, 2014\-11\-13 00:08:51 bin/bash
lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
\-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
\&...

$ borg list /path/to/repo::root\-2016\-02\-15 \-\-pattern \(dq\- bin/ba*\(dq
drwxr\-xr\-x root   root          0 Mon, 2016\-02\-15 17:44:27 .
drwxrwxr\-x root   root          0 Mon, 2016\-02\-15 19:04:49 bin
lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
\-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
\&...

$ borg list /path/to/repo::archiveA \-\-format=\(dq{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}\(dq
drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 .
drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code
drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code/myproject
\-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
\-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
\&...

$ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:\e.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq
\-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
\&...

$ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq
\-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
\-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
\&...
.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.9/library/string.html#formatstrings>
\&.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ borg list \-\-format \(aq{archive}{NL}\(aq /path/to/repo
ArchiveFoo
ArchiveBar
\&...

# {VAR:NUMBER} \- pad to NUMBER columns.
# Strings are left\-aligned, numbers are right\-aligned.
# Note: time columns except \(ga\(gaisomtime\(ga\(ga, \(ga\(gaisoctime\(ga\(ga and \(ga\(gaisoatime\(ga\(ga cannot be padded.
$ borg list \-\-format \(aq{archive:36} {time} [{id}]{NL}\(aq /path/to/repo
ArchiveFoo                           Thu, 2021\-12\-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274]
$ borg list \-\-format \(aq{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}\(aq /path/to/repo::ArchiveFoo
\-rw\-rw\-r\-\- user   user       1024 Thu, 2021\-12\-09 10:22:17 file\-foo
\&...

# {VAR:<NUMBER} \- pad to NUMBER columns left\-aligned.
# {VAR:>NUMBER} \- pad to NUMBER columns right\-aligned.
$ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}\(aq /path/to/repo::ArchiveFoo
\-rw\-rw\-r\-\-   user   user 1024     Thu, 2021\-12\-09 10:22:17 file\-foo
\&...
.EE
.UNINDENT
.UNINDENT
.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, see barchive and bpath keys below
.IP \(bu 2
SPACE
.IP \(bu 2
TAB
.IP \(bu 2
CR
.IP \(bu 2
LF
.UNINDENT
.sp
Keys available only when listing archives in a repository:
.INDENT 0.0
.IP \(bu 2
archive: archive name interpreted as text (might be missing non\-text characters, see barchive)
.IP \(bu 2
name: alias of \(dqarchive\(dq
.IP \(bu 2
barchive: verbatim archive name, can contain any character except NUL
.IP \(bu 2
comment: archive comment interpreted as text (might be missing non\-text characters, see bcomment)
.IP \(bu 2
bcomment: verbatim archive comment, can contain any character except NUL
.IP \(bu 2
id: internal ID of the archive
.IP \(bu 2
tam: TAM authentication state of this archive
.IP \(bu 2
start: time (start) of creation of the archive
.IP \(bu 2
time: alias of \(dqstart\(dq
.IP \(bu 2
end: time (end) of creation of the archive
.IP \(bu 2
command_line: command line which was used to create the archive
.IP \(bu 2
hostname: hostname of host on which this archive was created
.IP \(bu 2
username: username of user who created this archive
.UNINDENT
.sp
Keys available only when listing files in an archive:
.INDENT 0.0
.IP \(bu 2
type
.IP \(bu 2
mode
.IP \(bu 2
uid
.IP \(bu 2
gid
.IP \(bu 2
user
.IP \(bu 2
group
.IP \(bu 2
path: path interpreted as text (might be missing non\-text characters, see bpath)
.IP \(bu 2
bpath: verbatim POSIX path, can contain any character except NUL
.IP \(bu 2
source: link target for links (identical to linktarget)
.IP \(bu 2
linktarget
.IP \(bu 2
flags
.IP \(bu 2
size
.IP \(bu 2
csize: compressed size
.IP \(bu 2
dsize: deduplicated size
.IP \(bu 2
dcsize: deduplicated compressed size
.IP \(bu 2
num_chunks: number of chunks in this file
.IP \(bu 2
unique_chunks: number of unique chunks in this file
.IP \(bu 2
mtime
.IP \(bu 2
ctime
.IP \(bu 2
atime
.IP \(bu 2
isomtime
.IP \(bu 2
isoctime
.IP \(bu 2
isoatime
.IP \(bu 2
blake2b
.IP \(bu 2
blake2s
.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
xxh64: XXH64 checksum of this file (note: this is NOT a cryptographic hash!)
.IP \(bu 2
archiveid
.IP \(bu 2
archivename
.IP \(bu 2
extra: prepends {source} with \(dq \-> \(dq for soft links and \(dq link to \(dq for hard links
.IP \(bu 2
health: either \(dqhealthy\(dq (file ok) or \(dqbroken\(dq (if file has all\-zero replacement chunks)
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-info(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-patterns(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.