Skip to content

borg help environment: new help topic about env variables - #10063

Merged
ThomasWaldmann merged 1 commit into
borgbackup:masterfrom
ThomasWaldmann:help-env-10061
Aug 9, 2026
Merged

borg help environment: new help topic about env variables#10063
ThomasWaldmann merged 1 commit into
borgbackup:masterfrom
ThomasWaldmann:help-env-10061

Conversation

@ThomasWaldmann

Copy link
Copy Markdown
Member

Fixes #10061.

borg help environment (alias: borg help env) now shows the documentation about the environment variables borg supports, like borg help already does for patterns, placeholders, match-archives and compression. build_man automatically produces a borg-environment(1) man page from the new topic.

To avoid duplicating the docs, the help topic is now the single source of that documentation: scripts/make.py build_usage generates docs/usage/general/environment.rst.inc from it (and skips this topic on the misc. help docs page, where it would just duplicate the "General" chapter's section). The text was adapted a bit so it renders well both via sphinx and via nanorst on the terminal: the list-table, the note directive and the hyperlink targets were replaced by constructs nanorst understands (plain code-block table, plain URLs); the :ref: roles were kept and get substituted with plain text on the terminal like the command epilogs already do.

nanorst change: a code block now ends when a following line is less indented than the code block's contents, instead of the hardcoded "less than 4 spaces" rule. Without this, the many code blocks nested inside the environment topic's definition lists would swallow the text following them (the compression topic's obfuscate section had the same problem). Covered by new tests.

Checked:

  • borg help environment / borg help env render cleanly on the terminal (no leftover rst markup).
  • clean sphinx html build has zero warnings; the env_vars label still resolves (the auto-generated marker comment must come after the heading, otherwise it breaks the label-to-title association - noted in make.py).
  • nanorst + help_cmd tests pass, black/ruff clean.

🤖 Generated with Claude Code

…backup#10061

Add an "environment" help topic (alias: "env") showing the documentation
about the environment variables borg supports, like borg help already does
for patterns, placeholders, compression and match-archives.

The help topic is now the single source of that documentation:
scripts/make.py build_usage generates docs/usage/general/environment.rst.inc
from it (and skips it on the misc. help docs page, where it would duplicate
the "General" chapter's section), and build_man already generates a
borg-environment(1) man page from any help topic.

The text was adapted a bit so that it renders well both via sphinx and via
nanorst on the terminal: the list-table, note directive and hyperlink
targets were replaced by constructs nanorst understands.

nanorst: end a code block when a following line is less indented than the
code block's contents (instead of the hardcoded "less than 4 spaces" rule),
so code blocks nested inside definition lists do not swallow the text
following them any more. Also, borg help <topic> now resolves :ref:
references like the command epilogs already did.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@codecov

codecov Bot commented Aug 9, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 95.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 86.66%. Comparing base (e481b32) to head (39d0e27).
⚠️ Report is 7 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
src/borg/helpers/nanorst.py 92.85% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master   #10063      +/-   ##
==========================================
- Coverage   86.76%   86.66%   -0.10%     
==========================================
  Files          98       98              
  Lines       17085    17098      +13     
  Branches     2586     2590       +4     
==========================================
- Hits        14823    14818       -5     
- Misses       1570     1585      +15     
- Partials      692      695       +3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

@ThomasWaldmann
ThomasWaldmann merged commit 849b71c into borgbackup:master Aug 9, 2026
18 of 20 checks passed
@ThomasWaldmann
ThomasWaldmann deleted the help-env-10061 branch August 9, 2026 15:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

borg2 help env

1 participant