borg-list

BORG-LIST(1) borg backup tool BORG-LIST(1)

NAME

   borg-list - List archive or repository contents

SYNOPSIS

   borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...]

DESCRIPTION

   This command lists the contents of a repository or an archive.

   For more help on include/exclude patterns, see the borg_patterns command output.

OPTIONS

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

arguments

   REPOSITORY_OR_ARCHIVE
          repository or archive to list contents of

   PATH   paths to list; patterns are supported

options

   --consider-checkpoints
          Show checkpoint archives in the repository contents list (default: hidden).

   --short
          only print file/directory names, nothing else

   --format FORMAT
          specify  format  for  file  or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{ar‐
          chive:<36} {time} [{id}]{NL}")

   --json Only valid for listing repository contents. Format output as JSON. 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. A "barchive" key is therefore not available.

   --json-lines
          Only  valid for listing archive contents. Format output as JSON Lines. The form of --format is ignored, but keys used in it are added to the JSON out‐
          put. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.

Archive filters

   -P PREFIX, --prefix PREFIX
          only consider archive names starting with this prefix. (deprecated)

   -a GLOB, --glob-archives GLOB
          only consider archive names matching the glob. sh: rules apply, see "borg help patterns".

   --sort-by KEYS
          Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp

   --first N
          consider first N archives after other filters were applied

   --last N
          consider last N archives after other filters were applied

Exclusion 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

      $ 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 "- bin/ba*"
      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="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
      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 're:\.ext$'
      -rw-rw-r-- user   user    1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext
      ...

      $ borg list /path/to/repo/::archiveA --pattern 're:.ext$'
      -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
      ...

NOTES The FORMAT specifier syntax

   The --format option uses python's format string syntax.

   Examples:

      $ borg list --format '{archive}{NL}' /path/to/repo
      ArchiveFoo
      ArchiveBar
      ...

      # {VAR:NUMBER} - pad to NUMBER columns.
      # Strings are left-aligned, numbers are right-aligned.
      # Note: time columns except ``isomtime``, ``isoctime`` and ``isoatime`` cannot be padded.
      $ borg list --format '{archive:36} {time} [{id}]{NL}' /path/to/repo
      ArchiveFoo                           Thu, 2021-12-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274]
      $ borg list --format '{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}' /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 '{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo
      -rw-rw-r--   user   user 1024     Thu, 2021-12-09 10:22:17 file-foo
      ...

   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, see barchive and bpath keys below

   • SPACE

   • TAB

   • CR

   • LF

   Keys available only when listing archives in a repository:

   • archive: archive name interpreted as text (might be missing non-text characters, see barchive)

   • name: alias of "archive"

   • barchive: verbatim archive name, can contain any character except NUL

   • comment: archive comment interpreted as text (might be missing non-text characters, see bcomment)

   • bcomment: verbatim archive comment, can contain any character except NUL

   • id: internal ID of the archive

   • start: time (start) of creation of the archive

   • time: alias of "start"

   • end: time (end) of creation of the archive

   • command_line: command line which was used to create the archive

   • hostname: hostname of host on which this archive was created

   • username: username of user who created this archive

   Keys available only when listing files in an archive:

   • type

   • mode

   • uid

   • gid

   • user

   • group

   • path: path interpreted as text (might be missing non-text characters, see bpath)

   • bpath: verbatim POSIX path, can contain any character except NUL

   • source: link target for links (identical to linktarget)

   • linktarget

   • flags

   • size

   • csize: compressed size

   • dsize: deduplicated size

   • dcsize: deduplicated compressed size

   • num_chunks: number of chunks in this file

   • unique_chunks: number of unique chunks in this file

   • mtime

   • ctime

   • atime

   • isomtime

   • isoctime

   • isoatime

   • blake2b

   • blake2s

   • md5

   • sha1

   • sha224

   • sha256

   • sha384

   • sha3_224

   • sha3_256

   • sha3_384

   • sha3_512

   • sha512

   • xxh64: XXH64 checksum of this file (note: this is NOT a cryptographic hash!)

   • archiveid

   • archivename

   • extra: prepends {source} with " -> " for soft links and " link to " for hard links

   • health: either "healthy" (file ok) or "broken" (if file has all-zero replacement chunks)