ran setup.py build_usage

docs/usage/create.rst.inc

@@ -6,7 +6,7 @@ borg create
 
     usage: borg create [-h] [-v] [--debug] [--lock-wait N] [--show-rc]
                        [--no-files-cache] [--umask M] [--remote-path PATH] [-s]
-                       [-p] [--filter STATUSCHARS] [-e PATTERN]
+                       [-p] [--list] [--filter STATUSCHARS] [-e PATTERN]
                        [--exclude-from EXCLUDEFILE] [--exclude-caches]
                        [--exclude-if-present FILENAME] [--keep-tag-files]
                        [-c SECONDS] [-x] [--numeric-owner]
@@ -39,6 +39,7 @@ borg create
                             showing Original, Compressed and Deduplicated sizes,
                             followed by the Number of files seen and the path
                             being processed, default: False
+      --list                output verbose list of items (files, dirs, ...)
       --filter STATUSCHARS  only display items with the given status characters
       -e PATTERN, --exclude PATTERN
                             exclude paths matching PATTERN

docs/usage/delete.rst.inc

@@ -5,8 +5,8 @@ borg delete
 ::
 
     usage: borg delete [-h] [-v] [--debug] [--lock-wait N] [--show-rc]
-                       [--no-files-cache] [--umask M] [--remote-path PATH] [-s]
-                       [-c] [--save-space]
+                       [--no-files-cache] [--umask M] [--remote-path PATH] [-p]
+                       [-s] [-c] [--save-space]
                        [TARGET]
     
     Delete an existing repository or archive
@@ -26,6 +26,7 @@ borg delete
                             detect unchanged files
       --umask M             set umask to M (local and remote, default: 0077)
       --remote-path PATH    set remote path to executable (default: "borg")
+      -p, --progress        show progress display while deleting a single archive
       -s, --stats           print statistics for the deleted archive
       -c, --cache-only      delete only the local cache for the given repository
       --save-space          work slower, but using less space

docs/usage/extract.rst.inc

@@ -15,7 +15,7 @@ borg extract
     
     positional arguments:
       ARCHIVE               archive to extract
-      PATH                  paths to extract
+      PATH                  paths to extract; patterns are supported
     
     optional arguments:
       -h, --help            show this help message and exit

docs/usage/help.rst.inc

@@ -5,30 +5,88 @@ borg help patterns
 ::
 
 
