docs(cli): clarify documentation regarding per-user and per-host (#4512)

Ref: #4341

---------
Co-authored-by: Julio Lopez <1953782+julio-lopez@users.noreply.github.com>

cli/command_policy.go

@@ -40,7 +40,7 @@ type policyTargetFlags struct {
 }
 
 func (c *policyTargetFlags) setup(cmd *kingpin.CmdClause) {
-	cmd.Arg("target", "Select a particular policy ('user@host','@host','user@host:path' or a local path). Use --global to target the global policy.").StringsVar(&c.targets)
+	cmd.Arg("target", "Select a particular policy (a per-host policy `@host`, a per-user policy `user@host`, a per-path policy `user@host:path` or a local path). Use --global to target the global policy.").StringsVar(&c.targets)
 	cmd.Flag("global", "Select the global policy.").BoolVar(&c.global)
 }
 

cli/command_policy_edit.go

@@ -57,7 +57,7 @@ type commandPolicyEdit struct {
 }
 
 func (c *commandPolicyEdit) setup(svc appServices, parent commandParent) {
-	cmd := parent.Command("edit", "Set snapshot policy for a single directory, user@host or a global policy.")
+	cmd := parent.Command("edit", "Edit policy.")
 	c.policyTargetFlags.setup(cmd)
 	cmd.Action(svc.repositoryWriterAction(c.run))
 	c.out.setup(svc)

cli/command_policy_export.go

@@ -27,7 +27,7 @@ type commandPolicyExport struct {
 const exportFilePerms = 0o600
 
 func (c *commandPolicyExport) setup(svc appServices, parent commandParent) {
-	cmd := parent.Command("export", "Exports the policy to the specified file, or to stdout if none is specified.")
+	cmd := parent.Command("export", "Exports the policies to the specified file, or to stdout if none is specified.")
 	cmd.Flag("to-file", "File path to export to").StringVar(&c.filePath)
 	cmd.Flag("overwrite", "Overwrite the file if it exists").BoolVar(&c.overwrite)
 

cli/command_policy_remove.go

@@ -15,7 +15,7 @@ type commandPolicyDelete struct {
 }
 
 func (c *commandPolicyDelete) setup(svc appServices, parent commandParent) {
-	cmd := parent.Command("delete", "Remove snapshot policy for a single directory, user@host or a global policy.").Alias("remove").Alias("rm")
+	cmd := parent.Command("delete", "Remove policy.").Alias("remove").Alias("rm")
 	c.policyTargetFlags.setup(cmd)
 	cmd.Flag("dry-run", "Do not remove").Short('n').BoolVar(&c.dryRun)
 	cmd.Action(svc.repositoryWriterAction(c.run))

cli/command_policy_set.go

@@ -31,7 +31,7 @@ type commandPolicySet struct {
 }
 
 func (c *commandPolicySet) setup(svc appServices, parent commandParent) {
-	cmd := parent.Command("set", "Set snapshot policy for a single directory, user@host or a global policy.")
+	cmd := parent.Command("set", "Set policy.")
 	c.policyTargetFlags.setup(cmd)
 	cmd.Flag(inheritPolicyString, "Enable or disable inheriting policies from the parent").BoolListVar(&c.inherit)
 

site/content/docs/Getting started/_index.md

@@ -38,7 +38,15 @@ After the initial snapshot, for every snapshot afterwards Kopia will rescan the
 
 > PRO TIP: If you pick a value for `Snapshot Frequency` when creating a `policy`, then Kopia will automatically take snapshots at that frequency (e.g., every one hour or whatever value you pick), and you do not need to remember to manually run the snapshot. If you do not pick a `Snapshot Frequency`, then Kopia will not automatically take snapshots, and you need to manually run snapshots from the `Snapshots` tab (just click the `Snapshot Now` button as needed).
 
-Note that you can set policies at two levels in `KopiaUI` -- at the `global` level, where the settings are applied by default to all policies that do not define their own settings, or at the individual `policy` level, where the settings are applied only to that particular policy. By default, all new policies are set to inherit settings from the `global` policy. The `global` policy is the one that says `*` for `Username`, `Host`, and `Path`.
+Note that you can set policies at four levels in `KopiaUI`:
+* at the `global` level (shown with `*` for `Username`, `Host` and `Path`),
+* at the per-host `@host` level (shown with `*` for `Username` and `Path`),
+* at the per-user `user@host` level (shown with `*` for `Path`),
+* and at the individual `Path` level, where the settings are applied only to that particular policy.
+
+By default, all new policies are set to inherit settings from the `global` policy, as well as from the applicable per-host and per-user policies. More specific policies settings take priority. This means that individual per-path policies settings come first, followed by per-user, then per-host and finally global policy settings.
+
+For example, say you have a path policy for `foo@bar:/path` which doesn't define setting `xyz`, a per-user policy for `foo@bar` setting `xyz` to `1` and the global policy setting `xyz` to `2`. In this case, the effective value of `xyz` for the policy `foo@bar:/path` will be `1`.
 
 > PRO TIP: Kopia does not currently support the ability to save one snapshot to multiple different repositories. However, you can use `KopiaUI` to connect to multiple different repositories simultaneously and create identical policies for each repository, which essentially achieves the same outcome of saving one snapshot to multiple different repositories. Connecting to more than one repository in `KopiaUI` is easy: just right-click the icon of the desktop application and select `Connect To Another Repository...`. Currently, this is only available in the desktop version of `KopiaUI` and not the web-based `KopiaUI`. However, if you are using the web-based `KopiaUI`, you can manually run multiple instances of `KopiaUI` to achieve the same outcome.
 
@@ -286,6 +294,8 @@ Files policy:
 
 We can change policy settings using the [`kopia policy set` command](../reference/command-line/common/policy-set/). This command allows you to change the `global` policy or change specific policies for a 'user@host', a '@host', a 'user@host:path', or a particular directory. For example, here we tell Kopia to set the policy to ignore two directories from being included in the snapshot of `jarek@jareks-mbp:/Users/jarek/Projects/Kopia/site`:
 
+> NOTE: When referring to policies, `user@host` and `@host` are used to refer to per-user and per-host policies, respectively. They do NOT refer to all policies defined under that user or host.
+
 ```
 $ kopia policy set --add-ignore public/ --add-ignore node_modules/ .
 Setting policy for jarek@jareks-mbp:/Users/jarek/Projects/Kopia/site