Add targeted “Common fixes” hints for specific mistaken borg command lines

[gmatht]

There is an experimental implementation of the proposed behavior.

Goal

When a user enters a wrong, obsolete, or borg1-style command line, borg should print actionable guidance tailored to that exact invocation (not just a generic usage dump): what was wrong, what borg2 expects, and one or more corrected commands.

Cases and expected help

1) Borg1 init used on borg2

User runs

borg --repo /tmp/demo-repo init -e repokey-aes-ocb

Help should say

• init is not a borg2 command; use repo-create.
• Show the corrected command:

borg --repo /tmp/demo-repo repo-create -e repokey-aes-ocb

• Also point to discovery: borg help (valid commands list).

2) Typos of valid borg2 commands

User runs

borg --repo /tmp/demo-repo rcreate -e repokey-aes-ocb
borg repo-creat
borg repoo-list

Help should say

• The entered word is not a valid command.
• Suggest the closest intended borg2 command (spell/nearest match), e.g.:
  • rcreate → repo-create
  • repo-creat → repo-create
  • repoo-list → repo-list
• Print a corrected command line preserving other args when possible, e.g.:

borg --repo /tmp/demo-repo repo-create -e repokey-aes-ocb
borg repo-create
borg repo-list

3) Borg1-only option --glob-archives used with list

User runs

borg --repo /tmp/demo-repo list --glob-archives 'my*'

Help should say

• --glob-archives is a borg1 option and is not used in borg2.
• Provide the borg2 replacement (--match-archives), including pattern style guidance and an example:

borg list ARCHIVE --match-archives 'sh:my*'

(And keep the normal borg list --help tip.)

4) Borg1-only option --remote-ratelimit used with create

User runs

borg --repo /tmp/demo-repo create --remote-ratelimit 1000 test /root/data

Help should say

• --remote-ratelimit is borg1-only / obsolete in borg2.
• Replacement is --upload-ratelimit.
• Provide corrected command:

borg --repo /tmp/demo-repo create --upload-ratelimit 1000 test /root/data

5) Missing required encryption for repo-create

User runs

borg --repo /tmp/demo-repo repo-create

Help should say

• repo-create requires -e/--encryption.
• Show a concrete fix:

borg --repo /tmp/demo-repo repo-create -e repokey-aes-ocb

• List available modes (or point to borg repo-create --help if the list is too long).

6) Borg1 repo::archive syntax passed via --repo

User runs

borg --repo /tmp/demo-repo::test1 list

Help should say

• Borg2 does not accept repo::archive in --repo.
• Show corrected ways to express the intent, e.g. either:
  • keep repo in --repo and pass archive separately, or
  • use BORG_REPO and pass ::archive positionally.
    Example corrected commands:

borg --repo /tmp/demo-repo list ::test1
export BORG_REPO=/tmp/demo-repo
borg list ::test1

7) Repo path does not exist (with guidance to create)

User runs

borg --repo /tmp/does-not-exist repo-info

Help should say

• Path does not exist / repo not found.
• Offer next steps:
  • fix the path, or
  • create the repo (and show an example with repo-create + -e), or
  • set BORG_REPO then run repo-create.

8) “I ran borg list but meant ‘list archives’”

User runs

borg list

(or borg --repo /tmp/does-not-exist list resulting in missing required args)
Help should say

• borg list NAME lists contents of an archive and needs an archive NAME.
• If the user intended to list archives in a repo, suggest repo-list:

borg -r REPO repo-list

[ThomasWaldmann]

Thanks for creating this issue, so we can discuss its parts:

1. borg1 to borg2 renamed commands: good idea, that will help users when they upgrade after borg2 release.

2. Typos: I don't think we should implement that. There can be many different kinds of typos.

3. Similar to 1), that might be useful. We do not need to support that for stuff that gives deprecation warnings since long though.

4. That should be delayed, we are still working on the repository code and there will be major changes.

5. There is a reason that --encryption has no default and for the same reason it should not just offer a single value. That stuff is not simple, so users will need to read the docs.

6. Maybe useful. Users used to borg1 might skip the "--repo" completely though.

7. Due to all sorts of URLs or paths being supported here, that might be not that easy.

8. Yes, might be useful.

In general: the smaller the code change required and the more useful it is, the better!

[gmatht]

(2) I was only proposing the type of typo where it doesn't match a valid command, but it fuzzy matches a valid command.

(4) What about something like:
Given that your CPU (does/doesn't) support AES, we recommend (AES/poly1305) encryption. Consider:
-e: authenticated -- If your data is public or you trust your backup server more than your memory.
-e: key-file-(a/p) -- Secure, but DO NOT LOSE KEYFILE or all data will be lost. Make backups of keyfile.
-e: repo-key-(a/p) -- Stores the key in the repo. For security, you need to pick a strong passphrase.

Also, I forgot:
9) User tries to issue UNIX or DOS command to borg.
If user runs borg rm or borg del suggest borg delete

[ThomasWaldmann]

(2) Only easy/simple/short fixes.

(4) No, we have quite extensive docs about that and I don't want to duplicate that to the code (and maintain it at 2 places).

(9) No, people can read the docs and use the shell completions (in 1.4-maint, these are handwritten, in master branch they are created via borg completion SHELL).