Rewrite for quickstart

docs/quickstart.rst

@@ -21,22 +21,22 @@ 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 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).
+repositories contain data blocks and a manifest that tracks which blocks are in each
+archive. If some data hasn't changed between backups, Borg simply
+references an already uploaded data chunk (deduplication).
 
 .. _about_free_space:
 
 Important note about free space
 -------------------------------
 
-Before you start creating backups, please make sure that there is *always*
-a good amount of free space on the filesystem that has your backup repository
+Before you start creating backups, ensure that there is *always* plenty
+of free space on the destination filesystem that has your backup repository
 (and also on ~/.cache). A few GB should suffice for most hard-drive sized
 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
+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
 some space in Borg itself just to be safe by adjusting the ``additional_free_space``
 setting (a good starting point is ``2G``)::
 
@@ -47,7 +47,7 @@ can while aborting the current operation safely, which allows the user to free m
 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,
+If you do 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 archives.
 
 You can use some monitoring process or just include the free space information
@@ -71,16 +71,15 @@ Also helpful:
 Important note about permissions
 --------------------------------
 
-To avoid permissions issues (in your borg repository or borg cache), **always
+To avoid permission issues (in your borg repository or borg cache), **always
 access the repository using the same user account**.
 
 If you want to back up files of other users or the operating system, running
 borg as root likely will be required (otherwise you get `Permission denied`
 errors).
-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.
+If you only back up your own files, run it as your normal user (no root).
 
-For a local repository just always use the same user to invoke borg.
+For a local repository always use the same user to invoke borg.
 
 For a remote repository: always use e.g. ssh://borg@remote_host. You can use this
 from different local users, the remote user running borg and accessing the
@@ -116,7 +115,7 @@ common techniques to achieve this.
 
 - Shut down containers before backing up their storage volumes.
 
-For some systems Borg might work well enough without these
+For some systems, Borg might work well enough without these
 precautions.  If you are simply backing up the files on a system that
 isn't very active (e.g. in a typical home directory), Borg usually
 works well enough without further care for consistency.  Log files and
@@ -139,8 +138,8 @@ complete operating system) to a repository ``~/backup/main``  on a remote server
 Some files which aren't necessarily needed in this backup are excluded. See
 :ref:`borg_patterns` on how to add more exclude options.
 
-After the backup this script also uses the :ref:`borg_prune` subcommand to keep
-only a certain number of old archives and deletes the others.
+After the backup, this script also uses the :ref:`borg_prune` subcommand to keep
+a certain number of old archives and deletes the others.
 
 Finally, it uses the :ref:`borg_compact` subcommand to remove deleted objects
 from the segment files in the repository to free disk space.
@@ -152,8 +151,8 @@ by the root user, but not executable or readable by anyone else, i.e. root:root
 You can use this script as a starting point and modify it where it's necessary to fit
 your setup.
 
-Do not forget to test your created backups to make sure everything you need is being
-backed up and that the ``prune`` command is keeping and deleting the correct backups.
+Do not forget to test your created backups to make sure everything you need is
+backed up and that the ``prune`` command keeps and deletes the correct backups.
 
 ::
 
@@ -236,7 +235,7 @@ Pitfalls with shell variables and environment variables
 -------------------------------------------------------
 
 This applies to all environment variables you want Borg to see, not just
-``BORG_PASSPHRASE``. The short explanation is: always ``export`` your variable,
+``BORG_PASSPHRASE``. TL;DR: always ``export`` your variable,
 and use single quotes if you're unsure of the details of your shell's expansion
 behavior. E.g.::
 
@@ -267,26 +266,27 @@ Passphrase notes
 If you use encryption (or authentication), Borg will interactively ask you
 for a passphrase to encrypt/decrypt the keyfile / repokey.
 
-A passphrase should be a single line of text, a trailing linefeed will be
+A passphrase should be a single line of text. Any trailing linefeed will be
 stripped.
 
-For your own safety, you maybe want to avoid empty passphrases as well
-extremely long passphrase (much more than 256 bits of entropy).
+Do not use empty passphrases, as these can be trivially guessed, which does not
+leave any encrypted data secure. 
 
