From 89120a984352dbe87cb9041c6308f53a2a1cad60 Mon Sep 17 00:00:00 2001 From: Marian Beermann Date: Fri, 18 Mar 2016 12:17:57 +0100 Subject: [PATCH] Update usage docs --- borg/archiver.py | 9 ++++-- docs/usage.rst | 42 ++++++++++++++++++++++++++++ docs/usage/diff.rst.inc | 5 ++++ docs/usage/list.rst.inc | 61 +++++++++++++++++++++++++++++++++++------ 4 files changed, 107 insertions(+), 10 deletions(-) diff --git a/borg/archiver.py b/borg/archiver.py index 3fc4f52b4..c55ca5959 100644 --- a/borg/archiver.py +++ b/borg/archiver.py @@ -1212,6 +1212,11 @@ class Archiver: Both archives need to be in the same repository, and a repository location may only be specified for ARCHIVE1. + For archives created with Borg 1.1 or newer only chunks IDs + are compared, which is very fast. For archives prior to Borg 1.1 chunk contents must be + compared, unless you are sure they were created with the same chunker params + (pass --same-chunker-params). Note that the chunker params changed from Borg 0.xx to 1.0. + See the output of the "borg help patterns" command for more help on exclude patterns. """) subparser = subparsers.add_parser('diff', parents=[common_parser], @@ -1289,7 +1294,7 @@ class Archiver: See the "borg help patterns" command for more help on exclude patterns. - The following keys are available for --format: + The following keys are available for --format when listing files: """) + ItemFormatter.keys_help() subparser = subparsers.add_parser('list', parents=[common_parser], @@ -1316,7 +1321,7 @@ class Archiver: type=location_validator(), help='repository/archive to list contents of') subparser.add_argument('paths', metavar='PATH', nargs='*', type=str, - help='paths to extract; patterns are supported') + help='paths to list; patterns are supported') mount_epilog = textwrap.dedent(""" This command mounts an archive as a FUSE filesystem. This can be useful for diff --git a/docs/usage.rst b/docs/usage.rst index b8284e254..8c321d087 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -374,6 +374,48 @@ Examples ... + +.. include:: usage/diff.rst.inc + +Examples +~~~~~~~~ +:: + + $ mkdir testdir + $ echo asdf > testdir/file1 + $ dd if=/dev/urandom bs=1M count=4 > testdir/file2 + $ touch testdir/file3 + + $ borg init testrepo + $ borg create testrepo::archive1 testdir + + $ chmod a+x testdir/file1 + $ echo "something" >> testdir/file2 + $ borg create testrepo::archive2 testdir + + $ rm testdir/file3 + $ borg create testrepo::archive3 testdir + + $ borg diff testrepo::archive1 archive2 + testdir/file1 different mode + archive1 -rw-r--r-- + archive2 -rwxr-xr-x + testdir/file2 different contents + +28 B, -31 B, 4.19 MB, 4.19 MB + + $ borg diff testrepo::archive2 archive3 + testdir/file3 different contents + +0 B, -0 B, 0 B, + + $ borg diff testrepo::archive1 archive3 + testdir/file1 different mode + archive1 -rw-r--r-- + archive3 -rwxr-xr-x + testdir/file2 different contents + +28 B, -31 B, 4.19 MB, 4.19 MB + testdir/file3 different contents + +0 B, -0 B, 0 B, + .. include:: usage/delete.rst.inc Examples diff --git a/docs/usage/diff.rst.inc b/docs/usage/diff.rst.inc index a74ef35ac..546746ef2 100644 --- a/docs/usage/diff.rst.inc +++ b/docs/usage/diff.rst.inc @@ -48,4 +48,9 @@ This command finds differences in files (contents, user, group, mode) between ar Both archives need to be in the same repository, and a repository location may only be specified for ARCHIVE1. +For archives created with Borg 1.1 or newer only chunks IDs +are compared, which is very fast. For archives prior to Borg 1.1 chunk contents must be +compared, unless you are sure they were created with the same chunker params +(pass --same-chunker-params). Note that the chunker params changed from Borg 0.xx to 1.0. + See the output of the "borg help patterns" command for more help on exclude patterns. diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index 02e40b70a..009f6f09f 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -6,15 +6,16 @@ borg list usage: borg list [-h] [-v] [--debug] [--lock-wait N] [--show-version] [--show-rc] [--no-files-cache] [--umask M] - [--remote-path PATH] [--short] [--list-format LISTFORMAT] - [-P PREFIX] - [REPOSITORY_OR_ARCHIVE] + [--remote-path PATH] [--short] [--format FORMAT] [-P PREFIX] + [-e PATTERN] [--exclude-from EXCLUDEFILE] + [REPOSITORY_OR_ARCHIVE] [PATH [PATH ...]] List archive or repository contents positional arguments: REPOSITORY_OR_ARCHIVE repository/archive to list contents of + PATH paths to list; patterns are supported optional arguments: -h, --help show this help message and exit @@ -30,15 +31,59 @@ borg list --umask M set umask to M (local and remote, default: 0077) --remote-path PATH set remote path to executable (default: "borg") --short only print file/directory names, nothing else - --list-format LISTFORMAT - specify format for archive file listing (default: - "{mode} {user:6} {group:6} {size:8d} {isomtime} - {path}{extra}{NEWLINE}") Special "{formatkeys}" exists - to list available keys + --format FORMAT, --list-format FORMAT + specify format for file listing (default: "{mode} + {user:6} {group:6} {size:8d} {isomtime} + {path}{extra}{NL}") -P PREFIX, --prefix PREFIX only consider archive names starting with this prefix + -e PATTERN, --exclude PATTERN + exclude paths matching PATTERN + --exclude-from EXCLUDEFILE + read exclude patterns from EXCLUDEFILE, one per line 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 when listing files: + + - archiveid + - archivename + - atime + - bpath: verbatim POSIX path, can contain any character except NUL + - csize: compressed size + - ctime + - extra + - gid + - group + - isoatime + - isoctime + - isomtime + - linktarget + - md5 + - mode + - mtime + - num_chunks: number of chunks in this file + - path: path interpreted as text (might be missing non-text characters, see bpath) + - sha1 + - sha224 + - sha256 + - sha384 + - sha512 + - size + - source: link target for links (identical to linktarget) + - type + - uid + - unique_chunks: number of unique chunks in this file + - user + - CR + - LF + - NEWLINE: OS dependent line separator + - NL: alias of NEWLINE + - NUL: NUL character for creating print0 / xargs -0 like ouput, see bpath + - SPACE + - TAB \ No newline at end of file