-        Exclude patterns use a variant of shell pattern syntax, with '*' matching any
-        number of characters, '?' matching any single character, '[...]' matching any
-        single character specified, including ranges, and '[!...]' matching any
-        character not specified.  For the purpose of these patterns, the path
-        separator ('\' for Windows and '/' on other systems) is not treated
-        specially.  For a path to match a pattern, it must completely match from
-        start to end, or must match from the start to just before a path separator.
-        Except for the root path, paths will never end in the path separator when
-        matching is attempted.  Thus, if a given pattern ends in a path separator, a
-        '*' is appended before matching is attempted.  Patterns with wildcards should
-        be quoted to protect them from shell expansion.
-
-        Examples:
-
-        # Exclude '/home/user/file.o' but not '/home/user/file.odt':
-        $ borg create -e '*.o' backup /
-
-        # Exclude '/home/user/junk' and '/home/user/subdir/junk' but
-        # not '/home/user/importantjunk' or '/etc/junk':
-        $ borg create -e '/home/*/junk' backup /
-
-        # Exclude the contents of '/home/user/cache' but not the directory itself:
-        $ borg create -e /home/user/cache/ backup /
-
-        # The file '/home/user/cache/important' is *not* backed up:
-        $ borg create -e /home/user/cache/ backup / /home/user/cache/important
-        
+Exclusion patterns support four separate styles, fnmatch, shell, regular
+expressions and path prefixes. If followed by a colon (':') the first two
+characters of a pattern are used as a style selector. Explicit style
+selection is necessary when a non-default style is desired or when the
+desired pattern starts with two alphanumeric characters followed by a colon
+(i.e. `aa:something/*`).
+
+`Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector `fm:`
+
+    These patterns use a variant of shell pattern syntax, with '*' matching
+    any number of characters, '?' matching any single character, '[...]'
+    matching any single character specified, including ranges, and '[!...]'
+    matching any character not specified. For the purpose of these patterns,
+    the path separator ('\' for Windows and '/' on other systems) is not
+    treated specially. Wrap meta-characters in brackets for a literal match
+    (i.e. `[?]` to match the literal character `?`). For a path to match
+    a pattern, it must completely match from start to end, or must match from
+    the start to just before a path separator. Except for the root path,
+    paths will never end in the path separator when matching is attempted.
+    Thus, if a given pattern ends in a path separator, a '*' is appended
+    before matching is attempted.
+
+Shell-style patterns, selector `sh:`
+
+    Like fnmatch patterns these are similar to shell patterns. The difference
+    is that the pattern may include `**/` for matching zero or more directory
+    levels, `*` for matching zero or more arbitrary characters with the
+    exception of any path separator.
+
+Regular expressions, selector `re:`
+
+    Regular expressions similar to those found in Perl are supported. Unlike
+    shell patterns regular expressions are not required to match the complete
+    path and any substring match is sufficient. It is strongly recommended to
+    anchor patterns to the start ('^'), to the end ('$') or both. Path
+    separators ('\' for Windows and '/' on other systems) in paths are
+    always normalized to a forward slash ('/') before applying a pattern. The
+    regular expression syntax is described in the `Python documentation for
+    the re module <https://docs.python.org/3/library/re.html>`_.
+
+Prefix path, selector `pp:`
+
+    This pattern style is useful to match whole sub-directories. The pattern
+    `pp:/data/bar` matches `/data/bar` and everything therein.
+
+Exclusions can be passed via the command line option `--exclude`. When used
+from within a shell the patterns should be quoted to protect them from
+expansion.
+
+The `--exclude-from` option permits loading exclusion patterns from a text
+file with one pattern per line. Lines empty or starting with the number sign
+('#') after removing whitespace on both ends are ignored. The optional style
+selector prefix is also supported for patterns loaded from a file. Due to
+whitespace removal paths with whitespace at the beginning or end can only be
+excluded using regular expressions.
+
+Examples:
+
+# Exclude '/home/user/file.o' but not '/home/user/file.odt':
+$ borg create -e '*.o' backup /
+
+# Exclude '/home/user/junk' and '/home/user/subdir/junk' but
+# not '/home/user/importantjunk' or '/etc/junk':
+$ borg create -e '/home/*/junk' backup /
+
+# Exclude the contents of '/home/user/cache' but not the directory itself:
+$ borg create -e /home/user/cache/ backup /
+
+# The file '/home/user/cache/important' is *not* backed up:
+$ borg create -e /home/user/cache/ backup / /home/user/cache/important
+
+# The contents of directories in '/home' are not backed up when their name
+# ends in '.tmp'
+$ borg create --exclude 're:^/home/[^/]+\.tmp/' backup /
+
+# Load exclusions from file
+$ cat >exclude.txt <<EOF
+# Comment line
+/home/*/junk
+*.tmp
+fm:aa:something/*
+re:^/home/[^/]\.tmp/
+sh:/home/*/.thumbnails
+EOF
+$ borg create --exclude-from exclude.txt backup /

docs/usage/migrate-to-repokey.rst.inc

@@ -0,0 +1,48 @@
+.. _borg_migrate-to-repokey:
+
+borg migrate-to-repokey
+-----------------------
+::
+
+    usage: borg migrate-to-repokey [-h] [-v] [--debug] [--lock-wait N] [--show-rc]
+                                   [--no-files-cache] [--umask M]
+                                   [--remote-path PATH]
+                                   [REPOSITORY]
+    
+    Migrate passphrase -> repokey
+    
+    positional arguments:
+      REPOSITORY
+    
+    optional arguments:
+      -h, --help            show this help message and exit
+      -v, --verbose, --info
+                            enable informative (verbose) output, work on log level
+                            INFO
+      --debug               enable debug output, work on log level DEBUG
+      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
+      --show-rc             show/log the return code (rc)
+      --no-files-cache      do not load/update the file metadata cache used to
+                            detect unchanged files
+      --umask M             set umask to M (local and remote, default: 0077)
+      --remote-path PATH    set remote path to executable (default: "borg")
+    
+Description
+~~~~~~~~~~~
+
+This command migrates a repository from passphrase mode (not supported any
+more) to repokey mode.
+
+You will be first asked for the repository passphrase (to open it in passphrase
+mode). This is the same passphrase as you used to use for this repo before 1.0.
+
+It will then derive the different secrets from this passphrase.
+
+Then you will be asked for a new passphrase (twice, for safety). This
+passphrase will be used to protect the repokey (which contains these same
+secrets in encrypted form). You may use the same passphrase as you used to
+use, but you may also use a different one.
+
+After migrating to repokey mode, you can change the passphrase at any time.
+But please note: the secrets will always stay the same and they could always
+be derived from your (old) passphrase-mode passphrase.

docs/usage/upgrade.rst.inc

@@ -5,8 +5,8 @@ borg upgrade
 ::
 
     usage: borg upgrade [-h] [-v] [--debug] [--lock-wait N] [--show-rc]
-                        [--no-files-cache] [--umask M] [--remote-path PATH] [-n]
-                        [-i]
+                        [--no-files-cache] [--umask M] [--remote-path PATH] [-p]
+                        [-n] [-i]
                         [REPOSITORY]
     
     upgrade a repository from a previous version
@@ -26,6 +26,7 @@ borg upgrade
                             detect unchanged files
       --umask M             set umask to M (local and remote, default: 0077)
       --remote-path PATH    set remote path to executable (default: "borg")
+      -p, --progress        show progress display while upgrading the repository
       -n, --dry-run         do not change repository
       -i, --inplace         rewrite repository in place, with no chance of going
                             back to older versions of the repository.
@@ -33,38 +34,38 @@ borg upgrade
 Description
 ~~~~~~~~~~~
 
-upgrade an existing Borg repository. this currently
-only support converting an Attic repository, but may
+Upgrade an existing Borg repository. This currently
+only supports converting an Attic repository, but may
 eventually be extended to cover major Borg upgrades as well.
 
-it will change the magic strings in the repository's segments
-to match the new Borg magic strings. the keyfiles found in
+It will change the magic strings in the repository's segments
+to match the new Borg magic strings. The keyfiles found in
 $ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and
 copied to $BORG_KEYS_DIR or ~/.borg/keys.
 
-the cache files are converted, from $ATTIC_CACHE_DIR or
+The cache files are converted, from $ATTIC_CACHE_DIR or
 ~/.cache/attic to $BORG_CACHE_DIR or ~/.cache/borg, but the
 cache layout between Borg and Attic changed, so it is possible
 the first backup after the conversion takes longer than expected
 due to the cache resync.
 
-upgrade should be able to resume if interrupted, although it
-will still iterate over all segments. if you want to start
+Upgrade should be able to resume if interrupted, although it
+will still iterate over all segments. If you want to start
 from scratch, use `borg delete` over the copied repository to
 make sure the cache files are also removed:
 
     borg delete borg
 
-unless ``--inplace`` is specified, the upgrade process first
+Unless ``--inplace`` is specified, the upgrade process first
 creates a backup copy of the repository, in
-REPOSITORY.upgrade-DATETIME, using hardlinks. this takes
+REPOSITORY.upgrade-DATETIME, using hardlinks. This takes
 longer than in place upgrades, but is much safer and gives
-progress information (as opposed to ``cp -al``). once you are
+progress information (as opposed to ``cp -al``). Once you are
 satisfied with the conversion, you can safely destroy the
 backup copy.
 
-WARNING: running the upgrade in place will make the current
+WARNING: Running the upgrade in place will make the current
 copy unusable with older version, with no way of going back
-to previous versions. this can PERMANENTLY DAMAGE YOUR
+to previous versions. This can PERMANENTLY DAMAGE YOUR
 REPOSITORY!  Attic CAN NOT READ BORG REPOSITORIES, as the
-magic strings have changed. you have been warned.
+magic strings have changed. You have been warned.