Merge pull request #5590 from ThomasWaldmann/rel1115

release 1.1.15

docs/changes.rst

@@ -217,8 +217,8 @@ The best check that everything is ok is to run a dry-run extraction::
 Changelog
 =========
 
-Version 1.1.15 (not released yet)
----------------------------------
+Version 1.1.15 (2020-12-25)
+---------------------------
 
 Compatibility notes:
 
@@ -247,13 +247,19 @@ Compatibility notes:
 
 Fixes:
 
-- use --timestamp for {utcnow} and {now} if given, #5189
-- create: fix --dry-run and --stats coexistence, #5415
+- extract:
+
+  - improve exception handling when setting xattrs, #5092.
+  - emit a warning message giving the path, xattr key and error message.
+  - continue trying to restore other xattrs and bsdflags of the same file
+    after an exception with xattr-setting happened.
 - export-tar:
 
   - set tar format to GNU_FORMAT explicitly, #5274
   - fix memory leak with ssh: remote repository, #5568
   - fix potential memory leak with ssh: remote repository with partial extraction
+- create: fix --dry-run and --stats coexistence, #5415
+- use --timestamp for {utcnow} and {now} if given, #5189
 
 New features:
 
@@ -268,6 +274,7 @@ Other changes:
 - set cython language_level in some files to fix warnings
 - allow EIO with warning when trying to hardlink
 - PropDict: fail early if internal_dict is not a dict
+- update shell completions
 - tests / CI
 
   - add a test for the hashindex corruption bug, #5531 #4829
@@ -293,6 +300,7 @@ Other changes:
   - new compression algorithm policy, #1633 #5505
   - faq: add a hint on sleeping computer, #5301
   - note requirements for full disk access on macOS Catalina, #5303
+  - fix/improve description of borg upgrade hardlink usage, #5518
 - modernize 1.1 code:
 
   - drop code/workarounds only needed to support Python 3.4

docs/man/borg-benchmark-crud.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK-CRUD 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-BENCHMARK-CRUD 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .

docs/man/borg-benchmark.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-BENCHMARK 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-benchmark \- benchmark command
 .

docs/man/borg-break-lock.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BREAK-LOCK 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .

docs/man/borg-change-passphrase.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHANGE-PASSPHRASE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-CHANGE-PASSPHRASE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-change-passphrase \- Change repository key file passphrase
 .

docs/man/borg-check.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHECK 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-CHECK 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .

docs/man/borg-common.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMMON 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-COMMON 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .

docs/man/borg-compression.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMPRESSION 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .

docs/man/borg-config.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CONFIG 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-CONFIG 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-config \- get, set, and delete values in a repository or cache config file
 .

docs/man/borg-create.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CREATE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-CREATE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .
@@ -117,6 +117,7 @@ the state after creation. Also, the \fB\-\-stats\fP and \fB\-\-dry\-run\fP optio
 exclusive because the data is not actually compressed and deduplicated during a dry run.
 .sp
 See the output of the "borg help patterns" command for more help on exclude patterns.
+.sp
 See the output of the "borg help placeholders" command for more help on placeholders.
 .SH OPTIONS
 .sp
@@ -156,6 +157,15 @@ do not load/update the file metadata cache used to detect unchanged files
 .TP
 .BI \-\-stdin\-name \ NAME
 use NAME in archive for stdin data (default: "stdin")
