Merge pull request #8462 from ThomasWaldmann/doc-updates-1.4

Doc updates (1.4-maint)

docs/binaries/00_README.txt

@@ -0,0 +1,84 @@
+Binary BorgBackup builds
+========================
+
+The binaries are supposed to work on the specified platform without installing
+any dependencies.
+
+
+Download the correct files
+--------------------------
+
+amd64 / x86_64 architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+borg-linux-glibc236 Linux (built on Debian 12 "Bookworm" with glibc 2.36)
+borg-linux-glibc231 Linux (built on Debian 11 "Bullseye" with glibc 2.31)
+borg-linux-glibc228 Linux (built on Debian 10 "Buster" with glibc 2.28)
+                    Note: you can also try them on other Linuxes with other glibc
+                    versions - as long as the glibc is compatible, they will work.
+                    If it doesn't work, try a borg 1.2.x binary.
+
+borg-macos1012      macOS (built on macOS Sierra 10.12 with latest macFUSE from brew)
+                    To avoid signing issues download the file via command line OR
+                    remove the "quarantine" attribute after downloading:
+                    $ xattr -dr com.apple.quarantine borg-macos.tgz
+
+borg-freebsd13      FreeBSD (built on FreeBSD 13)
+borg-freebsd14      FreeBSD (built on FreeBSD 14)
+
+*.tgz               similar to above, but built as a directory with files,
+                    not as a single self-extracting binary. using the directory
+                    build is faster and doesn't need as much space in the temp
+                    directory as the one-file build.
+*.asc               GnuPG signatures for *
+
+
+Verifying your download
+-----------------------
+
+Please check the GPG signature to make sure you received the binary as I have
+built it.
+
+To check the GPG signature, download both the binary and the corresponding
+*.asc file and then (on the shell) type, e.g.:
+
+    gpg --recv-keys 9F88FB52FAF7B393
+    gpg --verify borg-freebsd.asc borg-freebsd
+
+The files are signed by:
+
+Thomas Waldmann <tw@waldmann-edv.de>
+GPG key fingerprint: 6D5B EF9A DD20 7580 5747 B70F 9F88 FB52 FAF7 B393
+
+My fingerprint is also in the footer of all my borgbackup mailing list posts.
+
+
+Installing
+----------
+
+It is suggested that you rename or symlink the binary to just "borg".
+If you need "borgfs", just also symlink it to the same binary, it will
+detect internally under which name it was invoked.
+
+On UNIX-like platforms, /usr/local/bin/ or ~/bin/ is a nice place for it,
+but you can invoke it from every place by giving a full path to it.
+
+Make sure the file is readable and executable (chmod +rx borg on UNIX-like
+platforms).
+
+
+Reporting issues
+----------------
+If you find issues, please open a ticket on our issue tracker:
+
+https://github.com/borgbackup/borg/issues/
+
+There, please give:
+- the version number (it is displayed if you invoke borg -V)
+- the sha256sum of the binary
+- a good description of what the issue is
+- a good description of how to reproduce your issue
+- a traceback with system info (if you have one)
+- your precise platform (CPU, 32/64bit?), OS, distribution, release
+- your python and (g)libc version
+

docs/usage/general/return-codes.rst.inc

@@ -18,3 +18,5 @@ Return code Meaning
 
 If you use ``--show-rc``, the return code is also logged at the indicated
 level as the last log entry.
+
+The modern exit codes (return codes, "rc") are documented there: :ref:`msgid`

src/borg/archiver.py

@@ -3083,10 +3083,25 @@ class Archiver:
 
         # borg mount
         mount_epilog = process_epilog("""
-        This command mounts an archive as a FUSE filesystem. This can be useful for
-        browsing an archive or restoring individual files. Unless the ``--foreground``
-        option is given the command will run in the background until the filesystem
-        is ``umounted``.
+        This command mounts a repository or an archive as a FUSE filesystem.
+        This can be useful for browsing or restoring individual files.
+
+        When restoring, take into account that the current FUSE implementation does
+        not support special fs flags and ACLs.
+
+        When mounting a repository, the top directories will be named like the
+        archives and the directory structure below these will be loaded on-demand from
+        the repository when entering these directories, so expect some delay.
+
+        Unless the ``--foreground`` option is given the command will run in the
+        background until the filesystem is ``umounted``.
+
+        Performance tips:
+
+        - when doing a "whole repository" mount:
+          do not enter archive dirs if not needed, this avoids on-demand loading.
+        - only mount a specific archive, not the whole repository.
+        - only mount specific paths in a specific archive, not the complete archive.
 
         The command ``borgfs`` provides a wrapper for ``borg mount``. This can also be
         used in fstab entries: