`borg2`: Support `env` section in YAML config files
- Dominant language
- Python
- Stars
- 13.7k
- Forks
- 875
- Avg merge
- 11h 15m
- Merged PRs (30d)
- 192
Description
One of the goals of `borg2` has been to reduce the number of dedicated CLI options and instead rely more on env variables. For example, `--remote-path` and `--rsh` are about to be removed in favor of `BORG_REMOTE_PATH` and `BORG_RSH` (#9952).
While this reduces the CLI surface, it also spreads config across multiple places: some settings are configured via CLI options, while others are configured exclusively via dedicated env variables.
With `borg2`, `jsonargparse` was introduced as a new dependency, making it possible to provide CLI options via alternative means:
* via env variables (although the generated names can be somewhat cumbersome, e.g. `BORG_CREATE__COMMENT` for `borg2 create --comment`)
* via YAML config files, either specified with `--config` or loaded from `~/.config/borg/default.yaml` by default
Overall, this makes config feel somewhat fragmented. While all settings can now be expressed via env variables, they are not a good fit for persistent and per-job configuration. Config files are the natural alternative. However, the config files currently cannot express settings that are available exclusively via dedicated `BORG_*` env variables. Allowing config files to define those env variables would make them a complete and consistent alternative for persistent and per-job Borg configuration.
**Proposal**
Support an optional top-level `env` section in the YAML config file.
For example:
```yaml
env:
BORG_HOSTNAME: my-host
BORG_RSH: ssh -i /path/to/private/key
BORG_FILES_CACHE_TTL: 30
log_level: info
show_rc: true
create:
stats: true
compression: zstd,6
```
The values defined in `env` would be injected into Borg's environment as part of normal argument processing (unless already explicitly set in the calling environment), making them practically behave as if they had been set in the shell.
This would allow users to keep all Borg config in a single declarative file.
**Motivation**
The YAML config support provided by `jsonargparse` is a valuable addition to `borg2` and has the potential to become a common way of managing Borg configs.
While `jsonargparse` also makes it possible to provide CLI options via env variables, env variables are not an ideal replacement for persistent application config. They are inherently global to a shell. Users may not want to populate their shell environment with application-specific variables, and setting them only at runtime typically requires wrapper scripts, shell aliases, systemd unit files, cron jobs, or similar tooling. More importantly, Borg is commonly used with multiple independent backup jobs, each requiring different settings, but env variables cannot easily express multiple independent configurations without external scaffolding.
Config files naturally solve these problems. They are easy to version, can be selected on a per-invocation basis via `--config`, and allow multiple independent backup configurations to coexist cleanly. To fully support this use case, config files should also be able to define settings that are currently only accessible via dedicated env variables.
Supporting an `env` section would:
* keep config centralized,
* allow complete backup job definitions to live in a single declarative file,
* avoid the need for wrapper scripts whose only purpose is to set env variables,
* make multiple independent backup configurations straightforward to maintain,
* provide a more consistent config experience,
* naturally complement the existing YAML config mechanism.
It would also align well with the goal of reducing CLI-specific options without making config files less expressive.
Contributor guide
Research direction
Start by tracing borg2's jsonargparse-based YAML loading for --config and ~/.config/borg/default.yaml, then check how dedicated BORG_* variables enter normal argument processing. Done means an optional top-level env mapping injects values without overriding explicitly supplied process environment variables, while existing CLI and YAML options continue to work.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100