Feature Request: Improve `SN_THROW` Error Output with Contextual Help and Variable Disclosure

[Torstein-Eide]

Summary

Current snapper error messages produced via SN_THROW are technically correct but user-hostile.
They often fail fast without telling the user:

• What snapper detected
• Which variables were involved
• What the next obvious corrective action is
• How to get help for the exact subcommand that failed

This request proposes enhanced error output that is still concise, but actionable.

Goals

1. Make errors self-explanatory without requiring users to immediately read man snapper
2. Expose relevant runtime variables (config, path, subcommand)
3. Always suggest the correct scoped help, i.e.
   snapper ${sub_function} --help
4. Do not change exit codes or program flow
5. Keep output compatible with scripting (human-readable only on stderr)

Proposed Behavior

1. Context-aware SN_THROW output

When an error occurs, the output should include:

• The primary error (unchanged)
• Detected state (current config, path, etc.)
• Action hint
• Help hint, scoped to the subcommand

Example: snapper create-config

Currently

# snapper create-config ${Path}
Creating config failed (config already exists).

This is technically true and practically useless.

Proposed

# snapper create-config ${Path}
Creating config failed (config already exists).

Detected state:
  Config name : root
  Subvolume   : ${Path}

Hints:
  - You can select a different config with: -c ${new_config}
  - Existing configs can be listed with: snapper list-configs

Help:
  snapper create-config --help
  man snapper

This tells the user exactly what snapper already knows internally.

Example: Generic Pattern

Current (typical SN_THROW)

Operation failed.

Proposed Pattern

Operation failed.

Context:
  Command     : ${sub_function}
  Config      : ${config}
  Target      : ${path}

Help:
  snapper ${sub_function} --help

Variable Disclosure (Minimal but Useful)

Suggested standard variables to include when available:

Variable	Description
${sub_function}	Current snapper command
${config}	Active config (e.g. root)
${path}	Target subvolume/path
${number}	Snapshot number (if applicable)

Important:
Only print variables that are actually resolved.
No N/A, no noise.

--help Support for Subcommands

The manpage already documents:

snapper --help

But users expect this to work:

snapper create-config --help
snapper delete --help
snapper rollback --help

Request

Ensure all subcommands accept:

snapper ${sub_function} --help

and display command-scoped help, not global help.

If already implemented internally, error output should explicitly point users to it.

Why This Matters

• Snapper is often used during system recovery
• Errors happen when users are already stressed
• Better messages reduce:
  • Support load
  • Documentation lookups
  • Trial-and-error runs
• This aligns with modern CLI UX (git, podman, systemd tools)

Bluntly put: Snapper already knows the answer. It just refuses to tell the user.

Let’s fix that.

Compatibility & Risk

• No behavior changes
• No output format changes for --machine-readable
• Only improves stderr messages
• Zero risk to existing workflows