--- name: "borg2-list" section: "1" platform: "linux" package: "borgbackup2" version: "2.0.0b19-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/borg2-list" --- # borg2-list(1) List archive contents ## NAME borg-list - List archive contents ## SYNOPSIS borg \[common options\] list \[options\] NAME \[PATH...\] ## DESCRIPTION This command lists the contents of an archive. For more help on include/exclude patterns, see the *borg\_patterns* command output. ## OPTIONS See *[borg-common(1)](/borg-common/1.md)* for common options of Borg commands. ### arguments - **NAME** specify the archive name - **PATH** paths to list; patterns are supported ### options - **--short** only print file/directory names, nothing else - **--format** *FORMAT* specify format for file listing (default: "{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. - **--depth** *N* only list files up to the specified directory level depth ### 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 ``` $ borg list 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 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 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 archiveA --pattern '+ re:\.ext$' --pattern '- re:^.*$' -rw-rw-r-- user user 1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext ... $ borg list archiveA --pattern '+ re:.ext$' --pattern '- re:^.*$' -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 '{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}' ArchiveFoo -rw-rw-r-- user user 1024 Thu, 2021-12-09 10:22:17 file-foo ... # {VAR:NUMBER} - pad to NUMBER columns right-aligned. $ borg list --format '{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}' 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 - • SPACE: space character - • TAB: tab character - • CR: carriage return character - • LF: line feed character Keys available only when listing 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) - • 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) - • 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: 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)](/borg-common/1.md)*, *[borg-info(1)](/borg-info/1.md)*, *[borg-diff(1)](/borg-diff/1.md)*, *[borg-prune(1)](/borg-prune/1.md)*, *[borg-patterns(1)](/borg-patterns/1.md)*, *[borg-repo-list(1)](/borg-repo-list/1.md)* ## AUTHOR The Borg Collective