upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-05-28 04:03:21 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Merge pull request #6084 from hexagonrecursion/back-port-format

Browse source 
Backport: Improve docs for borg list --format (#6080)
This commit is contained in:
TW 2021-12-10 18:13:03 +01:00 committed by GitHub
commit 5530996309
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 36 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
src/borg/archiver.py
View file

@ -3770,16 +3770,45 @@ class Archiver:
.. man NOTES
The following keys are available for ``--format``:
The FORMAT specifier syntax
+++++++++++++++++++++++++++
The ``--format`` option uses python's `format string syntax
<https://docs.python.org/3.8/library/string.html#formatstrings>`_.
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:
""") + BaseFormatter.keys_help() + textwrap.dedent("""
Keys for listing repository archives:
Keys available only when listing archives in a repository:
""") + ArchiveFormatter.keys_help() + textwrap.dedent("""
Keys for listing archive files:
Keys available only when listing files in an archive:
""") + ItemFormatter.keys_help()
subparser = subparsers.add_parser('list', parents=[common_parser], add_help=False,
@ -3791,8 +3820,9 @@ class Archiver:
subparser.add_argument('--short', dest='short', action='store_true',
help='only print file/directory names, nothing else')
subparser.add_argument('--format', '--list-format', metavar='FORMAT', dest='format',
help='specify format for file listing '
'(default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}")')
help='specify format for file or archive listing '
'(default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; '
'for archives: "{archive:<36} {time} [{id}]{NL}")')
subparser.add_argument('--json', action='store_true',
help='Only valid for listing repository contents. Format output as JSON. '
'The form of ``--format`` is ignored, '

2
src/borg/helpers.py
View file

@ -1777,7 +1777,7 @@ class BaseFormatter:
def keys_help():
return "- NEWLINE: OS dependent line separator\n" \
"- NL: alias of NEWLINE\n" \
"- NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath\n" \
"- NUL: NUL character for creating print0 / xargs -0 like output, see barchive and bpath keys below\n" \
"- SPACE\n" \
"- TAB\n" \
"- CR\n" \