From 4c9a07e9c8cd117c7354edf6c4914c8c078dbd20 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Fri, 15 May 2026 23:10:01 +0200 Subject: [PATCH] doc: stick to second-persion "you" in user docs Replace usages of `we`, `one` and "it is possible" with the mainly used `you`. --- doc/010_introduction.rst | 4 ++-- doc/020_installation.rst | 4 ++-- doc/030_preparing_a_new_repo.rst | 4 ++-- doc/040_backup.rst | 8 ++++---- doc/045_working_with_repos.rst | 10 +++++----- doc/050_restore.rst | 8 ++++---- doc/060_forget.rst | 6 +++--- doc/075_scripting.rst | 2 +- doc/077_troubleshooting.rst | 4 ++-- doc/080_examples.rst | 16 ++++++++-------- doc/090_participating.rst | 2 +- doc/faq.rst | 2 +- doc/manual_rest.rst | 18 +++++++++--------- 13 files changed, 44 insertions(+), 44 deletions(-) diff --git a/doc/010_introduction.rst b/doc/010_introduction.rst index bdfc9b19e..a24824e11 100644 --- a/doc/010_introduction.rst +++ b/doc/010_introduction.rst @@ -14,8 +14,8 @@ Introduction ############ -Restic is a fast and secure backup program. In the following sections, we will -present typical workflows, starting with installing, preparing a new +Restic is a fast and secure backup program. The following sections present +typical workflows, starting with installing, preparing a new repository, and making the first backup. Quickstart Guide diff --git a/doc/020_installation.rst b/doc/020_installation.rst index 00268e188..9735bec13 100644 --- a/doc/020_installation.rst +++ b/doc/020_installation.rst @@ -267,8 +267,8 @@ master branch. Docker Container **************** -We're maintaining a bare docker container with just a few files and the restic -binary, you can get it with `docker pull` like this: +A minimal Docker image with just a few files and the restic +binary is available; you can get it with `docker pull` like this: .. code-block:: console diff --git a/doc/030_preparing_a_new_repo.rst b/doc/030_preparing_a_new_repo.rst index 2d457494a..6afb069e6 100644 --- a/doc/030_preparing_a_new_repo.rst +++ b/doc/030_preparing_a_new_repo.rst @@ -22,8 +22,8 @@ To access the repository, a password (also called a key) must be specified. A repository can hold multiple keys that can all be used to access the repository. This chapter explains how to create ("init") such a repository. The repository -can be stored locally, or on some remote server or service. We'll first cover -using a local repository; the remaining sections of this chapter cover all the +can be stored locally, or on some remote server or service. This chapter first +covers using a local repository; the remaining sections cover all the other options. You can skip to the next chapter once you've read the relevant section here. diff --git a/doc/040_backup.rst b/doc/040_backup.rst index 578913355..a8eed4dff 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -14,7 +14,7 @@ Backing up ########## -Now we're ready to backup some data. The contents of a directory at a +You can now back up some data. The contents of a directory at a specific point in time is called a "snapshot" in restic. Run the following command and enter the repository password you chose above again: @@ -41,9 +41,9 @@ As you can see, restic created a backup of the directory and was pretty fast! The specific snapshot just created is identified by a sequence of hexadecimal characters, ``40dc1520`` in this case. -You can see that restic tells us it processed 1.720 GiB of data, this is the +You can see that restic processed 1.720 GiB of data; this is the size of the files and directories in ``~/work`` on the local file system. It -also tells us that only 1.200 GiB was added to the repository. This means that +also reports that only 1.200 GiB was added to the repository. This means that some of the data was duplicate and restic was able to efficiently reduce it. The data compression also managed to compress the data down to 1.103 GiB. @@ -355,7 +355,7 @@ the exclude options are: Please see ``restic help backup`` for more specific information about each exclude option. -Let's say we have a file called ``excludes.txt`` with the following content: +Suppose you have a file called ``excludes.txt`` with the following content: :: diff --git a/doc/045_working_with_repos.rst b/doc/045_working_with_repos.rst index 90e8d3100..db9108b2f 100644 --- a/doc/045_working_with_repos.rst +++ b/doc/045_working_with_repos.rst @@ -253,7 +253,7 @@ can also be set as environment variables ``$RESTIC_FROM_REPOSITORY`` or the password can be read from a file ``--from-password-file`` or from a command ``--from-password-command``. Alternatively the environment variables ``$RESTIC_FROM_PASSWORD_COMMAND`` and -``$RESTIC_FROM_PASSWORD_FILE`` can be used. It is also possible to directly +``$RESTIC_FROM_PASSWORD_FILE`` can be used. You can also directly pass the password via ``$RESTIC_FROM_PASSWORD``. The key which should be used for decryption can be selected by passing its ID via the flag ``--from-key-hint`` or the environment variable ``$RESTIC_FROM_KEY_HINT``. @@ -279,7 +279,7 @@ and/or a comma-separated tag list: $ restic -r /srv/restic-repo-copy copy --from-repo /srv/restic-repo --host luigi --path /srv --tag foo,bar -It is also possible to explicitly specify the list of snapshots to copy, in +You can also explicitly specify the list of snapshots to copy, in which case only these instead of all snapshots will be copied: .. code-block:: console @@ -300,7 +300,7 @@ identical chunks and therefore deduplication also works for snapshots copied bet these repositories. The chunker parameters are generated once when creating a new (destination) repository. -That is for a copy destination repository we have to instruct restic to initialize it +For a copy destination repository, you must instruct restic to initialize it using the same chunker parameters as the source repository: .. code-block:: console @@ -315,7 +315,7 @@ Removing files from snapshots Snapshots sometimes turn out to include more files than intended. Instead of removing the snapshots entirely and running the corresponding backup commands -again (which is not always practical after the fact) it is possible to remove +again (which is not always practical after the fact), you can remove the unwanted files from affected snapshots by rewriting them using the ``rewrite`` command: @@ -352,7 +352,7 @@ to those files that you are really interested in. An example could be all pictur from a snapshot: ``restic rewrite -r ... --iinclude "*.jpg" --iinclude "*.jpeg" --iinclude "*.png"``. -It is possible to rewrite only a subset of snapshots by filtering them the same +You can rewrite only a subset of snapshots by filtering them the same way as for the ``copy`` command, see :ref:`copy-filtering-snapshots`. The option ``--snapshot-summary`` can be used to attach summary data to existing diff --git a/doc/050_restore.rst b/doc/050_restore.rst index 3d72abc6e..b9efe4044 100644 --- a/doc/050_restore.rst +++ b/doc/050_restore.rst @@ -153,7 +153,7 @@ options will be deleted. For example, the command would only delete files within ``/tmp/restore/foo``. When using ``--target`` and ``--delete`` then the ``restore`` command only works if either an ``--include`` -or ``--exclude`` option is also specified. This ensures that one cannot accidentally delete +or ``--exclude`` option is also specified. This ensures that you cannot accidentally delete the whole system. The ``--delete`` option also allows overwriting a non-empty directory if the snapshot contains a @@ -247,7 +247,7 @@ snapshots in a repository: ---------------------------------------------------------------------- Here, restic would resolve ``latest`` to the snapshot ``1541acae``, which does -not contain the file we'd like to print at all (``production.sql``). In this +not contain the file you want to print at all (``production.sql``). In this case, you can pass restic the snapshot ID of the snapshot you like to restore: .. code-block:: console @@ -273,7 +273,7 @@ See :ref:`absolute-and-relative-paths` for details. Use ``ls`` to determine the /other /other/work -It is also possible to ``dump`` the contents of a whole folder structure to +You can also ``dump`` the contents of a whole folder structure to stdout. To retain the information about the files and folders restic will output the contents in the tar (default) or zip format: @@ -292,7 +292,7 @@ To include the folder content at the root of the archive, you can use the `` restore.tar -It is also possible to ``dump`` the contents of a selected snapshot and folder +You can also ``dump`` the contents of a selected snapshot and folder structure to a file using the ``--target`` flag. .. code-block:: console diff --git a/doc/060_forget.rst b/doc/060_forget.rst index 71d7ed0fa..492ae09dc 100644 --- a/doc/060_forget.rst +++ b/doc/060_forget.rst @@ -395,7 +395,7 @@ removes all snapshots with tag ``example``. Security considerations in append-only mode =========================================== -.. note:: TL;DR: With append-only repositories, one should specifically use the +.. note:: TL;DR: With append-only repositories, you should specifically use the ``--keep-within`` option of the ``forget`` command when removing snapshots. To prevent a compromised backup client from deleting its backups (for example @@ -404,7 +404,7 @@ repository in a so-called append-only mode. This means that the repository is served in such a way that it can only be written to and read from, while delete and overwrite operations are denied. Restic's `rest-server`_ features an append-only mode, but few other standard backends do. To support append-only -with such backends, one can use `rclone`_ as a complement in between the backup +with such backends, you can use `rclone`_ as a complement in between the backup client and the backend service. .. _rest-server: https://github.com/restic/rest-server/ @@ -449,7 +449,7 @@ all legitimate snapshots. Customize pruning ***************** -To understand the custom options, we first explain how the pruning process works: +To understand the custom options, this section first explains how the pruning process works: 1. All snapshots and directories within snapshots are scanned to determine which data is still in use. diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index 3060c577c..2be12b15a 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -184,7 +184,7 @@ JSON output of most restic commands is documented here. feel free to submit a pull request! .. warning:: - We try to keep the JSON output backwards compatible. However, new message types + The JSON output is intended to remain backwards compatible. However, new message types or fields may be added at any time. Similarly, enum-like fields for which a fixed list of allowed values is documented may be extended at any time. diff --git a/doc/077_troubleshooting.rst b/doc/077_troubleshooting.rst index e7d0b609a..bc34ac8b7 100644 --- a/doc/077_troubleshooting.rst +++ b/doc/077_troubleshooting.rst @@ -194,8 +194,8 @@ to run ``restic forget 6979421e``. 6. Check the repository again ***************************** -Phew, we're almost done now. To make sure that the repository has been successfully -repaired please run ``check`` again. +As a final step, run ``check`` again to make sure that the repository has been successfully +repaired. .. code-block:: console diff --git a/doc/080_examples.rst b/doc/080_examples.rst index 9ca785d52..ea622bee3 100644 --- a/doc/080_examples.rst +++ b/doc/080_examples.rst @@ -291,13 +291,13 @@ least possible privileges. Fortunately, Linux has functionality to divide root's power into single separate *capabilities*. The *CAP_DAC_READ_SEARCH* capability allows the current process to "Bypass file read permission checks and -directory read and execute permission checks", which is what we need to +directory read and execute permission checks", which is what you need to back up a system. Using ambient capabilities (recommended) ======================================== -First we create a new user called ``restic`` that is going to create +First, create a new user called ``restic`` that is going to create the backups: .. code-block:: console @@ -361,21 +361,21 @@ execution, the system will read the assigned capabilities and assign them to the process. This is less secure than using ambient capabilities as anyone who is able to execute the binary can make use of the capability. -First we create a new user called ``restic`` that is going to create +First, create a new user called ``restic`` that is going to create the backups: .. code-block:: console # useradd --system --create-home --shell /sbin/nologin restic -Then we copy the restic binary into the user's home directory: +Then copy the restic binary into the user's home directory: .. code-block:: console # mkdir /home/restic/bin # cp /usr/bin/restic /home/restic/bin/restic -Before we assign any special capability to the restic binary we +Before assigning any special capability to the restic binary, restrict its permissions so that only root and the newly created restic user can execute it. Otherwise any user could use the privileged restic binary to access any file. @@ -385,7 +385,7 @@ privileged restic binary to access any file. # chown root:restic /home/restic/bin/restic # chmod 750 /home/restic/bin/restic -Finally we can use ``setcap`` to add an extended attribute to the +Finally, use ``setcap`` to add an extended attribute to the restic binary. On every execution the system will read the extended attribute, interpret it and assign capabilities accordingly. @@ -428,8 +428,8 @@ Running a local repository server ================================= On the internal host, download and run the latest `release `__ -of REST-server to act as the repository server. In this example we are using -the ``--no-auth`` option to not require authentication when connecting to it: +of REST-server to act as the repository server. In this example the +``--no-auth`` option is used to not require authentication when connecting to it: .. code-block:: console diff --git a/doc/090_participating.rst b/doc/090_participating.rst index 749e07eda..d6d474b23 100644 --- a/doc/090_participating.rst +++ b/doc/090_participating.rst @@ -166,7 +166,7 @@ The classical helpers for integration tests are, amongst others: - ``testListSnapshots(t, env.gopts, )``: check that there are snapshots in the repository - ``testRunCheck(t, env.gopts)``: check that the repository is sound and happy - the above mentioned ``rtest.OK()``, ``rtest.Equals()``, ``rtest.Assert()`` helpers -- ``withCaptureStdout()`` and ``withTermStatus()`` wrappers: both functions are found in ``cmd/restic/integration_helpers_test.go`` for creating an environment where one can analyze the output created by the ``testRunXXX()`` command, particularly when checking JSON output +- ``withCaptureStdout()`` and ``withTermStatus()`` wrappers: both functions are found in ``cmd/restic/integration_helpers_test.go`` for creating an environment where you can analyze the output created by the ``testRunXXX()`` command, particularly when checking JSON output Integration tests test the overall workings of a command. Integration tests are used for commands and are stored in the same directory ``cmd/restic``. The recommended naming convention is diff --git a/doc/faq.rst b/doc/faq.rst index f777d1309..329c54479 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -280,7 +280,7 @@ Archive** storage classes is available: **Notes:** - This feature is still in early alpha stage. Expect arbitrary breaking changes - in the future (although we'll do our best-effort to avoid them). + in the future (although the project will make best-effort attempts to avoid them). - Expect restores to hang from 1 up to 42 hours depending on your storage class, provider and luck. Restores from cold storages are known to be time-consuming. You may need to adjust the `s3.restore-timeout` if a restore diff --git a/doc/manual_rest.rst b/doc/manual_rest.rst index 2382e7c87..0f4f3929f 100644 --- a/doc/manual_rest.rst +++ b/doc/manual_rest.rst @@ -190,9 +190,9 @@ Managing tags on snapshots is done with the ``tag`` command. The existing set of tags can be replaced completely, tags can be added or removed. The result is directly visible in the ``snapshots`` command. -Let's say we want to tag snapshot ``590c8fc8`` with the tags ``NL`` and -``CH`` and remove all other tags that may be present, the following -command does that: +To tag snapshot ``590c8fc8`` with the tags ``NL`` and +``CH`` and remove all other tags that may be present, run the following +command: .. code-block:: console @@ -200,10 +200,10 @@ command does that: create exclusive lock for repository modified tags on 1 snapshots -Note the snapshot ID has changed, so between each change we need to look up the +Note the snapshot ID has changed, so between each change you need to look up the new ID of the snapshot. But there is an even better way - the ``tag`` command -accepts a filter using the ``--tag`` option, so we can filter snapshots based -on the tag we just added. This way we can add and remove tags incrementally: +accepts a filter using the ``--tag`` option, so you can filter snapshots based +on the tag you just added. This way you can add and remove tags incrementally: .. code-block:: console @@ -354,7 +354,7 @@ host by using the ``--host`` flag: Total File Count: 21766 Total Size: 481.783 GiB -There we see that it would take 482 GiB of disk space to restore the latest +This shows that it would take 482 GiB of disk space to restore the latest snapshot from "myserver". In case you have multiple backups running from the same host you can also use @@ -362,7 +362,7 @@ In case you have multiple backups running from the same host you can also use are looking for. But how much space does that snapshot take on disk? In other words, how much -has restic's deduplication helped? We can check: +has restic's deduplication helped? You can check: .. code-block:: console @@ -370,7 +370,7 @@ has restic's deduplication helped? We can check: Total Blob Count: 340847 Total Size: 458.663 GiB -Comparing this size to the previous command, we see that restic has saved +Comparing this size to the previous command, you can see that restic has saved about 23 GiB of space with deduplication. Which mode you use depends on your exact use case. Some modes are more useful