rewrite: Polish documentation

cmd/restic/cmd_rewrite.go

@@ -17,22 +17,23 @@ import (
 
 var cmdRewrite = &cobra.Command{
 	Use:   "rewrite [flags] [snapshotID ...]",
-	Short: "Rewrite existing snapshots",
+	Short: "Rewrite snapshots to exclude unwanted files",
 	Long: `
-The "rewrite" command excludes files from existing snapshots.
+The "rewrite" command excludes files from existing snapshots. It creates new
+snapshots containing the same data as the original ones, but without the files
+you specify to exclude. All metadata (time, host, tags) will be preserved.
 
-By default 'rewrite' will create new snapshots that will contains same data as
-the source snapshots but without excluded files. All metadata (time, host, tags)
-will be preserved. The special tag 'rewrite' will be added to new snapshots to
-distinguish it from the source (unless --forget is used).
+The snapshots to rewrite are specified using the --host, --tag and --path options,
+or by providing a list of snapshot IDs. Please note that specifying neither any of
+these options nor a snapshot ID will cause the command to rewrite all snapshots.
 
-If --forget option is used, old snapshot will be removed from repository.
+The special tag 'rewrite' will be added to the new snapshots to distinguish
+them from the original ones, unless --forget is used. If the --forget option is
+used, the original snapshots will instead be directly removed from the repository.
 
-Snapshots to rewrite are specified using --host, --tag, --path or by providing
-a list of snapshot ids. Not specifying a snapshot id will rewrite all snapshots.
-
-Please note, that this command only creates new snapshots. In order to delete
-data from the repository use 'prune' command.
+Please note that the --forget option only removes the snapshots and not the actual
+data stored in the repository. In order to delete the no longer referenced data,
+use the "prune" command.
 
 EXIT STATUS
 ===========
@@ -60,7 +61,7 @@ func init() {
 	cmdRoot.AddCommand(cmdRewrite)
 
 	f := cmdRewrite.Flags()
-	f.BoolVarP(&rewriteOptions.Forget, "forget", "", false, "replace existing snapshots")
+	f.BoolVarP(&rewriteOptions.Forget, "forget", "", false, "remove original snapshots after creating new ones")
 	f.BoolVarP(&rewriteOptions.DryRun, "dry-run", "n", false, "do not do anything, just print what would be done")
 
 	initMultiSnapshotFilterOptions(f, &rewriteOptions.snapshotFilterOptions, true)

doc/045_working_with_repos.rst

@@ -141,7 +141,7 @@ Filtering snapshots to copy
 ---------------------------
 
 The list of snapshots to copy can be filtered by host, path in the backup
-and / or a comma-separated tag list:
+and/or a comma-separated tag list:
 
 .. code-block:: console
 
@@ -179,9 +179,11 @@ Note that it is not possible to change the chunker parameters of an existing rep
 Removing files from snapshots
 =============================
 
-Sometimes a backup includes more files that intended. Instead of removing the snapshot,
-it is possible to rewrite its contents to remove the files in question. For this you
-can use the ``rewrite`` command:
+Snapshots sometimes turn out to include more files that 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
+the unwanted files from affected snapshots by rewriting them using the
+``rewrite`` command:
 
 .. code-block:: console
 
@@ -190,7 +192,7 @@ can use the ``rewrite`` command:
 
     snapshot 6160ddb2 of [/home/user/work] at 2022-06-12 16:01:28.406630608 +0200 CEST)
     excluding /home/user/work/secret-file
-    new snapshot saved as b6aee1ff7f5e0ac15157f16370015978e496fa60f7351bc94a8d6049e4c7096d
+    saved new snapshot b6aee1ff
 
     snapshot 4fbaf325 of [/home/user/work] at 2022-05-01 11:22:26.500093107 +0200 CEST)
 
@@ -201,29 +203,32 @@ can use the ``rewrite`` command:
 
     snapshot 6160ddb2 of [/home/user/work] at 2022-06-12 16:01:28.406630608 +0200 CEST)
     excluding /home/user/work/secret-file
-    new snapshot saved as b6aee1ff7f5e0ac15157f16370015978e496fa60f7351bc94a8d6049e4c7096d
+    new snapshot saved as b6aee1ff
 
     modified 1 snapshots
 
-The options ``--exclude``, ``--exclude-file``, ``--iexclude`` and ``--iexclude-file`` are
-supported. They behave the same way as for the backup command, see :ref:`backup-excluding-files`
-for details.
+The options ``--exclude``, ``--exclude-file``, ``--iexclude`` and
+``--iexclude-file`` are supported. They behave the same way as for the backup
+command, see :ref:`backup-excluding-files` for details.
 
-It is possible to only rewrite a subset of snapshots. Filtering the snapshots works the
-same way as for the ``copy`` command, see :ref:`copy-filtering-snapshots`.
+It is possible to rewrite only a subset of snapshots by filtering them the same
+way as for the ``copy`` command, see :ref:`copy-filtering-snapshots`.
 
-By default, the ``rewrite`` command will keep the original snapshot and create a new
-snapshot for every snapshot which was modified while rewriting. All new snapshots are
-marked with the tag ``rewrite``.
+By default, the ``rewrite`` command will keep the original snapshots and create
+new ones for every snapshot which was modified during rewriting. The new
+snapshots are marked with the tag ``rewrite`` to differentiate them from the
+original, rewritten snapshots.
 
-Alternatively, you can use the ``--forget`` option to immediatelly remove the original
-snapshot. In this case, no tag is added to the snapshots. Please note that only the
-original snapshot file is removed from the repository, but not the excluded data.
-Run the ``prune`` command afterwards to cleanup the now unused data.
+Alternatively, you can use the ``--forget`` option to immediately remove the
+original snapshots. In this case, no tag is added to the new snapshots. Please
+note that this only removes the snapshots and not the actual data stored in the
+repository. Run the ``prune`` command afterwards to remove the now unreferenced
+data (just like when having used the ``forget`` command).
 
-In order to preview the changes which ``rewrite`` would make, you can use the ``--dry-run``
-option. This will simulate the rewriting process without actually modifying the repository.
-Instead restic will only print the expected changes.
+In order to preview the changes which ``rewrite`` would make, you can use the
+``--dry-run`` option. This will simulate the rewriting process without actually
+modifying the repository. Instead restic will only print the actions it would
+perform.
 
 
 Checking integrity and consistency

doc/manual_rest.rst

@@ -38,7 +38,7 @@ Usage help is available:
       rebuild-index Build a new index
       recover       Recover data from the repository not referenced by snapshots
       restore       Extract the data from a snapshot
-      rewrite       Rewrite existing snapshots
+      rewrite       Rewrite snapshots to exclude unwanted files
       self-update   Update the restic binary
       snapshots     List all snapshots
       stats         Scan the repository and show basic statistics