1.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! 2 3.. _borg_list: 4 5borg list 6--------- 7.. code-block:: none 8 9 borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...] 10 11.. only:: html 12 13 .. class:: borg-options-table 14 15 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 16 | **positional arguments** | 17 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 18 | | ``REPOSITORY_OR_ARCHIVE`` | repository or archive to list contents of | 19 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 20 | | ``PATH`` | paths to list; patterns are supported | 21 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 22 | **optional arguments** | 23 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 24 | | ``--short`` | only print file/directory names, nothing else | 25 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 26 | | ``--format FORMAT``, ``--list-format FORMAT`` | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}") | 27 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 28 | | ``--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. | 29 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 30 | | ``--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 output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. | 31 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 32 | .. class:: borg-common-opt-ref | 33 | | 34 | :ref:`common_options` | 35 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 36 | **Archive filters** — Archive filters can be applied to repository targets. | 37 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 38 | | ``-P PREFIX``, ``--prefix PREFIX`` | only consider archive names starting with this prefix. | 39 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 40 | | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. | 41 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 42 | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | 43 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 44 | | ``--first N`` | consider first N archives after other filters were applied | 45 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 46 | | ``--last N`` | consider last N archives after other filters were applied | 47 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 48 | **Exclusion options** | 49 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 50 | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | 51 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 52 | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | 53 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 54 | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | 55 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 56 | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | 57 +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 58 59 .. raw:: html 60 61 <script type='text/javascript'> 62 $(document).ready(function () { 63 $('.borg-options-table colgroup').remove(); 64 }) 65 </script> 66 67.. only:: latex 68 69 REPOSITORY_OR_ARCHIVE 70 repository or archive to list contents of 71 PATH 72 paths to list; patterns are supported 73 74 75 optional arguments 76 --short only print file/directory names, nothing else 77 --format FORMAT, --list-format FORMAT specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}") 78 --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. 79 --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 output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. 80 81 82 :ref:`common_options` 83 | 84 85 Archive filters 86 -P PREFIX, --prefix PREFIX only consider archive names starting with this prefix. 87 -a GLOB, --glob-archives GLOB only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. 88 --sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp 89 --first N consider first N archives after other filters were applied 90 --last N consider last N archives after other filters were applied 91 92 93 Exclusion options 94 -e PATTERN, --exclude PATTERN exclude paths matching PATTERN 95 --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line 96 --pattern PATTERN experimental: include/exclude paths matching PATTERN 97 --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line 98 99 100Description 101~~~~~~~~~~~ 102 103This command lists the contents of a repository or an archive. 104 105See the "borg help patterns" command for more help on exclude patterns. 106 107.. man NOTES 108 109The following keys are available for ``--format``: 110 111- NEWLINE: OS dependent line separator 112- NL: alias of NEWLINE 113- NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath 114- SPACE 115- TAB 116- CR 117- LF 118 119Keys for listing repository archives: 120 121- archive: archive name interpreted as text (might be missing non-text characters, see barchive) 122- name: alias of "archive" 123- barchive: verbatim archive name, can contain any character except NUL 124- comment: archive comment interpreted as text (might be missing non-text characters, see bcomment) 125- bcomment: verbatim archive comment, can contain any character except NUL 126- id: internal ID of the archive 127 128- start: time (start) of creation of the archive 129- time: alias of "start" 130- end: time (end) of creation of the archive 131 132- hostname: hostname of host on which this archive was created 133- username: username of user who created this archive 134 135 136Keys for listing archive files: 137 138- type 139- mode 140- uid 141- gid 142- user 143- group 144- path: path interpreted as text (might be missing non-text characters, see bpath) 145- bpath: verbatim POSIX path, can contain any character except NUL 146- source: link target for links (identical to linktarget) 147- linktarget 148- flags 149 150- size 151- csize: compressed size 152- dsize: deduplicated size 153- dcsize: deduplicated compressed size 154- num_chunks: number of chunks in this file 155- unique_chunks: number of unique chunks in this file 156 157- mtime 158- ctime 159- atime 160- isomtime 161- isoctime 162- isoatime 163 164- blake2b 165- blake2s 166- md5 167- sha1 168- sha224 169- sha256 170- sha384 171- sha3_224 172- sha3_256 173- sha3_384 174- sha3_512 175- sha512 176- shake_128 177- shake_256 178 179- archiveid 180- archivename 181- extra: prepends {source} with " -> " for soft links and " link to " for hard links 182 183- health: either "healthy" (file ok) or "broken" (if file has all-zero replacement chunks) 184