docs: fix typos and grammar

docs/book.rst

@@ -5,7 +5,7 @@
 Borg documentation
 ==================
 
-.. when you add an element here, do not forget to add it to index.rst
+.. When you add an element here, do not forget to add it to index.rst.
 .. Note: Some things are in appendices (see latex_appendices in conf.py)
 
 .. toctree::

docs/changes.rst

@@ -87,11 +87,11 @@ no matter what encryption mode they use, including "none"):
 
 5. Done. Manifest and archives are TAM authenticated now.
 
-Vulnerability time line:
+Vulnerability timeline:
 
 * 2023-06-13: Vulnerability discovered during code review by Thomas Waldmann
 * 2023-06-13...: Work on fixing the issue, upgrade procedure, docs.
-* 2023-06-30: CVE was assigned via Github CNA
+* 2023-06-30: CVE was assigned via GitHub CNA
 * 2023-06-30 .. 2023-08-29: Fixed issue, code review, docs, testing.
 * 2023-08-30: Released fixed version 1.2.5 (broken upgrade procedure for some repos)
 * 2023-08-31: Released fixed version 1.2.6 (fixes upgrade procedure)
@@ -230,7 +230,7 @@ This attack is mitigated by:
 
 We are not aware of others having discovered, disclosed or exploited this vulnerability.
 
-Vulnerability time line:
+Vulnerability timeline:
 
 * 2016-11-14: Vulnerability and fix discovered during review of cryptography by Marian Beermann (@enkore)
 * 2016-11-20: First patch

docs/deployment/automated-local.rst

@@ -14,8 +14,8 @@ systemd and udev.
 Overview
 --------
 
-An udev rule is created to trigger on the addition of block devices. The rule contains a tag
-that triggers systemd to start a oneshot service. The oneshot service executes a script in
+A udev rule is created to trigger on the addition of block devices. The rule contains a tag
+that causes systemd to start a oneshot service. The oneshot service executes a script in
 the standard systemd service environment, which automatically captures stdout/stderr and
 logs it to the journal.
 
