doc: Clarify and make grouping in forget more noticeable

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
+The "forget" command removes snapshots according to a policy. All snapshots are
-this command really only deletes the snapshot object in the repository, which
+first divided into groups according to "--group-by", and after that the policy
-is a reference to data stored there. In order to remove the unreferenced data
+specified by the "--keep-*" options is applied to each group individually.
-after "forget" was run successfully, see the "prune" command. Please also read
+
-the documentation for "forget" to learn about important security considerations.
+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")
 

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 {

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,
+When ``forget`` is run with a policy, restic first loads the list of all snapshots
-then groups these by host name and list of directories. The grouping options can
+and groups them by their host name and paths. The grouping options can be set with
-be set with ``--group-by``, to e.g. group snapshots by only paths and tags use
+``--group-by``, e.g. using ``--group-by paths,tags`` to instead group snapshots by
-``--group-by paths,tags``. The policy is then applied to each group of snapshots
+paths and tags. The policy is then applied to each group of snapshots individually.
-separately. This is a safety feature to prevent accidental removal of unrelated
+This is a safety feature to prevent accidental removal of unrelated backup sets. To
-backup sets.
+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``