rewrite: add documentation

doc/040_backup.rst

@@ -204,6 +204,7 @@ Combined with ``--verbose``, you can see a list of changes:
     modified  /archive.tar.gz, saved in 0.140s (25.542 MiB added)
     Would be added to the repository: 25.551 MiB
 
+.. _backup-excluding-files:
 Excluding Files
 ***************
 

doc/045_working_with_repos.rst

@@ -136,6 +136,7 @@ or the environment variable ``$RESTIC_FROM_KEY_HINT``.
     repository. You can avoid this limitation by using the rclone backend
     along with remotes which are configured in rclone.
 
+.. _copy-filtering-snapshots:
 Filtering snapshots to copy
 ---------------------------
 
@@ -175,6 +176,56 @@ using the same chunker parameters as the source repository:
 Note that it is not possible to change the chunker parameters of an existing repository.
 
 
+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:
+
+.. code-block:: console
+
+    $ restic -r /srv/restic-repo rewrite --exclude secret-file
+    repository c881945a opened (repository version 2) successfully, password is correct
+
+    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
+
+    snapshot 4fbaf325 of [/home/user/work] at 2022-05-01 11:22:26.500093107 +0200 CEST)
+
+    modified 1 snapshots
+
+    $ restic -r /srv/restic-repo rewrite --exclude secret-file 6160ddb2
+    repository c881945a opened (repository version 2) successfully, password is correct
+
+    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
+
+    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.
+
+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`.
+
+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``.
+
+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.
+
+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.
+
+
 Checking integrity and consistency
 ==================================
 

doc/manual_rest.rst

@@ -26,7 +26,7 @@ Usage help is available:
       dump          Print a backed-up file to stdout
       find          Find a file, a directory or restic IDs
       forget        Remove snapshots from the repository
-      generate      Generate manual pages and auto-completion files (bash, fish, zsh)
+      generate      Generate manual pages and auto-completion files (bash, fish, zsh, powershell)
       help          Help about any command
       init          Initialize a new repository
       key           Manage keys (passwords)
@@ -38,6 +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
       self-update   Update the restic binary
       snapshots     List all snapshots
       stats         Scan the repository and show basic statistics