+.TP
+.BI \-\-stdin\-user \ USER
+set user USER in archive for stdin data (default: \(aqroot\(aq)
+.TP
+.BI \-\-stdin\-group \ GROUP
+set group GROUP in archive for stdin data (default: \(aqroot\(aq)
+.TP
+.BI \-\-stdin\-mode \ M
+set mode to M in archive for stdin data (default: 0660)
 .UNINDENT
 .SS Exclusion options
 .INDENT 0.0
@@ -188,7 +198,7 @@ exclude files flagged NODUMP
 .INDENT 0.0
 .TP
 .B \-x\fP,\fB  \-\-one\-file\-system
-stay in the same file system and do not store mount points of other file systems
+stay in the same file system and do not store mount points of other file systems.  This might behave different from your expectations, see the docs.
 .TP
 .B \-\-numeric\-owner
 only store numeric user and group identifiers
@@ -320,6 +330,17 @@ all of its contents will be omitted from the backup.  If, however, you wish to
 only include the objects specified by \fB\-\-exclude\-if\-present\fP in your backup,
 and not include any other contents of the containing folder, this can be enabled
 through using the \fB\-\-keep\-exclude\-tags\fP option.
+.sp
+The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories, that are mountpoints (and everything in them).
+It detects mountpoints by comparing the device number from the output of \fBstat()\fP of the directory and its
+parent directory. Specifically, it excludes directories for which \fBstat()\fP reports a device number different
+from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
+with device number different from their parent, which the kernel does not consider a mountpoint and also the
+other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
+subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
+using \fB\-\-one\-file\-system\fP, one should make doubly sure that the backup works as intended especially when using
+btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
+installer.
 .SS Item flags
 .sp
 \fB\-\-list\fP outputs a list of all files, directories and other

docs/man/borg-delete.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-DELETE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .

docs/man/borg-diff.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DIFF 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-DIFF 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .

docs/man/borg-export-tar.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXPORT-TAR 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-EXPORT-TAR 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .

docs/man/borg-extract.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXTRACT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .

docs/man/borg-info.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INFO 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-INFO 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .

docs/man/borg-init.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INIT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-INIT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .

docs/man/borg-key-change-passphrase.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .

docs/man/borg-key-export.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-EXPORT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .

docs/man/borg-key-import.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-IMPORT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .

docs/man/borg-key-migrate-to-repokey.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .

docs/man/borg-key.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-KEY 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-key \- Manage a keyfile or repokey of a repository
 .

docs/man/borg-list.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-LIST 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-LIST 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .
@@ -119,6 +119,13 @@ lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdif
 \-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
 \&...
 
+$ borg list /path/to/repo::root\-2016\-02\-15 \-\-pattern "\- bin/ba*"
+drwxr\-xr\-x root   root          0 Mon, 2016\-02\-15 17:44:27 .
+drwxrwxr\-x root   root          0 Mon, 2016\-02\-15 19:04:49 bin
+lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
+\-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
+\&...
+
 $ borg list /path/to/repo::archiveA \-\-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 .
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code

docs/man/borg-mount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-MOUNT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .

docs/man/borg-patterns.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PATTERNS 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .
@@ -168,8 +168,10 @@ $ cat >exclude.txt <<EOF
 /home/*/junk
 *.tmp
 fm:aa:something/*
-re:^/home/[^/]\e.tmp/
-sh:/home/*/.thumbnails
+re:^home/[^/]\e.tmp/
+sh:home/*/.thumbnails
+ # Example with spaces, no need to escape as it is processed by borg
+some file with spaces.txt
 EOF
 $ borg create \-\-exclude\-from exclude.txt backup /
 .ft P

docs/man/borg-placeholders.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PLACEHOLDERS 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-PLACEHOLDERS 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .

docs/man/borg-prune.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PRUNE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .

docs/man/borg-recreate.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RECREATE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .

docs/man/borg-rename.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RENAME 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-RENAME 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .

docs/man/borg-serve.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-SERVE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-SERVE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .

docs/man/borg-umount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UMOUNT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-UMOUNT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .

docs/man/borg-upgrade.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UPGRADE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-UPGRADE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous version
 .

docs/man/borg-with-lock.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-WITH-LOCK 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-WITH-LOCK 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .

docs/man/borg.1

@@ -205,7 +205,7 @@ borg create repo::archive \-s \-\-progress path  # BAD
 .UNINDENT
 .UNINDENT
 .sp
-This is due to a problem in the argparse module: \fI\%http://bugs.python.org/issue15112\fP
+This is due to a problem in the argparse module: \fI\%https://bugs.python.org/issue15112\fP
 .SS Repository URLs
 .sp
 \fBLocal filesystem\fP (or locally mounted network filesystem):
@@ -441,6 +441,11 @@ the \fB\-\-rsh CMD\fP commandline option overrides the environment variable.
 When set, use the given path as borg executable on the remote (defaults to "borg" if unset).
 Using \fB\-\-remote\-path PATH\fP commandline option overrides the environment variable.
 .TP
+.B BORG_FILES_CACHE_SUFFIX
+When set to a value at least one character long, instructs borg to use a specifically named
+(based on the suffix) alternative files cache. This can be used to avoid loading and saving
+cache entries for backup sources other than the current sources.
+.TP
 .B BORG_FILES_CACHE_TTL
 When set to a numeric value, this determines the maximum "time to live" for the files cache
 entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
@@ -584,7 +589,9 @@ Up to 1000 files per directory (10000 for repositories initialized with Borg 1.0
 .IP \(bu 2
 mkdir(2) should be atomic, since it is used for locking
 .IP \(bu 2
-Hardlinks are needed for \fIborg_upgrade\fP \fB\-\-inplace\fP
+Hardlinks are needed for \fIborg_upgrade\fP (if \fB\-\-inplace\fP option is not used).
+Also hardlinks are used for more safe and secure file updating (e.g. of the repo
+config file), but the code tries to work also if hardlinks are not supported.
 .UNINDENT
 .SS Units
 .sp

docs/man/borgfs.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORGFS 1 "2020-10-06" "" "borg backup tool"
+.TH BORGFS 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .

docs/usage/create.rst.inc

@@ -12,85 +12,91 @@ borg create
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE``                                       | name of archive to create (must be also a valid directory name)                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``PATH``                                          | paths to archive                                                                                                                                  |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                        |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-n``, ``--dry-run``                             | do not create a backup archive                                                                                                                    |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-s``, ``--stats``                               | print statistics for the created archive                                                                                                          |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--filter STATUSCHARS``                          | only display items with the given status characters (see description)                                                                             |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--json``                                        | output stats as JSON. Implies ``--stats``.                                                                                                        |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--no-cache-sync``                               | experimental: do not synchronize the cache. Implies not using the files cache.                                                                    |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--no-files-cache``                              | do not load/update the file metadata cache used to detect unchanged files                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-name NAME``                             | use NAME in archive for stdin data (default: "stdin")                                                                                             |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                |
-    |                                                                                                                                                                                                                                                               |
-    | :ref:`common_options`                                                                                                                                                                                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-e PATTERN``, ``--exclude PATTERN``             | exclude paths matching PATTERN                                                                                                                    |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                              |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                             | experimental: include/exclude paths matching PATTERN                                                                                              |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                        |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--keep-exclude-tags``, ``--keep-tag-files``     | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                         |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-nodump``                              | exclude files flagged NODUMP                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Filesystem options**                                                                                                                                                                                                                                        |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-x``, ``--one-file-system``                     | stay in the same file system and do not store mount points of other file systems                                                                  |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--numeric-owner``                               | only store numeric user and group identifiers                                                                                                     |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noatime``                                     | do not store atime into archive                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noctime``                                     | do not store ctime into archive                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--nobirthtime``                                 | do not store birthtime (creation date) into archive                                                                                               |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--nobsdflags``                                  | do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive                                                                              |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--ignore-inode``                                | ignore inode data in the file metadata cache used to detect unchanged files.                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--files-cache MODE``                            | operate files cache in MODE. default: ctime,size,inode                                                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--read-special``                                | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files. |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive options**                                                                                                                                                                                                                                           |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--comment COMMENT``                             | add a comment text to the archive                                                                                                                 |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--timestamp TIMESTAMP``                         | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory.                |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095                           |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details.                                                  |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                                                         |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``ARCHIVE``                                       | name of archive to create (must be also a valid directory name)                                                                                      |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``PATH``                                          | paths to archive                                                                                                                                     |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                                                           |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-n``, ``--dry-run``                             | do not create a backup archive                                                                                                                       |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-s``, ``--stats``                               | print statistics for the created archive                                                                                                             |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                      |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--filter STATUSCHARS``                          | only display items with the given status characters (see description)                                                                                |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--json``                                        | output stats as JSON. Implies ``--stats``.                                                                                                           |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--no-cache-sync``                               | experimental: do not synchronize the cache. Implies not using the files cache.                                                                       |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--no-files-cache``                              | do not load/update the file metadata cache used to detect unchanged files                                                                            |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--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: 'root')                                                                                          |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--stdin-mode M``                                | set mode to M in archive for stdin data (default: 0660)                                                                                              |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                   |
+    |                                                                                                                                                                                                                                                                  |
+    | :ref:`common_options`                                                                                                                                                                                                                                            |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **Exclusion options**                                                                                                                                                                                                                                            |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-e PATTERN``, ``--exclude PATTERN``             | exclude paths matching PATTERN                                                                                                                       |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                                 |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--pattern PATTERN``                             | experimental: include/exclude paths matching PATTERN                                                                                                 |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                           |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                      |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                            |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--keep-exclude-tags``, ``--keep-tag-files``     | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                            |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--exclude-nodump``                              | exclude files flagged NODUMP                                                                                                                         |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **Filesystem options**                                                                                                                                                                                                                                           |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-x``, ``--one-file-system``                     | stay in the same file system and do not store mount points of other file systems.  This might behave different from your expectations, see the docs. |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--numeric-owner``                               | only store numeric user and group identifiers                                                                                                        |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--noatime``                                     | do not store atime into archive                                                                                                                      |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--noctime``                                     | do not store ctime into archive                                                                                                                      |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--nobirthtime``                                 | do not store birthtime (creation date) into archive                                                                                                  |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--nobsdflags``                                  | do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive                                                                                 |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--ignore-inode``                                | ignore inode data in the file metadata cache used to detect unchanged files.                                                                         |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--files-cache MODE``                            | operate files cache in MODE. default: ctime,size,inode                                                                                               |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--read-special``                                | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.    |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **Archive options**                                                                                                                                                                                                                                              |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--comment COMMENT``                             | add a comment text to the archive                                                                                                                    |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--timestamp TIMESTAMP``                         | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory.                   |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                               |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095                              |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details.                                                     |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -117,6 +123,9 @@ borg create
         --no-cache-sync    experimental: do not synchronize the cache. Implies not using the files cache.
         --no-files-cache    do not load/update the file metadata cache used to detect unchanged files
         --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: 'root')
+        --stdin-mode M    set mode to M in archive for stdin data (default: 0660)
 
 
     :ref:`common_options`
@@ -134,7 +143,7 @@ borg create
 
 
     Filesystem options
-        -x, --one-file-system     stay in the same file system and do not store mount points of other file systems
+        -x, --one-file-system     stay in the same file system and do not store mount points of other file systems.  This might behave different from your expectations, see the docs.
         --numeric-owner           only store numeric user and group identifiers
         --noatime                 do not store atime into archive
         --noctime                 do not store ctime into archive
@@ -227,6 +236,7 @@ the state after creation. Also, the ``--stats`` and ``--dry-run`` options are mu
 exclusive because the data is not actually compressed and deduplicated during a dry run.
 
 See the output of the "borg help patterns" command for more help on exclude patterns.
+
 See the output of the "borg help placeholders" command for more help on placeholders.
 
 .. man NOTES
@@ -245,6 +255,18 @@ only include the objects specified by ``--exclude-if-present`` in your backup,
 and not include any other contents of the containing folder, this can be enabled
 through using the ``--keep-exclude-tags`` option.
 
+The ``-x`` or ``--one-file-system`` option excludes directories, that are mountpoints (and everything in them).
+It detects mountpoints by comparing the device number from the output of ``stat()`` of the directory and its
+parent directory. Specifically, it excludes directories for which ``stat()`` reports a device number different
+from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
+with device number different from their parent, which the kernel does not consider a mountpoint and also the
+other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
+subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
+using ``--one-file-system``, one should make doubly sure that the backup works as intended especially when using
+btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
+installer.
+
+
 .. _list_item_flags:
 
 Item flags

docs/usage/help.rst.inc

@@ -133,8 +133,10 @@ Examples::
     /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
     $ borg create --exclude-from exclude.txt backup /
 
@@ -213,11 +215,11 @@ and ``--remote-path`` values support these placeholders:
 
 {now}
     The current local date and time, by default in ISO-8601 format.
-    You can also supply your own `format string <https://docs.python.org/3.4/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {now:%Y-%m-%d_%H:%M:%S}
+    You can also supply your own `format string <https://docs.python.org/3.7/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {now:%Y-%m-%d_%H:%M:%S}
 
 {utcnow}
     The current UTC date and time, by default in ISO-8601 format.
-    You can also supply your own `format string <https://docs.python.org/3.4/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {utcnow:%Y-%m-%d_%H:%M:%S}
+    You can also supply your own `format string <https://docs.python.org/3.7/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {utcnow:%Y-%m-%d_%H:%M:%S}
 
 {user}
     The user name (or UID, if no name is available) of the user running borg.

src/borg/archive.py

@@ -784,7 +784,7 @@ Utilization of max. archive size: {csize_max:.0%}
                     # generic handler
                     # EACCES: permission denied to set this specific xattr (this may happen related to security.* keys)
                     # EPERM: operation not permitted
-                    err_str = str(e)
+                    err_str = os.strerror(e.errno)
                 logger.warning(msg_format % err_str)
                 set_ec(EXIT_WARNING)
         # bsdflags include the immutable flag and need to be set last:

src/borg/testsuite/archiver.py

@@ -1309,16 +1309,15 @@ class ArchiverTestCase(ArchiverTestCaseBase):
             input_abspath = os.path.abspath('input/file')
             with patch.object(xattr, 'setxattr', patched_setxattr_E2BIG):
                 out = self.cmd('extract', self.repository_location + '::test', exit_code=EXIT_WARNING)
-                assert out == (input_abspath + ': Value or key of extended attribute user.attribute is too big for this '
-                                               'filesystem\n')
+                assert out == (input_abspath + ': when setting extended attribute user.attribute: too big for this filesystem\n')
             os.remove(input_abspath)
             with patch.object(xattr, 'setxattr', patched_setxattr_ENOTSUP):
                 out = self.cmd('extract', self.repository_location + '::test', exit_code=EXIT_WARNING)
-                assert out == (input_abspath + ': Extended attributes are not supported on this filesystem\n')
+                assert out == (input_abspath + ': when setting extended attribute user.attribute: xattrs not supported on this filesystem\n')
             os.remove(input_abspath)
             with patch.object(xattr, 'setxattr', patched_setxattr_EACCES):
                 out = self.cmd('extract', self.repository_location + '::test', exit_code=EXIT_WARNING)
-                assert out == (input_abspath + ': Permission denied when setting extended attribute user.attribute\n')
+                assert out == (input_abspath + ': when setting extended attribute user.attribute: Permission denied\n')
             assert os.path.isfile(input_abspath)
 
     def test_path_normalization(self):