borg/docs/usage/list.rst.inc

.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!

.. _borg_list:

borg list
---------
::

    borg list <options> REPOSITORY_OR_ARCHIVE PATH

positional arguments
    REPOSITORY_OR_ARCHIVE
        repository/archive to list contents of
    PATH
        paths to list; patterns are supported

optional arguments
    ``--short``
        | only print file/directory names, nothing else
    ``--format``, ``--list-format``
        | specify format for file listing
        |                                 (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
    ``-e PATTERN``, ``--exclude PATTERN``
        | exclude paths matching PATTERN
    ``--exclude-from EXCLUDEFILE``
        | read exclude patterns from EXCLUDEFILE, one per line

`Common options`_
    |

filters
    ``-P``, ``--prefix``
        | only consider archive names starting with this prefix
    ``--sort-by``
        | 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

Description
~~~~~~~~~~~

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

See the "borg help patterns" command for more help on exclude patterns.

The following keys are available for --format:
 - NEWLINE: OS dependent line separator
 - NL: alias of NEWLINE
 - NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath
 - SPACE
 - TAB
 - CR
 - LF

-- Keys for listing repository archives:
 - archive: archive name interpreted as text (might be missing non-text characters, see barchive)
 - barchive: verbatim archive name, can contain any character except NUL
 - time: time of creation of the archive
 - id: internal ID of the archive

-- Keys for listing archive files:
 - 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
 - num_chunks: number of chunks in this file
 - unique_chunks: number of unique chunks in this file

 - mtime
 - ctime
 - atime
 - isomtime
 - isoctime
 - isoatime

 - md5
 - sha1
 - sha224
 - sha256
 - sha384
 - sha512

 - 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)
update usage files 2016-07-05 21:30:08 +00:00			`.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!`

commit usage files directly into git the generation of those files was causing us way too much pain to justify automatically generating them all the time. those will have to be re-generated with `build_api` or `build_usage` as appropriate, for example when function signatures or commandline flags change. see #384 2015-11-13 15:42:16 +00:00			`.. _borg_list:`

			`borg list`
			`---------`
			`::`

Better help texts and Sphinx reproduction of usage - Group options - Nicer list of options in Sphinx - Deduplicate 'Common options' (including --help) The latter is done by explicitly declaring --help in the common_parser, which is then inherited by the sub-parsers; no change in observable behaviour. 2016-04-09 23:28:18 +00:00			`borg list <options> REPOSITORY_OR_ARCHIVE PATH`

			`positional arguments`
			`REPOSITORY_OR_ARCHIVE`
			`repository/archive to list contents of`
			`PATH`
			`paths to list; patterns are supported`

			`optional arguments`
			``--short``
			`\| only print file/directory names, nothing else`
			``--format``, ``--list-format``
			`\| specify format for file listing`
			`\| (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")`
			``-e PATTERN``, ``--exclude PATTERN``
			`\| exclude paths matching PATTERN`
			``--exclude-from EXCLUDEFILE``
			`\| read exclude patterns from EXCLUDEFILE, one per line`

			`Common options`_
			`\|`

ran build_usage 2016-10-01 16:23:36 +00:00			`filters`
			``-P``, ``--prefix``
			`\| only consider archive names starting with this prefix`
			``--sort-by``
			`\| 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`

commit usage files directly into git the generation of those files was causing us way too much pain to justify automatically generating them all the time. those will have to be re-generated with `build_api` or `build_usage` as appropriate, for example when function signatures or commandline flags change. see #384 2015-11-13 15:42:16 +00:00			`Description`
			`~~~~~~~~~~~`

			`This command lists the contents of a repository or an archive.`
Update usage docs 2016-03-18 11:17:57 +00:00
			`See the "borg help patterns" command for more help on exclude patterns.`

Add documentation for listing repository archives 2016-06-21 13:18:19 +00:00			`The following keys are available for --format:`
			`- NEWLINE: OS dependent line separator`
			`- NL: alias of NEWLINE`
			`- NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath`
			`- SPACE`
			`- TAB`
			`- CR`
			`- LF`

			`-- Keys for listing repository archives:`
			`- archive: archive name interpreted as text (might be missing non-text characters, see barchive)`
			`- barchive: verbatim archive name, can contain any character except NUL`
			`- time: time of creation of the archive`
			`- id: internal ID of the archive`
Update usage docs 2016-03-18 11:17:57 +00:00
Add documentation for listing repository archives 2016-06-21 13:18:19 +00:00			`-- Keys for listing archive files:`
ItemFormatter: group keys in help output 2016-03-18 12:29:49 +00:00			`- type`
			`- mode`
			`- uid`
			`- gid`
			`- user`
			`- group`
			`- path: path interpreted as text (might be missing non-text characters, see bpath)`
Update usage docs 2016-03-18 11:17:57 +00:00			`- bpath: verbatim POSIX path, can contain any character except NUL`
ItemFormatter: group keys in help output 2016-03-18 12:29:49 +00:00			`- source: link target for links (identical to linktarget)`
			`- linktarget`
Add documentation for listing repository archives 2016-06-21 13:18:19 +00:00			`- flags`
ItemFormatter: group keys in help output 2016-03-18 12:29:49 +00:00
			`- size`
Update usage docs 2016-03-18 11:17:57 +00:00			`- csize: compressed size`
ItemFormatter: group keys in help output 2016-03-18 12:29:49 +00:00			`- num_chunks: number of chunks in this file`
			`- unique_chunks: number of unique chunks in this file`

			`- mtime`
Update usage docs 2016-03-18 11:17:57 +00:00			`- ctime`
ItemFormatter: group keys in help output 2016-03-18 12:29:49 +00:00			`- atime`
Update usage docs 2016-03-18 11:17:57 +00:00			`- isomtime`
ItemFormatter: group keys in help output 2016-03-18 12:29:49 +00:00			`- isoctime`
			`- isoatime`

Update usage docs 2016-03-18 11:17:57 +00:00			`- md5`
			`- sha1`
			`- sha224`
			`- sha256`
			`- sha384`
			`- sha512`
ItemFormatter: group keys in help output 2016-03-18 12:29:49 +00:00
			`- archiveid`
			`- archivename`
			`- extra: prepends {source} with " -> " for soft links and " link to " for hard links`
run setup.py build_usage 2016-12-14 02:42:38 +00:00
			`- health: either "healthy" (file ok) or "broken" (if file has all-zero replacement chunks)`