borgbackup / borgbackup/borg

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

Open
#9,545 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
13.7k
Forks
875
Avg merge
11h 15m
Merged PRs (30d)
192

Description

There is an [experimental implementation](https://github.com/gmatht/rorg/tree/ux-clean4) 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**
```bash
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:
```bash
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**
```bash
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.:
```bash
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**
```bash
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:
```bash
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**
```bash
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:
```bash
borg --repo /tmp/demo-repo create --upload-ratelimit 1000 test /root/data
```
### 5) Missing required encryption for `repo-create`
**User runs**
```bash
borg --repo /tmp/demo-repo repo-create
```
**Help should say**
- `repo-create` requires `-e/--encryption`.
- Show a concrete fix:
```bash
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**
```bash
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:
```bash
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**
```bash
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**
```bash
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`:
```bash
borg -r REPO repo-list
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.