@@ -36,9 +36,9 @@ Then, create ``/etc/backups/80-backup.rules`` with the following content (all on
 
     ACTION=="add", SUBSYSTEM=="block", ENV{ID_PART_TABLE_UUID}=="<the PTUUID you just noted>", TAG+="systemd", ENV{SYSTEMD_WANTS}+="automatic-backup.service"
 
-The "systemd" tag in conjunction with the SYSTEMD_WANTS environment variable has systemd
-launch the "automatic-backup" service, which we will create next, as the
-``/etc/backups/automatic-backup.service`` file:
+The "systemd" tag in conjunction with the SYSTEMD_WANTS environment variable causes systemd to
+launch the "automatic-backup" service, which we will create next, as the file
+``/etc/backups/automatic-backup.service``:
 
 .. code-block:: ini
 
@@ -65,13 +65,13 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
     # Script configuration
     #
 
-    # The backup partition is mounted there
+    # The backup partition is mounted here
     MOUNTPOINT=/mnt/backup
 
     # This is the location of the Borg repository
     TARGET=$MOUNTPOINT/borg-backups/backup.borg
 
-    # Archive name schema
+    # Archive name scheme
     DATE=$(date --iso-8601)-$(hostname)
 
     # This is the file that will later contain UUIDs of registered backup drives
@@ -93,7 +93,7 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
 
     echo "Disk $uuid is a backup disk"
     partition_path=/dev/disk/by-uuid/$uuid
-    # Mount file system if not already done. This assumes that if something is already
+    # Mount the file system if not already done. This assumes that if something is already
     # mounted at $MOUNTPOINT, it is the backup drive. It won't find the drive if
     # it was mounted somewhere else.
     findmnt $MOUNTPOINT >/dev/null || mount $partition_path $MOUNTPOINT
@@ -104,7 +104,7 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
     # Create backups
     #
 
-    # Options for borg create
+    # Options for Borg create
     BORG_OPTS="--stats --one-file-system --compression lz4 --checkpoint-interval 86400"
 
     # Set BORG_PASSPHRASE or BORG_PASSCOMMAND somewhere around here, using export,

docs/deployment/central-backup-server.rst

@@ -4,20 +4,20 @@
 Central repository server with Ansible or Salt
 ==============================================
 
-This section will give an example how to setup a borg repository server for multiple
+This section gives an example of how to set up a Borg repository server for multiple
 clients.
 
 Machines
 --------
 
 There are multiple machines used in this section and will further be named by their
-respective fully qualified domain name (fqdn).
+respective fully qualified domain name (FQDN).
 
 * The backup server: `backup01.srv.local`
 * The clients:
 
   - John Doe's desktop: `johndoe.clnt.local`
-  - Webserver 01: `web01.srv.local`
+  - Web server 01: `web01.srv.local`
   - Application server 01: `app01.srv.local`
 
 User and group
@@ -28,7 +28,7 @@ Recommended user and group with additional settings:
 
 * User: `backup`
 * Group: `backup`
-* Shell: `/bin/bash` (or other capable to run the `borg serve` command)
+* Shell: `/bin/bash` (or another capable of running the `borg serve` command)
 * Home: `/home/backup`
 
 Most clients shall initiate a backup from the root user to catch all
@@ -79,11 +79,11 @@ The options which are added to the key will perform the following:
 3. Restrict ssh and do not allow stuff which imposes a security risk
 
 Due to the ``cd`` command we use, the server automatically changes the current
-working directory. Then client doesn't need to have knowledge of the absolute
+working directory. The client doesn't need to have knowledge of the absolute
 or relative remote repository path and can directly access the repositories at
 ``ssh://<user>@<host>/./<repo>``.
 
-.. note:: The setup above ignores all client given commandline parameters
+.. note:: The setup above ignores all client-given command-line parameters
           which are normally appended to the `borg serve` command.
 
 Client
@@ -95,14 +95,14 @@ The client needs to initialize the `pictures` repository like this:
 
  borg init ssh://backup@backup01.srv.local/./pictures
 
-Or with the full path (should actually never be used, as only for demonstrational purposes).
-The server should automatically change the current working directory to the `<client fqdn>` folder.
+Or with the full path (should actually never be used, as only for demonstration purposes).
+The server should automatically change the current working directory to the `<client FQDN>` folder.
 
 ::
 
   borg init ssh://backup@backup01.srv.local/home/backup/repos/johndoe.clnt.local/pictures
 
-When `johndoe.clnt.local` tries to access a not restricted path the following error is raised.
+When `johndoe.clnt.local` tries to access an unrestricted path, the following error is raised.
 John Doe tries to backup into the Web 01 path:
 
 ::

docs/deployment/hosting-repositories.rst

@@ -5,11 +5,11 @@
 Hosting repositories
 ====================
 
-This sections shows how to securely provide repository storage for users.
+This section shows how to securely provide repository storage for users.
 Optionally, each user can have a storage quota.
 
 Repositories are accessed through SSH. Each user of the service should
-have her own login which is only able to access the user's files.
+have their own login which is only able to access the user's files.
 Technically it would be possible to have multiple users share one login,
 however, separating them is better. Separate logins increase isolation
 and are thus an additional layer of security and safety for both the

docs/deployment/image-backup.rst

@@ -8,9 +8,9 @@ Backing up disk images can still be efficient with Borg because its `deduplicati
 technique makes sure only the modified parts of the file are stored. Borg also has
 optional simple sparse file support for extract.
 
-It is of utmost importancy to pin down the disk you want to backup.
-You need to use the SERIAL for that. 
-Use: 
+It is of utmost importance to pin down the disk you want to back up.
+You need to use the SERIAL for that.
+Use:
 
 .. code-block:: bash
 
@@ -65,7 +65,7 @@ deduplicating. For backup, save the disk header and the contents of each partiti
         PARTNUM=$(echo $x | grep -Eo "[0-9]+$")
         ntfsclone -so - $x | borg create repo::hostname-part$PARTNUM -
     done
-    # to backup non-NTFS partitions as well:
+    # to back up non-NTFS partitions as well:
     echo "$PARTITIONS" | grep -v NTFS | cut -d' ' -f1 | while read x; do
         PARTNUM=$(echo $x | grep -Eo "[0-9]+$")
         borg create --read-special repo::hostname-part$PARTNUM $x

docs/deployment/non-root-user.rst

@@ -6,29 +6,29 @@
 Backing up using a non-root user
 ================================
 
-This section describes how to run borg as a non-root user and still be able to
-backup every file on the system.
+This section describes how to run Borg as a non-root user and still be able to
+back up every file on the system.
 
-Normally borg is run as the root user to bypass all filesystem permissions and
-be able to read all files. But in theory this also allows borg to modify or
-delete files on your system, in case of a bug for example.
+Normally Borg is run as the root user to bypass all filesystem permissions and
+be able to read all files. But in theory this also allows Borg to modify or
+delete files on your system, in case of a bug, for example.
 
-To eliminate this possibility, we can run borg as a non-root user and give it read-only
+To eliminate this possibility, we can run Borg as a non-root user and give it read-only
 permissions to all files on the system.
 
 
 Using Linux capabilities inside a systemd service
 =================================================
 
-One way to do so, is to use linux `capabilities
+One way to do so is to use Linux `capabilities
 <https://man7.org/linux/man-pages/man7/capabilities.7.html>`_ within a systemd
 service.
 
-Linux capabilities allow us to give parts of the privileges the root user has to
-a non-root user. This works on a per-thread level and does not give the permission
+Linux capabilities allow us to give some of the privileges that the root user has to
+a non-root user. This works on a per-thread level and does not grant these permissions
 to the non-root user as a whole.
 
-For this we need to run our backup script from a systemd service and use the `AmbientCapabilities
+For this, we need to run our backup script from a systemd service and use the `AmbientCapabilities
 <https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#AmbientCapabilities=>`_
 option added in systemd 229.
 
@@ -46,7 +46,7 @@ A very basic unit file would look like this:
 
     AmbientCapabilities=CAP_DAC_READ_SEARCH
 
-The ``CAP_DAC_READ_SEARCH`` capability gives borg read-only access to all files and directories on the system.
+The ``CAP_DAC_READ_SEARCH`` capability gives Borg read-only access to all files and directories on the system.
 
 This service can then be started manually using ``systemctl start``, a systemd timer or other methods.
 
@@ -57,7 +57,7 @@ When restoring files, the root user should be used. When using the non-root user
 change all files to be owned by the non-root user. Using borg mount will not allow the non-root user
 to access files that it would not have access to on the system itself.
 
-Other than that, the same restore process, that would be used when running the backup as root, can be used.
+Other than that, the same restore process that would be used when running the backup as root can be used.
 
 .. warning::
 

docs/deployment/pull-backup.rst

@@ -6,20 +6,20 @@
 Backing up in pull mode
 =======================
 
-Typically the borg client connects to a backup server using SSH as a transport
+Typically the Borg client connects to a backup server using SSH as a transport
 when initiating a backup. This is referred to as push mode.
 
-If you however require the backup server to initiate the connection or prefer
+If, however, you require the backup server to initiate the connection or prefer
 it to initiate the backup run, one of the following workarounds is required to
 allow such a pull mode setup.
 
-A common use case for pull mode is to backup a remote server to a local personal
+A common use case for pull mode is to back up a remote server to a local personal
 computer.
 
 SSHFS
 =====
 
-Assuming you have a pull backup system set up with borg, where a backup server
+Assuming you have a pull backup system set up with Borg, where a backup server
 pulls the data from the target via SSHFS. In this mode, the backup client's file
 system is mounted remotely on the backup server. Pull mode is even possible if
 the SSH connection must be established by the client via a remote tunnel. Other
@@ -54,7 +54,7 @@ completely in every aspect from such a backup.
 
 .. warning::
 
-    The chroot method was chosen to get the right user and group name-id
+    The chroot method was chosen to get the right user and group name-ID
     mappings, assuming they only come from files (/etc/passwd and group).
     This assumption might be wrong, e.g. if users/groups also come from
     ldap or other providers.
@@ -64,7 +64,7 @@ completely in every aspect from such a backup.
 Creating a backup
 -----------------
 
-Generally, in a pull backup situation there is no direct way for borg to know
+Generally, in a pull backup situation there is no direct way for Borg to know
 the client's original UID:GID name mapping of files, because Borg would use
 ``/etc/passwd`` and ``/etc/group`` of the backup server to map the names. To
 derive the right names, Borg needs to have access to the client's passwd and
@@ -72,7 +72,7 @@ group files and use them in the backup process.
 
 The solution to this problem is chrooting into an sshfs mounted directory. In
 this example the whole client root file system is mounted. We use the
-stand-alone BorgBackup executable and copy it into the mounted file system to
+standalone BorgBackup executable and copy it into the mounted file system to
 make Borg available after entering chroot; this can be skipped if Borg is
 already installed on the client.
 

docs/development.rst

@@ -52,7 +52,7 @@ Borg development happens on the ``master`` branch and uses GitHub pull
 requests (if you don't have GitHub or don't want to use it you can
 send smaller patches via the borgbackup mailing list to the maintainers).
 
-Stable releases are maintained on maintenance branches named ``x.y-maint``, eg.
+Stable releases are maintained on maintenance branches named ``x.y-maint``, e.g.
 the maintenance branch of the 1.4.x series is ``1.4-maint``.
 
 Most PRs should be filed against the ``master`` branch. Only if an
@@ -372,6 +372,7 @@ Checklist:
   ::
 
     scripts/sign-binaries 201912312359
+
 - Close the release milestone on GitHub.
 - `Update borgbackup.org
   <https://github.com/borgbackup/borgbackup.github.io/pull/53/files>`_ with the

docs/index.rst

@@ -6,7 +6,7 @@ Borg Documentation
 
 .. include:: ../README.rst
 
-.. when you add an element here, do not forget to add it to book.rst
+.. When you add an element here, do not forget to add it to book.rst.
 
 .. toctree::
    :maxdepth: 2

docs/installation.rst

@@ -105,7 +105,7 @@ Standalone Binary
 .. note:: Releases are signed with an OpenPGP key, see
           :ref:`security-contact` for more instructions.
 
-Borg x86-64 amd/intel compatible binaries (generated with `pyinstaller`_)
+Borg x86-64 AMD/Intel-compatible binaries (generated with `pyinstaller`_)
 are available on the releases_ page for the following platforms (for more
 details see the ``00_README.txt`` file there):
 

docs/internals.rst

@@ -4,7 +4,7 @@
 Internals
 =========
 
-The internals chapter describes and analyses most of the inner workings
+The internals chapter describes and analyzes most of the inner workings
 of Borg.
 
 Borg uses a low-level, key-value store, the :ref:`repository`, and
@@ -19,12 +19,12 @@ specified when the backup was performed.
 Deduplication is performed globally across all data in the repository
 (multiple backups and even multiple hosts), both on data and file
 metadata, using :ref:`chunks` created by the chunker using the
-Buzhash_ algorithm ("buzhash" chunker) or a simpler fixed blocksize
+Buzhash_ algorithm ("buzhash" chunker) or a simpler fixed block size
 algorithm ("fixed" chunker).
 
 To actually perform the repository-wide deduplication, a hash of each
 chunk is checked against the :ref:`chunks cache <cache>`, which is a
-hash-table of all chunks that already exist.
+hash table of all chunks that already exist.
 
 .. figure:: internals/structure.png
     :figwidth: 100%

docs/internals/data-structures.rst

@@ -21,29 +21,29 @@ Repository
 
 .. Some parts of this description were taken from the Repository docstring
 
-Borg stores its data in a `Repository`, which is a file system based
+Borg stores its data in a `Repository`, which is a filesystem-based
 transactional key-value store. Thus the repository does not know about
 the concept of archives or items.
 
 Each repository has the following file structure:
 
 README
-  simple text file telling that this is a Borg repository
+  Simple text file telling that this is a Borg repository
 
 config
-  repository configuration
+  Repository configuration
 
 data/
-  directory where the actual data is stored
+  Directory where the actual data is stored
 
 hints.%d
-  hints for repository compaction
+  Hints for repository compaction
 
 index.%d
-  repository index
+  Repository index
 
 lock.roster and lock.exclusive/*
-  used by the locking system to manage shared and exclusive locks
+  Used by the locking system to manage shared and exclusive locks
 
 Transactionality is achieved by using a log (aka journal) to record changes. The log is a series of numbered files
 called segments_. Each segment is a series of log entries. The segment number together with the offset of each

docs/internals/frontends.rst

@@ -10,18 +10,18 @@ Borg does not have a public API on the Python level. That does not keep you from
 but does mean that there are no release-to-release guarantees on what you might find in that package, not
 even for point releases (1.1.x), and there is no documentation beyond the code and the internals documents.
 
-Borg does on the other hand provide an API on a command-line level. In other words, a frontend should
-(for example) create a backup archive just invoke :ref:`borg_create`, give commandline parameters/options
-as needed and parse JSON output from borg.
+Borg does, on the other hand, provide an API on a command-line level. In other words, a frontend should
+(for example) create a backup archive by invoking :ref:`borg_create`, pass command-line parameters/options
+as needed, and parse JSON output from Borg.
 
-Important: JSON output is expected to be UTF-8, but currently borg depends on the locale being configured
-for that (must be a UTF-8 locale and *not* "C" or "ascii"), so that Python will choose to encode to UTF-8.
-The same applies to any inputs read by borg, they are expected to be UTF-8 encoded also.
+Important: JSON output is expected to be UTF-8, but currently Borg depends on the locale being configured
+for that (must be a UTF-8 locale and not "C" or "ASCII"), so that Python will choose to encode to UTF-8.
+The same applies to any inputs read by Borg; they are expected to be UTF-8 encoded also.
 
 We consider this a bug (see :issue:`2273`) and might fix it later, so borg will use UTF-8 independent of
 the locale.
 
-On POSIX systems, you can usually set environment vars to choose a UTF-8 locale:
+On POSIX systems, you can usually set environment variables to choose a UTF-8 locale:
 
 ::
 

docs/internals/security.rst

@@ -30,7 +30,7 @@ Under these circumstances Borg guarantees that the attacker cannot
 
 1. modify the data of any archive without the client detecting the change
 2. rename, remove or add an archive without the client detecting the change
-3. recover plain-text data
+3. recover plaintext data
 4. recover definite (heuristics based on access patterns are possible)
    structural information such as the object graph (which archives
    refer to what chunks)
@@ -144,10 +144,10 @@ Depending on the chosen mode (see :ref:`borg_init`) different primitives are use
 - The authentication primitive is either HMAC-SHA-256 or BLAKE2b-256
   in a keyed mode.
 
-  Both HMAC-SHA-256 and BLAKE2b have undergone extensive cryptanalysis  
+  Both HMAC-SHA-256 and BLAKE2b have undergone extensive cryptanalysis
   and have proven secure against known attacks. The known vulnerability
   of SHA-256 against length extension attacks does not apply to HMAC-SHA-256.
-  
+
   The authentication primitive should be chosen based upon SHA hardware support:
   all AMD Ryzen, Intel 10th+ generation mobile and Intel 11th+ generation
   desktop processors, Apple M1+ and most current ARM64 architectures support

docs/introduction.rst

@@ -1,8 +1,8 @@
 Introduction
 ============
 
-.. this shim is here to fix the structure in the PDF
-   rendering. without this stub, the elements in the toctree of
-   index.rst show up a level below the README file included
+.. This shim is here to fix the structure in the PDF
+   rendering. Without this stub, the elements in the toctree of
+   index.rst show up a level below the README file included there.
 
 .. include:: ../README.rst

docs/man_intro.rst

@@ -40,7 +40,7 @@ NOTES
 SEE ALSO
 --------
 
-`borg-common(1)` for common command line options
+`borg-common(1)` for common command-line options
 
 `borg-init(1)`,
 `borg-create(1)`, `borg-mount(1)`, `borg-extract(1)`,

docs/quickstart.rst

@@ -8,7 +8,7 @@ Quick Start
 This chapter will get you started with Borg and covers
 various use cases.
 
-A step by step example
+A step-by-step example
 ----------------------
 
 .. include:: quickstart_example.rst.inc
@@ -20,8 +20,8 @@ A *Borg archive* is the result of a single backup (``borg create``). An archive
 stores a snapshot of the data of the files "inside" it. One can later extract or
 mount an archive to restore from a backup.
 
-*Repositories* are filesystem directories acting as self-contained stores of archives.
-Repositories can be accessed locally via path or remotely via ssh. Under the hood,
+*Repositories* are file system directories acting as self-contained stores of archives.
+Repositories can be accessed locally via path or remotely via SSH. Under the hood,
 repositories contain data blocks and a manifest tracking which blocks are in each
 archive. If some data hasn't changed from one backup to another, Borg can simply
 reference an already uploaded data chunk (deduplication).
@@ -37,7 +37,7 @@ a good amount of free space on the filesystem that has your backup repository
 repositories. See also :ref:`cache-memory-usage`.
 
 Borg doesn't use space reserved for root on repository disks (even when run as root),
-on file systems which do not support this mechanism (e.g. XFS) we recommend to reserve
+on file systems which do not support this mechanism (e.g., XFS) we recommend reserving
 some space in Borg itself just to be safe by adjusting the ``additional_free_space``
 setting (a good starting point is ``2G``)::
 
@@ -49,7 +49,7 @@ by deleting/pruning archives. This mechanism is not bullet-proof in some
 circumstances [1]_.
 
 If you *really* run out of disk space, it can be hard or impossible to free space,
-because Borg needs free space to operate - even to delete backup
+because Borg needs free space to operate—even to delete backup
 archives.
 
 You can use some monitoring process or just include the free space information
@@ -58,38 +58,38 @@ in your backup log files (you check them regularly anyway, right?).
 Also helpful:
 
 - create a big file as a "space reserve", that you can delete to free space
-- if you use LVM: use a LV + a filesystem that you can resize later and have
+- if you use LVM: use an LV + a file system that you can resize later and have
   some unallocated PEs you can add to the LV.
 - consider using quotas
 - use `prune` and `compact` regularly
 
-.. [1] This failsafe can fail in these circumstances:
+.. [1] This fail-safe can fail in these circumstances:
 
-    - The underlying file system doesn't support statvfs(2), or returns incorrect
-      data, or the repository doesn't reside on a single file system
+    - The underlying file system does not support statvfs(2), or returns incorrect
+      data, or the repository does not reside on a single file system
     - Other tasks fill the disk simultaneously
     - Hard quotas (which may not be reflected in statvfs(2))
 
 Important note about permissions
 --------------------------------
 
-To avoid permissions issues (in your borg repository or borg cache), **always
+To avoid permissions issues (in your Borg repository or Borg cache), **always
 access the repository using the same user account**.
 
-If you want to backup files of other users or the operating system, running
-borg as root likely will be required (otherwise you'ld get `Permission denied`
+If you want to back up files of other users or the operating system, running
+Borg as root likely will be required (otherwise you'd get `Permission denied`
 errors).
-If you only back up your own files, you neither need nor want to run borg as
+If you only back up your own files, you neither need nor want to run Borg as
 root, just run it as your normal user.
 
-For a local repository just always use the same user to invoke borg.
+For a local repository just always use the same user to invoke Borg.
 
 For a remote repository: always use e.g. borg@remote_host. You can use this
-from different local users, the remote user running borg and accessing the
+from different local users; the remote user running Borg and accessing the
 repo will always be `borg`.
 
 If you need to access a local repository from different users, you can use the
-same method by using ssh to borg@localhost.
+same method by using SSH to borg@localhost.
 
 Important note about files changing during the backup process
 -------------------------------------------------------------

docs/support.rst

@@ -15,7 +15,7 @@ Security
 --------
 
 In case you discover a security issue, please use this contact for reporting it
-privately and please, if possible, use encrypted E-Mail:
+privately and please, if possible, use encrypted email:
 
 Thomas Waldmann <tw@waldmann-edv.de>
 
@@ -28,7 +28,7 @@ Verifying signed releases
 -------------------------
 
 `Releases <https://github.com/borgbackup/borg/releases>`_ are signed with the
-same GPG key and a .asc file is provided for each binary.
+same GPG key and an .asc file is provided for each binary.
 
 To verify a signature, the public key needs to be known to GPG. It can be
 imported into the local keystore from a keyserver with the fingerprint::
@@ -41,7 +41,7 @@ If GPG successfully imported the key, the output should include (among other thi
       gpg: Total number processed: 1
       ...
 
-To verify for example the signature of the borg-linux64 binary::
+To verify, for example, the signature of the borg-linux64 binary::
 
       gpg --verify borg-linux64.asc
 

docs/usage.rst

@@ -22,7 +22,7 @@ Usage
            window.location.pathname = replaced;
        }
    }
-   // Fixup anchored links from when usage.html contained all the commands
+   // Fix up anchored links from when usage.html contained all the commands
    else if(hash.startsWith("borg-key") || hash == "borg-change-passphrase") {
       window.location.hash = "";
       window.location.pathname = window.location.pathname.replace("usage.html", "usage/key.html");

docs/usage/compact.rst

@@ -7,7 +7,7 @@ Examples
     # compact segments and free repo disk space
     $ borg compact /path/to/repo
 
-    # same as above plus clean up 17byte commit-only segments
+    # same as above plus clean up 17-byte commit-only segments
     $ borg compact --cleanup-commits /path/to/repo
 
 

docs/usage/debug.rst

@@ -5,7 +5,7 @@ There is a ``borg debug`` command that has some subcommands which are all
 **not intended for normal use** and **potentially very dangerous** if used incorrectly.
 
 For example, ``borg debug put-obj`` and ``borg debug delete-obj`` will only do
-what their name suggests: put objects into repo / delete objects from repo.
+what their name suggests: put objects into the repository or delete objects from the repository.
 
 Please note:
 
@@ -31,4 +31,4 @@ The ``borg debug profile-convert`` command can be used to take a Borg profile an
 it to a profile file that is compatible with the Python tools.
 
 Additionally, if the filename specified for ``--debug-profile`` ends with ".pyprof" a
-Python compatible profile is generated. This is only intended for local use by developers.
+Python-compatible profile is generated. This is only intended for local use by developers.

docs/usage/delete.rst

@@ -15,7 +15,7 @@ Examples
     # delete all archives whose names contain "-2012-"
     $ borg delete --glob-archives '*-2012-*' /path/to/repo
 
-    # see what would be deleted if delete was run without --dry-run
+    # see what would be deleted if delete were run without --dry-run
     $ borg delete --list --dry-run -a '*-May-*' /path/to/repo
 
     # delete the whole repository and the related local cache:

docs/usage/general.rst

@@ -32,16 +32,16 @@ All Borg commands share these options:
 .. include:: common-options.rst.inc
 
 Option ``--bypass-lock`` allows you to access the repository while bypassing
-borg's locking mechanism. This is necessary if your repository is on a read-only
+Borg's locking mechanism. This is necessary if your repository is on a read-only
 storage where you don't have write permissions or capabilities and therefore
-cannot create a lock. Examples are repositories stored on a Bluray disc or a
-read-only network storage. Avoid this option if you are able to use locks as
+cannot create a lock. Examples are repositories stored on a Blu-ray disc or a
+read-only network storage. Avoid this option if you are able to use locks, as
 that is the safer way; see the warning below.
 
 .. warning::
 
-    If you do use ``--bypass-lock``, you are responsible to ensure that no other
-    borg instances have write access to the repository. Otherwise, you might
+    If you do use ``--bypass-lock``, you are responsible for ensuring that no other
+    Borg instances have write access to the repository. Otherwise, you might
     experience errors and read broken data if changes to that repository are
     being made at the same time.
 

docs/usage/mount.rst

@@ -59,11 +59,11 @@ borgfs
     $ mount /tmp/myrepo
     $ mount /tmp/myarchive
     $ ls /tmp/myrepo
-    root-2016-02-01 root-2016-02-2015
+    root-2016-02-01 root-2016-02-15
     $ ls /tmp/myarchive
     bin  boot  etc	home  lib  lib64  lost+found  media  mnt  opt  root  sbin  srv  tmp  usr  var
 
-.. Note::
+.. note::
 
     ``borgfs`` will be automatically provided if you used a distribution
     package or ``pip`` to install Borg. Users of the standalone binary will have

docs/usage/notes.rst

@@ -1,7 +1,7 @@
 Additional Notes
 ----------------
 
-Here are misc. notes about topics that are maybe not covered in enough detail in the usage section.
+Here are miscellaneous notes about topics that might not be covered in enough detail in the usage section.
 
 .. _chunker-params:
 
@@ -24,14 +24,14 @@ deduplication and creates a much smaller amount of chunks and thus uses less
 resources. This is good for relatively big data volumes and if the machine has
 a relatively low amount of free RAM and disk space.
 
-``--chunker-params=fixed,4194304`` results in fixed 4MiB sized block
+``--chunker-params=fixed,4194304`` results in fixed 4 MiB sized block
 deduplication and is more efficient than the previous example when used for
-for block devices (like disks, partitions, LVM LVs) or raw disk image files.
+block devices (like disks, partitions, LVM LVs) or raw disk image files.
 
-``--chunker-params=fixed,4096,512`` results in fixed 4kiB sized blocks,
-but the first header block will only be 512B long. This might be useful to
-dedup files with 1 header + N fixed size data blocks. Be careful to not
-produce a too big amount of chunks (like using small block size for huge
+``--chunker-params=fixed,4096,512`` results in fixed 4 KiB sized blocks,
+but the first header block will only be 512 B long. This might be useful to
+deduplicate files with 1 header + N fixed-size data blocks. Be careful not to
+produce too many chunks (such as using a small block size for huge
 files).
 
 If you already have made some archives in a repository and you then change
@@ -46,7 +46,7 @@ Usually, it is not that bad though:
 - usually most files are not touched, so it will just re-use the old chunks
   it already has in the repo
 - files smaller than the (both old and new) minimum chunksize result in only
-  one chunk anyway, so the resulting chunks are same and deduplication will apply
+  one chunk anyway, so the resulting chunks are the same and deduplication will apply
 
 If you switch chunker params to save resources for an existing repo that
 already has some backup archives, you will see an increasing effect over time,
@@ -85,17 +85,17 @@ use this option also for speeding up operations.
 ~~~~~~~~~~~
 
 borg uses a safe default umask of 077 (that means the files borg creates have
-only permissions for owner, but no permissions for group and others) - so there
+only permissions for the owner, but no permissions for group and others) - so there
 should rarely be a need to change the default behaviour.
 
 This option only affects the process to which it is given. Thus, when you run
 borg in client/server mode and you want to change the behaviour on the server
-side, you need to use ``borg serve --umask=XXX ...`` as a ssh forced command
+side, you need to use ``borg serve --umask=XXX ...`` as an SSH forced command
 in ``authorized_keys``. The ``--umask`` value given on the client side is
 **not** transferred to the server side.
 
 Also, if you choose to use the ``--umask`` option, always be consistent and use
-the same umask value so you do not create a mixup of permissions in a borg
+the same umask value so you do not create a mix-up of permissions in a borg
 repository or with other files borg creates.
 
 ``--read-special``
@@ -120,13 +120,13 @@ You need to be careful about what you include when using ``--read-special``,
 e.g. if you include ``/dev/zero``, your backup will never terminate.
 
 Restoring such files' content is currently only supported one at a time via
-``--stdout`` option (and you have to redirect stdout to where ever it shall go,
+``--stdout`` option (and you have to redirect stdout to wherever it shall go,
 maybe directly into an existing device file of your choice or indirectly via
 ``dd``).
 
 To some extent, mounting a backup archive with the backups of special files
 via ``borg mount`` and then loop-mounting the image files from inside the mount
-point will work. If you plan to access a lot of data in there, it likely will
+point will work. If you plan to access a lot of data in there, it will likely
 scale and perform better if you do not work via the FUSE mount.
 
 Example
@@ -211,7 +211,7 @@ but borg will also reject to delete the repository completely).
 If ``borg compact`` command is used on a repo in append-only mode, there
 will be no warning or error, but no compaction will happen.
 
-append-only is useful for scenarios where a backup client machine backups
+Append-only is useful for scenarios where a backup client machine backs up
 remotely to a backup server using ``borg serve``, since a hacked client machine
 cannot delete backups on the server permanently.
 
@@ -233,7 +233,7 @@ in ``.ssh/authorized_keys``:
 
 ::
 
-    command="borg serve --append-only ..." ssh-rsa <key used for not-always-trustable backup clients>
+    command="borg serve --append-only ..." ssh-rsa <key used for not-always-trustworthy backup clients>
     command="borg serve ..." ssh-rsa <key used for backup management>
 
 Running ``borg init`` via a ``borg serve --append-only`` server will *not* create
@@ -255,7 +255,7 @@ mode. A transaction log in this situation might look like this:
     transaction 13, UTC time 2016-03-31T15:55:55.472564
 
 From your security logs you conclude the attacker gained access at 15:54:00 and all
-the backups where deleted or replaced by compromised backups. From the log you know
+the backups were deleted or replaced by compromised backups. From the log you know
 that transactions 11 and later are compromised. Note that the transaction ID is the
 name of the *last* file in the transaction. For example, transaction 11 spans files 6
 to 11.
@@ -320,7 +320,7 @@ repository. Make sure that backup client machines only get to access the reposit
 ``borg serve``.
 
 Ensure that no remote access is possible if the repository is temporarily set to normal mode
-for e.g. regular pruning.
+for example, regular pruning.
 
 Further protections can be implemented, but are outside of Borg's scope. For example,
 file system snapshots or wrapping ``borg serve`` to set special permissions or ACLs on

docs/usage/prune.rst

@@ -3,38 +3,38 @@
 Examples
 ~~~~~~~~
 
-Be careful, prune is a potentially dangerous command, it will remove backup
+Be careful: prune is a potentially dangerous command; it will remove backup
 archives.
 
-The default of prune is to apply to **all archives in the repository** unless
-you restrict its operation to a subset of the archives using ``--glob-archives``.
-When using ``--glob-archives``, be careful to choose a good matching pattern -
-e.g. do not use "foo*" if you do not also want to match "foobar".
+By default, prune applies to **all archives in the repository** unless you
+restrict its operation to a subset of the archives using ``--glob-archives``.
+When using ``--glob-archives``, be careful to choose a good matching pattern —
+for example, do not use "foo*" if you do not also want to match "foobar".
 
 It is strongly recommended to always run ``prune -v --list --dry-run ...``
-first so you will see what it would do without it actually doing anything.
+first, so you can see what it would do without actually doing anything.
 
 ::
 
-    # Keep 7 end of day and 4 additional end of week archives.
+    # Keep 7 end-of-day and 4 additional end-of-week archives.
     # Do a dry-run without actually deleting anything.
     $ borg prune -v --list --dry-run --keep-daily=7 --keep-weekly=4 /path/to/repo
 
     # Same as above but only apply to archive names starting with the hostname
     # of the machine followed by a "-" character:
     $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --glob-archives='{hostname}-*' /path/to/repo
-    # actually free disk space:
+    # Actually free disk space:
     $ borg compact /path/to/repo
 
-    # Keep 7 end of day, 4 additional end of week archives,
-    # and an end of month archive for every month:
+    # Keep 7 end-of-day, 4 additional end-of-week archives,
+    # and an end-of-month archive for every month:
     $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --keep-monthly=-1 /path/to/repo
 
-    # Keep all backups in the last 10 days, 4 additional end of week archives,
-    # and an end of month archive for every month:
+    # Keep all backups in the last 10 days, 4 additional end-of-week archives,
+    # and an end-of-month archive for every month:
     $ borg prune -v --list --keep-within=10d --keep-weekly=4 --keep-monthly=-1 /path/to/repo
 
-There is also a visualized prune example in ``docs/misc/prune-example.txt``:
+There is also a visual example of pruning in ``docs/misc/prune-example.txt``:
 
 .. highlight:: none
 .. include:: ../misc/prune-example.txt

docs/usage/recreate.rst

@@ -4,22 +4,22 @@ Examples
 ~~~~~~~~
 ::
 
-    # Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives.
+    # Make old (Attic/Borg 0.xx) archives deduplicate with Borg 1.x archives.
     # Archives created with Borg 1.1+ and the default chunker params are skipped
     # (archive ID stays the same).
     $ borg recreate /mnt/backup --chunker-params default --progress
 
-    # Create a backup with little but fast compression
+    # Create a backup with low but fast compression.
     $ borg create /mnt/backup::archive /some/files --compression lz4
-    # Then compress it - this might take longer, but the backup has already completed,
+    # Then compress it — this might take longer, but the backup has already completed,
     # so no inconsistencies from a long-running backup job.
     $ borg recreate /mnt/backup::archive --recompress --compression zlib,9
 
     # Remove unwanted files from all archives in a repository.
-    # Note the relative path for the --exclude option - archives only contain relative paths.
+    # Note the relative path for the --exclude option — archives only contain relative paths.
     $ borg recreate /mnt/backup --exclude home/icke/Pictures/drunk_photos
 
-    # Change archive comment
+    # Change the archive comment.
     $ borg create --comment "This is a comment" /mnt/backup::archivename ~
     $ borg info /mnt/backup::archivename
     Name: archivename

docs/usage/serve.rst

@@ -3,7 +3,7 @@
 Examples
 ~~~~~~~~
 
-``borg serve`` has special support for ssh forced commands (see ``authorized_keys``
+``borg serve`` has special support for SSH forced commands (see ``authorized_keys``
 example below): if the environment variable SSH_ORIGINAL_COMMAND is set it will
 ignore some options given on the command line and use the values from the
 variable instead. This only applies to a carefully controlled allowlist of safe
@@ -15,31 +15,31 @@ options. This list currently contains:
   giving up and aborting the operation when another process is holding a lock.
 
 Environment variables (such as BORG_XXX) contained in the original
-command sent by the client are *not* interpreted, but ignored. If BORG_XXX environment
-variables should be set on the ``borg serve`` side, then these must be set in system-specific
+command sent by the client are *not* interpreted; they are ignored. If BORG_XXX environment
+variables need to be set on the ``borg serve`` side, then these must be set in system-specific
 locations like ``/etc/environment`` or in the forced command itself (example below).
 
 ::
 
-    # Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
+    # Allow an SSH key pair to only run borg, and only have access to /path/to/repo.
     # Use key options to disable unneeded and potentially dangerous SSH functionality.
-    # This will help to secure an automated remote backup system.
+    # This helps secure an automated remote backup system.
     $ cat ~/.ssh/authorized_keys
     command="borg serve --restrict-to-path /path/to/repo",restrict ssh-rsa AAAAB3[...]
 
-    # Set a BORG_XXX environment variable on the "borg serve" side
+    # Set a BORG_XXX environment variable on the ``borg serve`` side.
     $ cat ~/.ssh/authorized_keys
     command="BORG_XXX=value borg serve [...]",restrict ssh-rsa [...]
 
 .. note::
-    The examples above use the ``restrict`` directive and assume a POSIX
-    compliant shell set as the user's login shell.
-    This does automatically block potential dangerous ssh features, even when
+    The examples above use the ``restrict`` directive and assume a POSIX-compliant
+    shell set as the user's login shell.
+    This automatically blocks potentially dangerous SSH features, even when
     they are added in a future update. Thus, this option should be preferred.
 
-    If you're using openssh-server < 7.2, however, you have to explicitly specify
-    the ssh features to restrict and cannot simply use the restrict option as it
-    has been introduced in v7.2. We recommend to use
+    If you're using OpenSSH server < 7.2, however, you have to explicitly specify
+    the SSH features to restrict and cannot simply use the ``restrict`` option as it
+    was introduced in v7.2. We recommend using
     ``no-port-forwarding,no-X11-forwarding,no-pty,no-agent-forwarding,no-user-rc``
     in this case.
 
@@ -60,9 +60,9 @@ Either in the client side's ``~/.ssh/config`` file, or in the client's ``/etc/ss
             ServerAliveInterval 10
             ServerAliveCountMax 30
 
-Replacing ``backupserver`` with the hostname, FQDN or IP address of the borg server.
+Replace ``backupserver`` with the hostname, FQDN, or IP address of the Borg server.
 
-This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the ssh client process will be terminated, causing the borg process to terminate gracefully.
+This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the SSH client process will be terminated, causing the Borg process to terminate gracefully.
 
 On the server side's ``sshd`` configuration file (typically ``/etc/ssh/sshd_config``):
 ::
@@ -70,8 +70,8 @@ On the server side's ``sshd`` configuration file (typically ``/etc/ssh/sshd_conf
     ClientAliveInterval 10
     ClientAliveCountMax 30
 
-This will cause the server to send a keep alive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server's sshd process will be terminated, causing the ``borg serve`` process to terminate gracefully and release the lock on the repository.
+This will cause the server to send a keepalive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server's sshd process will be terminated, causing the ``borg serve`` process to terminate gracefully and release the lock on the repository.
 
-If you then run borg commands with ``--lock-wait 600``, this gives sufficient time for the borg serve processes to terminate after the SSH connection is torn down after the 300 second wait for the keepalives to fail.
+If you then run Borg commands with ``--lock-wait 600``, this gives sufficient time for the ``borg serve`` processes to terminate after the SSH connection is torn down following the 300-second wait for the keepalives to fail.
 
 You may, of course, modify the timeout values demonstrated above to values that suit your environment and use case.

docs/usage/tar.rst

@@ -6,18 +6,18 @@ Examples
 ~~~~~~~~
 ::
 
-    # export as uncompressed tar
+    # Export as an uncompressed tar.
     $ borg export-tar /path/to/repo::Monday Monday.tar
 
-    # exclude some types, compress using gzip
+    # Exclude some types; compress using gzip.
     $ borg export-tar /path/to/repo::Monday Monday.tar.gz --exclude '*.so'
 
-    # use higher compression level with gzip
+    # Use a higher compression level with gzip.
     $ borg export-tar --tar-filter="gzip -9" testrepo::linux Monday.tar.gz
 
-    # export a tar, but instead of storing it on disk,
+    # Export a tar, but instead of storing it on disk,
     # upload it to a remote site using curl.
     $ borg export-tar /path/to/repo::Monday - | curl --data-binary @- https://somewhere/to/POST
 
-    # remote extraction via "tarpipe"
+    # Remote extraction via "tarpipe".
     $ borg export-tar /path/to/repo::Monday - | ssh somewhere "cd extracted; tar x"

docs/usage/upgrade.rst

@@ -16,14 +16,14 @@ Examples
 
 .. _borg_key_migrate-to-repokey:
 
-Upgrading a passphrase encrypted attic repo
+Upgrading a passphrase-encrypted Attic repo
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-attic offered a "passphrase" encryption mode, but this was removed in borg 1.0
+Attic offered a "passphrase" encryption mode, but this was removed in Borg 1.0
 and replaced by the "repokey" mode (which stores the passphrase-protected
-encryption key into the repository config).
+encryption key in the repository config).
 
-Thus, to upgrade a "passphrase" attic repo to a "repokey" borg repo, 2 steps
+Thus, to upgrade a "passphrase" Attic repo to a "repokey" Borg repo, two steps
 are needed, in this order:
 
 - borg upgrade repo