diff --git a/cmd/restic/cmd_rewrite.go b/cmd/restic/cmd_rewrite.go index 688ee77a2..fc6284ce8 100644 --- a/cmd/restic/cmd_rewrite.go +++ b/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) diff --git a/doc/045_working_with_repos.rst b/doc/045_working_with_repos.rst index a42dbab9e..860d01ae3 100644 --- a/doc/045_working_with_repos.rst +++ b/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 diff --git a/doc/manual_rest.rst b/doc/manual_rest.rst index b15e1dd69..1aa9a434d 100644 --- a/doc/manual_rest.rst +++ b/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