diff --git a/cmd/restic/cmd_forget.go b/cmd/restic/cmd_forget.go index 1feb39994..46f3fee0f 100644 --- a/cmd/restic/cmd_forget.go +++ b/cmd/restic/cmd_forget.go @@ -14,11 +14,16 @@ var cmdForget = &cobra.Command{ Use: "forget [flags] [snapshot ID] [...]", Short: "Remove snapshots from the repository", Long: ` -The "forget" command removes snapshots according to a policy. Please note that -this command really only deletes the snapshot object in the repository, which -is a reference to data stored there. In order to remove the unreferenced data -after "forget" was run successfully, see the "prune" command. Please also read -the documentation for "forget" to learn about important security considerations. +The "forget" command removes snapshots according to a policy. All snapshots are +first divided into groups according to "--group-by", and after that the policy +specified by the "--keep-*" options is applied to each group individually. + +Please note that this command really only deletes the snapshot object in the +repository, which is a reference to data stored there. In order to remove the +unreferenced data after "forget" was run successfully, see the "prune" command. + +Please also read the documentation for "forget" to learn about some important +security considerations. EXIT STATUS =========== @@ -91,7 +96,7 @@ func init() { f.StringArrayVar(&forgetOptions.Paths, "path", nil, "only consider snapshots which include this (absolute) `path` (can be specified multiple times)") f.BoolVarP(&forgetOptions.Compact, "compact", "c", false, "use compact output format") - f.StringVarP(&forgetOptions.GroupBy, "group-by", "g", "host,paths", "string for grouping snapshots by host,paths,tags") + f.StringVarP(&forgetOptions.GroupBy, "group-by", "g", "host,paths", "`group` snapshots by host, paths and/or tags, separated by comma (disable grouping with '')") f.BoolVarP(&forgetOptions.DryRun, "dry-run", "n", false, "do not delete anything, just print what would be done") f.BoolVar(&forgetOptions.Prune, "prune", false, "automatically run the 'prune' command if snapshots have been removed") diff --git a/cmd/restic/cmd_snapshots.go b/cmd/restic/cmd_snapshots.go index d305878da..ed201bf65 100644 --- a/cmd/restic/cmd_snapshots.go +++ b/cmd/restic/cmd_snapshots.go @@ -58,7 +58,7 @@ func init() { panic(err) } f.IntVar(&snapshotOptions.Latest, "latest", 0, "only show the last `n` snapshots for each host and path") - f.StringVarP(&snapshotOptions.GroupBy, "group-by", "g", "", "string for grouping snapshots by host,paths,tags") + f.StringVarP(&snapshotOptions.GroupBy, "group-by", "g", "", "`group` snapshots by host, paths and/or tags, separated by comma") } func runSnapshots(opts SnapshotOptions, gopts GlobalOptions, args []string) error { diff --git a/doc/060_forget.rst b/doc/060_forget.rst index ce23a5893..55acc42ea 100644 --- a/doc/060_forget.rst +++ b/doc/060_forget.rst @@ -212,12 +212,13 @@ The ``forget`` command accepts the following policy options: .. note:: Specifying ``--keep-tag ''`` will match untagged snapshots only. -When ``forget`` is run with a policy, restic loads the list of all snapshots, -then groups these by host name and list of directories. The grouping options can -be set with ``--group-by``, to e.g. group snapshots by only paths and tags use -``--group-by paths,tags``. The policy is then applied to each group of snapshots -separately. This is a safety feature to prevent accidental removal of unrelated -backup sets. +When ``forget`` is run with a policy, restic first loads the list of all snapshots +and groups them by their host name and paths. The grouping options can be set with +``--group-by``, e.g. using ``--group-by paths,tags`` to instead group snapshots by +paths and tags. The policy is then applied to each group of snapshots individually. +This is a safety feature to prevent accidental removal of unrelated backup sets. To +disable grouping and apply the policy to all snapshots regardless of their host, +paths and tags, use ``--group-by ''`` (that is, an empty value to ``--group-by``). Additionally, you can restrict the policy to only process snapshots which have a particular hostname with the ``--host`` parameter, or tags with the ``--tag``