-Also avoid passphrases containing non-ASCII characters.
-Borg is technically able to process all unicode text, but you might get into
-trouble reproducing the same encoded utf-8 bytes or with keyboard layouts,
-so better just avoid non-ASCII stuff.
+Avoid passphrases containing non-ASCII characters.
+Borg can process any unicode text, but problems may arise at input due to text
+encoding or differing keyboard layouts, so best just avoid non-ASCII stuff.
 
-Alternatively, if you want to automate, you can supply the passphrase
-directly or indirectly using some environment variables.
+See: https://xkcd.com/936/
 
-You can directly give a passphrase::
+If you want to automate, you can supply the passphrase
+directly or indirectly with the use of environment variables.
+
+Supply a passphrase directly::
 
     # use this passphrase (use safe permissions on the script!):
     export BORG_PASSPHRASE='my super secret passphrase'
 
-Or ask an external program to supply the passphrase::
+Or delegate to an external program to supply the passphrase::
 
     # use the "pass" password manager to get the passphrase:
     export BORG_PASSCOMMAND='pass show backup'
@@ -424,22 +424,23 @@ be acceptable for backup usage.
 Restoring a backup
 ------------------
 
-Please note that we are only describing the most basic commands and options
-here - please refer to the command reference to see more.
+Please note that we describe only the most basic commands and options
+here. Refer to the command reference to see more.
+
+To restore, work **on the same machine as the same user**
+that was used to create the backups of the wanted files. Doing so
+avoids issues such as:
 
-For restoring, you usually want to work **on the same machine as the same user**
-that was also used to create the backups of the wanted files. Doing it like
-that avoids quite some issues:
+- confusion relating to paths
+- mapping of user/group names to user/group IDs
+- permissions
 
-- no confusion relating to paths
-- same mapping of user/group names to user/group IDs
-- no permission issues
-- you likely already have a working borg setup there,
+You likely already have a working borg setup there, including perhaps:
 
-  - maybe including a environment variable for the key passphrase (for encrypted repos),
-  - maybe including a keyfile for the repo (not needed for repokey mode),
-  - maybe including a ssh key for the repo server (not needed for locally mounted repos),
-  - maybe including a valid borg cache for that repo (quicker than cache rebuild).
+  - an environment variable for the key passphrase (for encrypted repos),
+  - a keyfile for the repo (not needed for repokey mode),
+  - a ssh key for the repo server (not needed for locally mounted repos),
+  - a valid borg cache for that repo (quicker than cache rebuild).
 
 The **user** might be:
 
@@ -461,12 +462,12 @@ The **key** can be located:
 - in the repository (**repokey** mode).
 
   Easy, this will usually "just work".
-- in the home directory of the user who did the backup (**keyfile** mode).
+- in the home directory of the user who made the backup (**keyfile** mode).
 
   This may cause a bit more effort:
 
   - if you have just lost that home directory and you first need to restore the
-    borg key (e.g. from the separate backup you have made of it or from another
+    borg key (e.g. from the separate backup you made of it or from another
     user or machine accessing the same repository).
   - if you first must find out the correct machine / user / home directory
     (where the borg client was run to make the backups).
@@ -483,19 +484,19 @@ There are **2 ways to restore** files from a borg backup repository:
 
 - **borg mount** - use this if:
 
-  - you don't precisely know what files you want to restore
+  - you don't know exactly which files you want to restore
   - you don't know which archive contains the files (in the state) you want
   - you need to look into files / directories before deciding what you want
   - you need a relatively low volume of data restored
-  - you don't care for restoring stuff that the FUSE mount is not implementing yet
+  - you don't care for restoring stuff that FUSE mount does not implement yet
     (like special fs flags, ACLs)
-  - you have a client with good resources (RAM, CPU, temp. disk space)
-  - you want to rather use some filemanager to restore (copy) files than borg
+  - you have a client with good resources (RAM, CPU, temporary disk space)
+  - you would rather use some filemanager to restore (copy) files than borg
     extract shell commands
 
 - **borg extract** - use this if:
 
-  - you precisely know what you want (repo, archive, path)
+  - you know precisely what you want (repo, archive, path)
   - you need a high volume of files restored (best speed)
   - you want a as-complete-as-it-gets reproduction of file metadata
     (like special fs flags, ACLs)