build_usage

4 files changed, 40 insertions, 38 deletions

diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc
index e4e530a2..0f4ff7af 100644
--- a/docs/usage/check.rst.inc
+++ b/docs/usage/check.rst.inc
@@ -138,15 +138,18 @@ Second, the consistency and correctness of the archive metadata is verified:
 The ``--max-duration`` option can be used to split a long-running repository check
 into multiple partial checks. After the given number of seconds the check is
 interrupted. The next partial check will continue where the previous one stopped,
-until the complete repository has been checked. Example: Assuming a full check took 7
+until the complete repository has been checked. Example: Assuming a complete check took 7
 hours, then running a daily check with --max-duration=3600 (1 hour) resulted in one
-full check per week.
-
-Attention: Partial checks can only do way less checking than a full check (only the
-CRC32 checks on segment file entries are done), and cannot be combined with the
-``--repair`` option. Partial checks may therefore be useful only with very large
-repositories where a full check took too long. Doing a full repository check aborts a
-partial check; the next partial check will restart from the beginning.
+completed check per week.
+
+Attention: A partial --repository-only check can only do way less checking than a full
+--repository-only check: only the non-cryptographic checksum checks on segment file
+entries are done, while a full --repository-only check would also do a repo index check.
+A partial check cannot be combined with the ``--repair`` option. Partial checks
+may therefore be useful only with very large repositories where a full check would take
+too long.
+Doing a full repository check aborts a partial check; the next partial check will restart
+from the beginning.
 
 The ``--verify-data`` option will perform a full integrity verification (as opposed to
 checking the CRC32 of the segment) of data, which means reading the data from the
diff --git a/docs/usage/compact.rst.inc b/docs/usage/compact.rst.inc
index 3d67fe5d..8187bbf7 100644
--- a/docs/usage/compact.rst.inc
+++ b/docs/usage/compact.rst.inc
@@ -71,6 +71,7 @@ When using ``--verbose``, borg will output an estimate of the freed space.
 
 After upgrading borg (server) to 1.2+, you can use ``borg compact --cleanup-commits``
 to clean up the numerous 17byte commit-only segments that borg 1.1 did not clean up
-due to a bug. It is enough to do that once per repository.
+due to a bug. It is enough to do that once per repository. After cleaning up the
+commits, borg will also do a normal compaction.
 
 See :ref:`separate_compaction` in Additional Notes for more details.
\ No newline at end of file
diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc
index cb377b2a..b61fb979 100644
--- a/docs/usage/create.rst.inc
+++ b/docs/usage/create.rst.inc
@@ -37,7 +37,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--stdin-user USER``                             | set user USER in archive for stdin data (default: 'root')                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'wheel')                                                                                         |
+    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'root')                                                                                          |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--stdin-mode M``                                | set mode to M in archive for stdin data (default: 0660)                                                                                              |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -139,7 +139,7 @@ borg create
         --no-cache-sync    experimental: do not synchronize the cache. Implies not using the files cache.
         --stdin-name NAME    use NAME in archive for stdin data (default: 'stdin')
         --stdin-user USER    set user USER in archive for stdin data (default: 'root')
-        --stdin-group GROUP    set group GROUP in archive for stdin data (default: 'wheel')
+        --stdin-group GROUP    set group GROUP in archive for stdin data (default: 'root')
         --stdin-mode M    set mode to M in archive for stdin data (default: 0660)
         --content-from-command    interpret PATH as command and store its stdout. See also section Reading from stdin below.
         --paths-from-stdin    read DELIM-separated list of paths to backup from stdin. Will not recurse into directories.
diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc
index 39dcca80..31c29b6a 100644
--- a/docs/usage/help.rst.inc
+++ b/docs/usage/help.rst.inc
@@ -10,15 +10,12 @@ The path/filenames used as input for the pattern matching start from the
 currently active recursion root. You usually give the recursion root(s)
 when invoking borg and these can be either relative or absolute paths.
 
-So, when you give `relative/` as root, the paths going into the matcher
-will look like `relative/.../file.ext`. When you give `/absolute/` as
-root, they will look like `/absolute/.../file.ext`.
-
-File paths in Borg archives are always stored normalized and relative.
-This means that e.g. ``borg create /path/to/repo ../some/path`` will
-store all files as `some/path/.../file.ext` and ``borg create
-/path/to/repo /home/user`` will store all files as
-`home/user/.../file.ext`.
+If you give `/absolute/` as root, the paths going into the matcher will
+look relative like `absolute/.../file.ext`, because file paths in Borg
+archives are always stored normalized and relative. This means that e.g.
+``borg create /path/to/repo ../some/path`` will store all files as
+`some/path/.../file.ext` and ``borg create /path/to/repo /home/user``
+will store all files as `home/user/.../file.ext`.
 
 A directory exclusion pattern can end either with or without a slash ('/').
 If it ends with a slash, such as `some/path/`, the directory will be
@@ -31,10 +28,11 @@ path prefixes and path full-matches. By default, fnmatch is used for
 option. For commands that support patterns in their ``PATH`` argument
 like (``borg list``), the default pattern is path prefix.
 
-Starting with Borg 1.2, for all but regular expression pattern matching
-styles, all paths are treated as relative, meaning that a leading path
-separator is removed after normalizing and before matching. This allows
-you to use absolute or relative patterns arbitrarily.
+Starting with Borg 1.2, discovered fs paths are normalised, have leading
+slashes removed and then are matched against your patterns.
+Note: You need to review your include / exclude patterns and make
+sure they do not expect leading slashes. Borg can only deal with this
+for some very simple patterns by removing leading slashes there also.
 
 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
@@ -124,26 +122,26 @@ Examples::
 
     # Exclude '/home/user/junk' and '/home/user/subdir/junk' but
     # not '/home/user/importantjunk' or '/etc/junk':
-    $ borg create -e '/home/*/junk' backup /
+    $ 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
+    $ 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 /
+    $ borg create --exclude 're:^home/[^/]+\.tmp/' backup /
 
     # Load exclusions from file
     $ cat >exclude.txt <<EOF
     # Comment line
-    /home/*/junk
+    home/*/junk
     *.tmp
     fm:aa:something/*
-    re:^/home/[^/]+\.tmp/
-    sh:/home/*/.thumbnails
+    re:^home/[^/]+\.tmp/
+    sh:home/*/.thumbnails
     # Example with spaces, no need to escape as it is processed by borg
     some file with spaces.txt
     EOF
@@ -197,23 +195,23 @@ The patterns.lst file could look like that::
     P sh
     R /
     # can be rebuild
-    - /home/*/.cache
+    - home/*/.cache
     # they're downloads for a reason
-    - /home/*/Downloads
+    - home/*/Downloads
     # susan is a nice person
     # include susans home
-    + /home/susan
+    + home/susan
     # also back up this exact file
-    + pf:/home/bobby/specialfile.txt
+    + pf:home/bobby/specialfile.txt
     # don't backup the other home directories
-    - /home/*
+    - home/*
     # don't even look in /proc
-    ! /proc
+    ! proc
 
 You can specify recursion roots either on the command line or in a patternfile::
 
     # these two commands do the same thing
-    borg create --exclude /home/bobby/junk repo::arch /home/bobby /home/susan
+    borg create --exclude home/bobby/junk repo::arch /home/bobby /home/susan
     borg create --patterns-from patternfile.lst repo::arch
 
 The patternfile::
@@ -224,7 +222,7 @@ The patternfile::
     R /home/bobby
     R /home/susan
 
-    - /home/bobby/junk
+    - home/bobby/junk
 
 This allows you to share the same patterns between multiple repositories
 without needing to specify them on the command line.