mirror of
https://github.com/borgbackup/borg.git
synced 2026-06-11 01:41:57 -04:00
Merge pull request #9184 from ThomasWaldmann/shtab2-master
more shell completion work
This commit is contained in:
TW
GitHub
commit
d6c334c4ec
6 changed files with 652 additions and 77 deletions
|
|
@ -168,7 +168,7 @@ New features:
|
|||
check; default is "yes", use at your own risk, #9109.
|
||||
- diff: --sort-by=field[,field,...], #8998
|
||||
- completion: generate completion scripts for supported shells, #9172,
|
||||
uses shtab, supports bash, tcsh, zsh (zsh needs shtab > 1.7.2).
|
||||
uses shtab, supports bash and zsh.
|
||||
|
||||
Fixes:
|
||||
|
||||
|
|
@ -199,7 +199,7 @@ Other changes:
|
|||
- save space in test_create_* tests
|
||||
- CI/tests: add SFTP/rclone/S3 repo testing
|
||||
- CI: add local servers for S3 and SFTP testing
|
||||
- CI: add *BSD and Haiku OS (on GitHub Actions)
|
||||
- CI: add misc. BSDs and Haiku OS (on GitHub Actions)
|
||||
- CI: do dynamic code analysis, #6819
|
||||
- transfer: add test for unexpected src repo index change, #9022
|
||||
- pyproject.toml: correctly define test environments for FUSE testing
|
||||
|
|
@ -222,6 +222,7 @@ Other changes:
|
|||
- how to debug borg mount, #5461
|
||||
- document what happens when a new keyfile repo is created at the same path, #6230
|
||||
- update install docs to include `SETUPTOOLS_SCM_PRETEND_VERSION`
|
||||
- highlight archive series naming for fast incrementals, #8955
|
||||
- add Arch Linux to the 'Installing from source' docs
|
||||
- add systemd-inhibit and examples, #8989
|
||||
- code/docs: fix typos and grammar
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ dependencies = [
|
|||
"platformdirs >=3.0.0, <5.0.0; sys_platform == 'darwin'", # for macOS: breaking changes in 3.0.0.
|
||||
"platformdirs >=2.6.0, <5.0.0; sys_platform != 'darwin'", # for others: 2.6+ works consistently.
|
||||
"argon2-cffi",
|
||||
"shtab>=1.7.0",
|
||||
"shtab>=1.8.0",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
|
|
|
|||
|
|
@ -1,45 +1,87 @@
|
|||
"""
|
||||
Shell completion support for Borg commands.
|
||||
|
||||
This module implements the `borg completion` command, which generates shell completion
|
||||
scripts for bash and zsh. It uses the shtab library for basic completion generation
|
||||
and extends it with custom dynamic completions for Borg-specific argument types.
|
||||
|
||||
Dynamic Completions
|
||||
-------------------
|
||||
|
||||
The following argument types have intelligent, context-aware completion:
|
||||
|
||||
1. Archive names/IDs (archivename_validator):
|
||||
- Completes archive names by default (e.g., "my-backup-2024")
|
||||
- Completes archive IDs when prefixed with "aid:" (e.g., "aid:12345678")
|
||||
- In zsh, shows archive metadata (name, timestamp, user@host) as descriptions
|
||||
- Respects --repo/-r flags to query the correct repository
|
||||
|
||||
2. Sort keys (SortBySpec):
|
||||
- Completes comma-separated sort keys (timestamp, archive, name, id, tags, host, user)
|
||||
- Prevents duplicate keys in the same option
|
||||
|
||||
3. Files cache mode (FilesCacheMode):
|
||||
- Completes comma-separated cache mode tokens (ctime, mtime, size, inode, rechunk, disabled)
|
||||
- Enforces mutual exclusivity (e.g., ctime vs mtime, disabled vs others)
|
||||
|
||||
4. Compression algorithms (CompressionSpec):
|
||||
- Suggests compression specs with examples (lz4, zstd,3, auto,zstd,10, etc.)
|
||||
|
||||
5. Chunker parameters (ChunkerParams):
|
||||
- Suggests chunker param examples (default, fixed,4194304, buzhash,19,23,21,4095, etc.)
|
||||
|
||||
6. Paths (PathSpec):
|
||||
- Completes directories using standard shell directory completion
|
||||
|
||||
7. Help topics:
|
||||
- Completes help command topics and subcommand names
|
||||
|
||||
8. Tags (tag_validator):
|
||||
- Completes existing tags from the repository
|
||||
|
||||
9. Relative time markers (relative_time_marker_validator):
|
||||
- Suggests common time intervals (60S, 60M, 24H, 7d, 4w, 12m, 1000y)
|
||||
|
||||
10. Timestamps (timestamp):
|
||||
- Completes file paths when starting with / or .
|
||||
- Otherwise suggests current timestamp in ISO format
|
||||
|
||||
11. File sizes (parse_file_size):
|
||||
- Suggests common file size values (500M, 1G, 10G, 100G, 1T, etc.)
|
||||
"""
|
||||
|
||||
import argparse
|
||||
|
||||
import shtab
|
||||
|
||||
from ._common import process_epilog
|
||||
from ..constants import * # NOQA
|
||||
from ..helpers import archivename_validator # used to detect ARCHIVE args for dynamic completion
|
||||
|
||||
# Dynamic completion for archive IDs (aid:...)
|
||||
#
|
||||
# This integrates with shtab by:
|
||||
# - tagging argparse actions that accept an ARCHIVE (identified by type == archivename_validator)
|
||||
# with a .complete mapping pointing to our helper function.
|
||||
# - using shtab.complete's 'preamble' parameter to inject the helper into the
|
||||
# generated completion script for supported shells.
|
||||
#
|
||||
# Notes / constraints (per plan):
|
||||
# - Calls `borg repo-list --format ...` and filters results by the typed aid: hex prefix.
|
||||
# - Non-interactive only. We rely on Borg to fail fast without prompting in non-interactive contexts.
|
||||
# If it cannot, we simply return no suggestions.
|
||||
|
||||
# Name of the helper function inserted into the generated completion script(s)
|
||||
AID_BASH_FN_NAME = "_borg_complete_aid"
|
||||
AID_ZSH_FN_NAME = "_borg_complete_aid"
|
||||
from ..helpers import (
|
||||
archivename_validator,
|
||||
SortBySpec,
|
||||
FilesCacheMode,
|
||||
PathSpec,
|
||||
ChunkerParams,
|
||||
tag_validator,
|
||||
relative_time_marker_validator,
|
||||
parse_file_size,
|
||||
)
|
||||
from ..helpers.time import timestamp
|
||||
from ..compress import CompressionSpec
|
||||
from ..helpers.parseformat import partial_format
|
||||
from ..manifest import AI_HUMAN_SORT_KEYS
|
||||
|
||||
# Global bash preamble that is prepended to the generated completion script.
|
||||
# It aggregates only what we need:
|
||||
# - wordbreak fixes for ':' and '=' so tokens like 'aid:' and '--repo=/path' stay intact
|
||||
# - a minimal dynamic completion helper for aid: archive IDs
|
||||
BASH_PREAMBLE = r"""
|
||||
BASH_PREAMBLE_TMPL = r"""
|
||||
# keep ':' and '=' intact so tokens like 'aid:' and '--repo=/path' stay whole
|
||||
if [[ ${COMP_WORDBREAKS-} == *:* ]]; then COMP_WORDBREAKS=${COMP_WORDBREAKS//:}; fi
|
||||
if [[ ${COMP_WORDBREAKS-} == *=* ]]; then COMP_WORDBREAKS=${COMP_WORDBREAKS//=}; fi
|
||||
|
||||
# Complete aid:<hex-prefix> archive IDs by querying "borg repo-list --short"
|
||||
# Note: we only suggest the first 8 hex digits (short ID) for completion.
|
||||
_borg_complete_aid() {
|
||||
_borg_complete_archive() {
|
||||
local cur="${COMP_WORDS[COMP_CWORD]}"
|
||||
[[ "$cur" == aid:* ]] || return 0
|
||||
|
||||
local prefix="${cur#aid:}"
|
||||
[[ -n "$prefix" && ! "$prefix" =~ ^[0-9a-fA-F]*$ ]] && return 0
|
||||
|
||||
# derive repo context from words: --repo=V, --repo V, -r=V, -rV, or -r V
|
||||
local repo_arg=()
|
||||
|
|
@ -55,26 +97,248 @@ _borg_complete_aid() {
|
|||
fi
|
||||
done
|
||||
|
||||
# ask borg for raw IDs; avoid prompts and suppress stderr
|
||||
# Check if completing aid: prefix
|
||||
if [[ "$cur" == aid:* ]]; then
|
||||
local prefix="${cur#aid:}"
|
||||
[[ -n "$prefix" && ! "$prefix" =~ ^[0-9a-fA-F]*$ ]] && return 0
|
||||
|
||||
# ask borg for raw IDs; avoid prompts and suppress stderr
|
||||
local out
|
||||
if [[ -n "${repo_arg[*]}" ]]; then
|
||||
out=$( borg repo-list "${repo_arg[@]}" --format '{id}{NL}' 2>/dev/null </dev/null )
|
||||
else
|
||||
out=$( borg repo-list --format '{id}{NL}' 2>/dev/null </dev/null )
|
||||
fi
|
||||
[[ -z "$out" ]] && return 0
|
||||
|
||||
# filter by (case-insensitive) hex prefix and emit candidates
|
||||
local IFS=$'\n' id prelower idlower
|
||||
prelower="$(printf '%s' "$prefix" | tr '[:upper:]' '[:lower:]')"
|
||||
while IFS= read -r id; do
|
||||
[[ -z "$id" ]] && continue
|
||||
idlower="$(printf '%s' "$id" | tr '[:upper:]' '[:lower:]')"
|
||||
# Print only the first 8 hex digits of the ID for completion suggestions.
|
||||
[[ "$idlower" == "$prelower"* ]] && printf 'aid:%s\n' "${id:0:8}"
|
||||
done <<< "$out"
|
||||
else
|
||||
# Complete archive names
|
||||
local out
|
||||
if [[ -n "${repo_arg[*]}" ]]; then
|
||||
out=$( borg repo-list "${repo_arg[@]}" --format '{archive}{NL}' 2>/dev/null </dev/null )
|
||||
else
|
||||
out=$( borg repo-list --format '{archive}{NL}' 2>/dev/null </dev/null )
|
||||
fi
|
||||
[[ -z "$out" ]] && return 0
|
||||
|
||||
# filter by prefix and emit candidates
|
||||
local IFS=$'\n' name
|
||||
while IFS= read -r name; do
|
||||
[[ -z "$name" ]] && continue
|
||||
[[ -z "$cur" || "$name" == "$cur"* ]] && printf '%s\n' "$name"
|
||||
done <<< "$out"
|
||||
fi
|
||||
return 0
|
||||
}
|
||||
|
||||
# Complete compression spec options
|
||||
_borg_complete_compression_spec() {
|
||||
local choices="{COMP_SPEC_CHOICES}"
|
||||
local IFS=$' \t\n'
|
||||
compgen -W "${choices}" -- "$1"
|
||||
}
|
||||
|
||||
# Complete chunker params options
|
||||
_borg_complete_chunker_params() {
|
||||
local choices="{CHUNKER_PARAMS_CHOICES}"
|
||||
local IFS=$' \t\n'
|
||||
compgen -W "${choices}" -- "$1"
|
||||
}
|
||||
|
||||
# Complete tags from repository
|
||||
_borg_complete_tags() {
|
||||
local cur="${COMP_WORDS[COMP_CWORD]}"
|
||||
|
||||
# derive repo context from words: --repo=V, --repo V, -r=V, -rV, or -r V
|
||||
local repo_arg=()
|
||||
local i w
|
||||
for (( i=0; i<${#COMP_WORDS[@]}; i++ )); do
|
||||
w="${COMP_WORDS[i]}"
|
||||
if [[ "$w" == --repo=* ]]; then repo_arg=( --repo "${w#--repo=}" ); break
|
||||
elif [[ "$w" == -r=* ]]; then repo_arg=( -r "${w#-r=}" ); break
|
||||
elif [[ "$w" == -r* && "$w" != "-r" ]]; then repo_arg=( -r "${w#-r}" ); break
|
||||
elif [[ "$w" == "--repo" || "$w" == "-r" ]]; then
|
||||
if (( i+1 < ${#COMP_WORDS[@]} )); then repo_arg=( "$w" "${COMP_WORDS[i+1]}" ); fi
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
# ask borg for tags; avoid prompts and suppress stderr
|
||||
local out
|
||||
if [[ -n "${repo_arg[*]}" ]]; then
|
||||
out=$( borg repo-list "${repo_arg[@]}" --short 2>/dev/null </dev/null )
|
||||
out=$( borg repo-list "${repo_arg[@]}" --format '{tags}{NL}' 2>/dev/null </dev/null )
|
||||
else
|
||||
out=$( borg repo-list --short 2>/dev/null </dev/null )
|
||||
out=$( borg repo-list --format '{tags}{NL}' 2>/dev/null </dev/null )
|
||||
fi
|
||||
[[ -z "$out" ]] && return 0
|
||||
|
||||
# filter by (case-insensitive) hex prefix and emit candidates
|
||||
local IFS=$'\n' id prelower idlower
|
||||
prelower="$(printf '%s' "$prefix" | tr '[:upper:]' '[:lower:]')"
|
||||
while IFS= read -r id; do
|
||||
[[ -z "$id" ]] && continue
|
||||
idlower="$(printf '%s' "$id" | tr '[:upper:]' '[:lower:]')"
|
||||
# Print only the first 8 hex digits of the ID for completion suggestions.
|
||||
[[ "$idlower" == "$prelower"* ]] && printf 'aid:%s\n' "${id:0:8}"
|
||||
# extract unique tags and filter by prefix
|
||||
local IFS=$'\n' line tag
|
||||
local -A seen
|
||||
while IFS= read -r line; do
|
||||
[[ -z "$line" ]] && continue
|
||||
# tags are comma-separated, split and deduplicate
|
||||
IFS=',' read -ra tags <<< "$line"
|
||||
for tag in "${tags[@]}"; do
|
||||
tag="${tag# }"
|
||||
tag="${tag% }"
|
||||
[[ -z "$tag" ]] && continue
|
||||
[[ -n "${seen[$tag]}" ]] && continue
|
||||
seen[$tag]=1
|
||||
[[ -z "$cur" || "$tag" == "$cur"* ]] && printf '%s\n' "$tag"
|
||||
done
|
||||
done <<< "$out"
|
||||
return 0
|
||||
}
|
||||
|
||||
# Complete relative time markers
|
||||
_borg_complete_relative_time() {
|
||||
local choices="{RELATIVE_TIME_CHOICES}"
|
||||
local IFS=$' \t\n'
|
||||
compgen -W "${choices}" -- "$1"
|
||||
}
|
||||
|
||||
# Complete timestamp (file path or ISO timestamp)
|
||||
_borg_complete_timestamp() {
|
||||
local cur="${COMP_WORDS[COMP_CWORD]}"
|
||||
|
||||
# If starts with / or ., complete as file path
|
||||
if [[ "$cur" == /* || "$cur" == ./* || "$cur" == ../* || "$cur" == . || "$cur" == .. ]]; then
|
||||
compgen -f -- "$cur"
|
||||
else
|
||||
# Suggest current timestamp in ISO format
|
||||
date +"%Y-%m-%dT%H:%M:%S%z" | sed 's/\([0-9]\{2\}\)$/:\1/'
|
||||
fi
|
||||
}
|
||||
|
||||
# Complete file size values
|
||||
_borg_complete_file_size() {
|
||||
local choices="{FILE_SIZE_CHOICES}"
|
||||
local IFS=$' \t\n'
|
||||
compgen -W "${choices}" -- "$1"
|
||||
}
|
||||
|
||||
# Complete comma-separated sort keys for any option with type=SortBySpec.
|
||||
# Keys are validated against Borg's AI_HUMAN_SORT_KEYS.
|
||||
_borg_complete_sortby() {
|
||||
local cur="${COMP_WORDS[COMP_CWORD]}"
|
||||
|
||||
# Extract value part for --opt=value forms; otherwise the value is the word itself
|
||||
local val prefix_eq
|
||||
if [[ "$cur" == *=* ]]; then
|
||||
prefix_eq="${cur%%=*}="
|
||||
val="${cur#*=}"
|
||||
else
|
||||
prefix_eq=""
|
||||
val="$cur"
|
||||
fi
|
||||
|
||||
# Split into head (selected keys + trailing comma if any) and fragment (last token being typed)
|
||||
local head frag
|
||||
if [[ "$val" == *,* ]]; then
|
||||
head="${val%,*},"
|
||||
frag="${val##*,}"
|
||||
else
|
||||
head=""
|
||||
frag="$val"
|
||||
fi
|
||||
|
||||
# Build a comma-delimited list for cheap membership testing
|
||||
local headlist
|
||||
if [[ -n "$head" ]]; then
|
||||
headlist=",${head%,},"
|
||||
else
|
||||
headlist="," # nothing selected yet
|
||||
fi
|
||||
|
||||
# Valid keys (embedded at generation time)
|
||||
local keys=({SORT_KEYS})
|
||||
|
||||
local k
|
||||
for k in "${keys[@]}"; do
|
||||
# skip already-selected keys
|
||||
[[ "$headlist" == *",${k},"* ]] && continue
|
||||
# match prefix of last fragment
|
||||
[[ -n "$frag" && "$k" != "$frag"* ]] && continue
|
||||
printf '%s\n' "${prefix_eq}${head}${k}"
|
||||
done
|
||||
}
|
||||
|
||||
# Complete comma-separated files cache mode tokens for options with type=FilesCacheMode.
|
||||
_borg_complete_filescachemode() {
|
||||
local cur="${COMP_WORDS[COMP_CWORD]}"
|
||||
|
||||
# Extract value part for --opt=value forms; otherwise the value is the word itself
|
||||
local val prefix_eq
|
||||
if [[ "$cur" == *=* ]]; then
|
||||
prefix_eq="${cur%%=*}="
|
||||
val="${cur#*=}"
|
||||
else
|
||||
prefix_eq=""
|
||||
val="$cur"
|
||||
fi
|
||||
|
||||
# Split into head (selected keys + trailing comma if any) and fragment (last token being typed)
|
||||
local head frag
|
||||
if [[ "$val" == *,* ]]; then
|
||||
head="${val%,*},"
|
||||
frag="${val##*,}"
|
||||
else
|
||||
head=""
|
||||
frag="$val"
|
||||
fi
|
||||
|
||||
# Build a comma-delimited list for cheap membership testing
|
||||
local headlist
|
||||
if [[ -n "$head" ]]; then
|
||||
headlist=",${head%,},"
|
||||
else
|
||||
headlist="," # nothing selected yet
|
||||
fi
|
||||
|
||||
# Valid tokens (embedded at generation time)
|
||||
local keys=({FCM_KEYS})
|
||||
|
||||
# If 'disabled' is already selected, there is nothing else to suggest.
|
||||
if [[ "$headlist" == *",disabled,"* ]]; then
|
||||
return 0
|
||||
fi
|
||||
|
||||
local k
|
||||
for k in "${keys[@]}"; do
|
||||
# skip duplicates
|
||||
[[ "$headlist" == *",${k},"* ]] && continue
|
||||
# do not suggest 'disabled' if any other token is already selected
|
||||
if [[ -n "$head" && "$k" == "disabled" ]]; then
|
||||
continue
|
||||
fi
|
||||
# ctime/mtime are mutually exclusive: don't suggest the other if one is present
|
||||
if [[ "$k" == "ctime" && "$headlist" == *",mtime,"* ]]; then
|
||||
continue
|
||||
fi
|
||||
if [[ "$k" == "mtime" && "$headlist" == *",ctime,"* ]]; then
|
||||
continue
|
||||
fi
|
||||
# match prefix of last fragment
|
||||
[[ -n "$frag" && "$k" != "$frag"* ]] && continue
|
||||
printf '%s\n' "${prefix_eq}${head}${k}"
|
||||
done
|
||||
}
|
||||
|
||||
_borg_help_topics() {
|
||||
local choices="{HELP_CHOICES}"
|
||||
local IFS=$' \t\n'
|
||||
compgen -W "${choices}" -- "$1"
|
||||
}
|
||||
"""
|
||||
|
||||
|
||||
|
|
@ -84,17 +348,10 @@ _borg_complete_aid() {
|
|||
# - We use zsh's $words/$CURRENT arrays to inspect the command line.
|
||||
# - Candidates are returned via `compadd`.
|
||||
# - We try to detect repo context from --repo=V, --repo V, -r=V, -rV, -r V.
|
||||
ZSH_PREAMBLE = r"""
|
||||
# Complete aid:<hex-prefix> archive IDs by querying "borg repo-list --short"
|
||||
# Note: we only suggest the first 8 hex digits (short ID) for completion.
|
||||
_borg_complete_aid() {
|
||||
ZSH_PREAMBLE_TMPL = r"""
|
||||
_borg_complete_archive() {
|
||||
local cur
|
||||
cur="${words[$CURRENT]}"
|
||||
[[ "$cur" == aid:* ]] || return 0
|
||||
|
||||
local prefix="${cur#aid:}"
|
||||
# allow only hex digits as prefix; empty prefix also allowed (list all)
|
||||
[[ -n "$prefix" && ! "$prefix" == [0-9a-fA-F]# ]] && return 0
|
||||
|
||||
# derive repo context from words: --repo=V, --repo V, -r=V, -rV, or -r V
|
||||
local -a repo_arg=()
|
||||
|
|
@ -110,50 +367,291 @@ _borg_complete_aid() {
|
|||
fi
|
||||
done
|
||||
|
||||
# ask borg for raw IDs; avoid prompts and suppress stderr
|
||||
# Check if completing aid: prefix
|
||||
if [[ "$cur" == aid:* ]]; then
|
||||
local prefix="${cur#aid:}"
|
||||
# allow only hex digits as prefix; empty prefix also allowed (list all)
|
||||
[[ -n "$prefix" && ! "$prefix" == [0-9a-fA-F]# ]] && return 0
|
||||
|
||||
# ask borg for IDs with metadata; avoid prompts and suppress stderr
|
||||
# Use tab as delimiter to avoid issues with spaces in archive names
|
||||
local out
|
||||
if (( ${#repo_arg[@]} > 0 )); then
|
||||
out=$( borg repo-list "${repo_arg[@]}" --format '{id}{TAB}{archive}{TAB}{time}{TAB}{username}@{hostname}{NL}' \
|
||||
2>/dev/null </dev/null )
|
||||
else
|
||||
out=$( borg repo-list --format '{id}{TAB}{archive}{TAB}{time}{TAB}{username}@{hostname}{NL}' \
|
||||
2>/dev/null </dev/null )
|
||||
fi
|
||||
[[ -z "$out" ]] && return 0
|
||||
|
||||
# filter by (case-insensitive) hex prefix and build candidates with descriptions
|
||||
local prelower id idlower line
|
||||
prelower="${prefix:l}"
|
||||
local -a candidates=()
|
||||
local -a descriptions=()
|
||||
while IFS=$'\t' read -r id archive time userhost; do
|
||||
[[ -z "$id" ]] && continue
|
||||
idlower="${id:l}"
|
||||
if [[ "$idlower" == "$prelower"* ]]; then
|
||||
candidates+=( "aid:${id[1,8]}" )
|
||||
# Description: show full ID, archive name, time, user@host
|
||||
descriptions+=( "${id[1,8]}: ${archive} (${time} ${userhost})" )
|
||||
fi
|
||||
done <<< "$out"
|
||||
# -Q: do not escape special chars, -d: provide descriptions, -l: one per line
|
||||
compadd -Q -l -d descriptions -- $candidates
|
||||
else
|
||||
# Complete archive names
|
||||
local out
|
||||
if (( ${#repo_arg[@]} > 0 )); then
|
||||
out=$( borg repo-list "${repo_arg[@]}" --format '{archive}{NL}' 2>/dev/null </dev/null )
|
||||
else
|
||||
out=$( borg repo-list --format '{archive}{NL}' 2>/dev/null </dev/null )
|
||||
fi
|
||||
[[ -z "$out" ]] && return 0
|
||||
|
||||
# filter by prefix and emit candidates
|
||||
local -a candidates=()
|
||||
local name
|
||||
for name in ${(f)out}; do
|
||||
[[ -z "$name" ]] && continue
|
||||
if [[ -z "$cur" || "$name" == "$cur"* ]]; then
|
||||
candidates+=( "$name" )
|
||||
fi
|
||||
done
|
||||
compadd -Q -- $candidates
|
||||
fi
|
||||
return 0
|
||||
}
|
||||
|
||||
# Complete compression spec options
|
||||
_borg_complete_compression_spec() {
|
||||
local choices=({COMP_SPEC_CHOICES})
|
||||
# use compadd -V to preserve order (do not sort)
|
||||
compadd -V 'compression algorithms' -Q -a choices
|
||||
}
|
||||
|
||||
# Complete chunker params options
|
||||
_borg_complete_chunker_params() {
|
||||
local choices=({CHUNKER_PARAMS_CHOICES})
|
||||
# use compadd -V to preserve order (do not sort)
|
||||
compadd -V 'chunker params' -Q -a choices
|
||||
}
|
||||
|
||||
# Complete tags from repository
|
||||
_borg_complete_tags() {
|
||||
local cur
|
||||
cur="${words[$CURRENT]}"
|
||||
|
||||
# derive repo context from words: --repo=V, --repo V, -r=V, -rV, or -r V
|
||||
local -a repo_arg=()
|
||||
local i w
|
||||
for i in {1..$#words}; do
|
||||
w="$words[$i]"
|
||||
if [[ "$w" == --repo=* ]]; then repo_arg=( --repo "${w#--repo=}" ); break
|
||||
elif [[ "$w" == -r=* ]]; then repo_arg=( -r "${w#-r=}" ); break
|
||||
elif [[ "$w" == -r* && "$w" != "-r" ]]; then repo_arg=( -r "${w#-r}" ); break
|
||||
elif [[ "$w" == "--repo" || "$w" == "-r" ]]; then
|
||||
if (( i+1 <= $#words )); then repo_arg=( "$w" "${words[$((i+1))]}" ); fi
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
# ask borg for tags; avoid prompts and suppress stderr
|
||||
local out
|
||||
if (( ${#repo_arg[@]} > 0 )); then
|
||||
out=$( borg repo-list "${repo_arg[@]}" --short 2>/dev/null </dev/null )
|
||||
out=$( borg repo-list "${repo_arg[@]}" --format '{tags}{NL}' 2>/dev/null </dev/null )
|
||||
else
|
||||
out=$( borg repo-list --short 2>/dev/null </dev/null )
|
||||
out=$( borg repo-list --format '{tags}{NL}' 2>/dev/null </dev/null )
|
||||
fi
|
||||
[[ -z "$out" ]] && return 0
|
||||
|
||||
# filter by (case-insensitive) hex prefix and emit candidates
|
||||
local prelower id idlower
|
||||
prelower="${prefix:l}"
|
||||
# extract unique tags and filter by prefix
|
||||
local line tag
|
||||
local -A seen
|
||||
local -a candidates=()
|
||||
for id in ${(f)out}; do
|
||||
[[ -z "$id" ]] && continue
|
||||
idlower="${id:l}"
|
||||
if [[ "$idlower" == "$prelower"* ]]; then
|
||||
candidates+=( "aid:${id[1,8]}" )
|
||||
fi
|
||||
for line in ${(f)out}; do
|
||||
[[ -z "$line" ]] && continue
|
||||
# tags are comma-separated, split and deduplicate
|
||||
for tag in ${(s:,:)line}; do
|
||||
tag="${tag## }"
|
||||
tag="${tag%% }"
|
||||
[[ -z "$tag" ]] && continue
|
||||
[[ -n "${seen[$tag]}" ]] && continue
|
||||
seen[$tag]=1
|
||||
if [[ -z "$cur" || "$tag" == "$cur"* ]]; then
|
||||
candidates+=( "$tag" )
|
||||
fi
|
||||
done
|
||||
done
|
||||
# -Q: do not escape special chars, so ':' remains as-is
|
||||
compadd -Q -- $candidates
|
||||
return 0
|
||||
}
|
||||
|
||||
# Complete relative time markers
|
||||
_borg_complete_relative_time() {
|
||||
local choices=({RELATIVE_TIME_CHOICES})
|
||||
# use compadd -V to preserve order (do not sort)
|
||||
compadd -V 'relative time' -Q -a choices
|
||||
}
|
||||
|
||||
# Complete timestamp (file path or ISO timestamp)
|
||||
_borg_complete_timestamp() {
|
||||
local cur
|
||||
cur="${words[$CURRENT]}"
|
||||
|
||||
# If starts with / or ., complete as file path
|
||||
if [[ "$cur" == /* || "$cur" == ./* || "$cur" == ../* || "$cur" == . || "$cur" == .. ]]; then
|
||||
_files
|
||||
else
|
||||
# Suggest current timestamp in ISO format
|
||||
local timestamp
|
||||
timestamp=$(date +"%Y-%m-%dT%H:%M:%S%z" | sed 's/\([0-9]\{2\}\)$/:\1/')
|
||||
compadd -Q -- "$timestamp"
|
||||
fi
|
||||
}
|
||||
|
||||
# Complete file size values
|
||||
_borg_complete_file_size() {
|
||||
local choices=({FILE_SIZE_CHOICES})
|
||||
# use compadd -V to preserve order (do not sort)
|
||||
compadd -V 'file size' -Q -a choices
|
||||
}
|
||||
|
||||
# Complete comma-separated sort keys for any option with type=SortBySpec.
|
||||
_borg_complete_sortby() {
|
||||
local cur
|
||||
cur="${words[$CURRENT]}"
|
||||
|
||||
local val prefix_eq
|
||||
if [[ "$cur" == *"="* ]]; then
|
||||
prefix_eq="${cur%%\=*}="
|
||||
val="${cur#*=}"
|
||||
else
|
||||
prefix_eq=""
|
||||
val="$cur"
|
||||
fi
|
||||
|
||||
local head frag
|
||||
if [[ "$val" == *","* ]]; then
|
||||
head="${val%,*},"
|
||||
frag="${val##*,}"
|
||||
else
|
||||
head=""
|
||||
frag="$val"
|
||||
fi
|
||||
|
||||
local headlist
|
||||
if [[ -n "$head" ]]; then
|
||||
headlist=",${head%,},"
|
||||
else
|
||||
headlist="," # nothing selected yet
|
||||
fi
|
||||
|
||||
# Valid keys (embedded at generation time)
|
||||
local -a keys=({SORT_KEYS})
|
||||
|
||||
local -a candidates=()
|
||||
local k
|
||||
for k in ${keys[@]}; do
|
||||
[[ "$headlist" == *",${k},"* ]] && continue
|
||||
[[ -n "$frag" && "$k" != "$frag"* ]] && continue
|
||||
candidates+=( "${prefix_eq}${head}${k}" )
|
||||
done
|
||||
compadd -Q -- $candidates
|
||||
return 0
|
||||
}
|
||||
|
||||
# Complete comma-separated files cache mode tokens for options with type=FilesCacheMode.
|
||||
_borg_complete_filescachemode() {
|
||||
local cur
|
||||
cur="${words[$CURRENT]}"
|
||||
|
||||
local val prefix_eq
|
||||
if [[ "$cur" == *"="* ]]; then
|
||||
prefix_eq="${cur%%\=*}="
|
||||
val="${cur#*=}"
|
||||
else
|
||||
prefix_eq=""
|
||||
val="$cur"
|
||||
fi
|
||||
|
||||
local head frag
|
||||
if [[ "$val" == *","* ]]; then
|
||||
head="${val%,*},"
|
||||
frag="${val##*,}"
|
||||
else
|
||||
head=""
|
||||
frag="$val"
|
||||
fi
|
||||
|
||||
local headlist
|
||||
if [[ -n "$head" ]]; then
|
||||
headlist=",${head%,},"
|
||||
else
|
||||
headlist="," # nothing selected yet
|
||||
fi
|
||||
|
||||
# Valid tokens (embedded at generation time)
|
||||
local -a keys=({FCM_KEYS})
|
||||
|
||||
# If 'disabled' is already selected, there is nothing else to suggest.
|
||||
if [[ "$headlist" == *",disabled,"* ]]; then
|
||||
return 0
|
||||
fi
|
||||
|
||||
local -a candidates=()
|
||||
local k
|
||||
for k in ${keys[@]}; do
|
||||
[[ "$headlist" == *",${k},"* ]] && continue
|
||||
if [[ -n "$head" && "$k" == "disabled" ]]; then
|
||||
continue
|
||||
fi
|
||||
if [[ "$k" == "ctime" && "$headlist" == *",mtime,"* ]]; then
|
||||
continue
|
||||
fi
|
||||
if [[ "$k" == "mtime" && "$headlist" == *",ctime,"* ]]; then
|
||||
continue
|
||||
fi
|
||||
[[ -n "$frag" && "$k" != "$frag"* ]] && continue
|
||||
candidates+=( "${prefix_eq}${head}${k}" )
|
||||
done
|
||||
compadd -Q -- $candidates
|
||||
return 0
|
||||
}
|
||||
|
||||
_borg_help_topics() {
|
||||
local choices=({HELP_CHOICES})
|
||||
_describe 'help topics' choices
|
||||
}
|
||||
"""
|
||||
|
||||
|
||||
def _attach_aid_completion(parser: argparse.ArgumentParser):
|
||||
"""Tag all arguments that accept an ARCHIVE with aid:-completion.
|
||||
|
||||
We detect ARCHIVE arguments by their type being archivename_validator.
|
||||
This function mutates the parser actions to add a .complete mapping used by shtab.
|
||||
"""
|
||||
def _attach_completion(parser: argparse.ArgumentParser, type_class, completion_dict: dict):
|
||||
"""Tag all arguments with type `type_class` with completion choices from `completion_dict`."""
|
||||
|
||||
for action in parser._actions:
|
||||
# Recurse into subparsers
|
||||
if isinstance(action, argparse._SubParsersAction):
|
||||
for sub in action.choices.values():
|
||||
_attach_aid_completion(sub)
|
||||
_attach_completion(sub, type_class, completion_dict)
|
||||
continue
|
||||
|
||||
# Assign dynamic completion only for arguments that take an archive name.
|
||||
if action.type is archivename_validator:
|
||||
action.complete = {"bash": AID_BASH_FN_NAME, "zsh": AID_ZSH_FN_NAME} # type: ignore[attr-defined]
|
||||
if action.type is type_class:
|
||||
action.complete = completion_dict # type: ignore[attr-defined]
|
||||
|
||||
|
||||
def _attach_help_completion(parser: argparse.ArgumentParser, completion_dict: dict):
|
||||
"""Tag the 'topic' argument of the 'help' command with static completion choices."""
|
||||
for action in parser._actions:
|
||||
if isinstance(action, argparse._SubParsersAction):
|
||||
for sub in action.choices.values():
|
||||
_attach_help_completion(sub, completion_dict)
|
||||
continue
|
||||
|
||||
if action.dest == "topic":
|
||||
action.complete = completion_dict # type: ignore[attr-defined]
|
||||
|
||||
|
||||
class CompletionMixIn:
|
||||
|
|
@ -164,8 +662,77 @@ class CompletionMixIn:
|
|||
# arguments (identified by archivename_validator). It reuses `borg repo-list`
|
||||
# to enumerate archives and does not introduce any new commands or caching.
|
||||
parser = self.build_parser()
|
||||
_attach_aid_completion(parser)
|
||||
preamble = {"bash": BASH_PREAMBLE, "zsh": ZSH_PREAMBLE}
|
||||
_attach_completion(
|
||||
parser, archivename_validator, {"bash": "_borg_complete_archive", "zsh": "_borg_complete_archive"}
|
||||
)
|
||||
_attach_completion(parser, SortBySpec, {"bash": "_borg_complete_sortby", "zsh": "_borg_complete_sortby"})
|
||||
_attach_completion(
|
||||
parser, FilesCacheMode, {"bash": "_borg_complete_filescachemode", "zsh": "_borg_complete_filescachemode"}
|
||||
)
|
||||
_attach_completion(
|
||||
parser,
|
||||
CompressionSpec,
|
||||
{"bash": "_borg_complete_compression_spec", "zsh": "_borg_complete_compression_spec"},
|
||||
)
|
||||
_attach_completion(parser, PathSpec, shtab.DIRECTORY)
|
||||
_attach_completion(
|
||||
parser, ChunkerParams, {"bash": "_borg_complete_chunker_params", "zsh": "_borg_complete_chunker_params"}
|
||||
)
|
||||
_attach_completion(parser, tag_validator, {"bash": "_borg_complete_tags", "zsh": "_borg_complete_tags"})
|
||||
_attach_completion(
|
||||
parser,
|
||||
relative_time_marker_validator,
|
||||
{"bash": "_borg_complete_relative_time", "zsh": "_borg_complete_relative_time"},
|
||||
)
|
||||
_attach_completion(parser, timestamp, {"bash": "_borg_complete_timestamp", "zsh": "_borg_complete_timestamp"})
|
||||
_attach_completion(
|
||||
parser, parse_file_size, {"bash": "_borg_complete_file_size", "zsh": "_borg_complete_file_size"}
|
||||
)
|
||||
|
||||
# Collect all commands and help topics for "borg help" completion
|
||||
help_choices = list(self.helptext.keys())
|
||||
for action in parser._actions:
|
||||
if isinstance(action, argparse._SubParsersAction):
|
||||
help_choices.extend(action.choices.keys())
|
||||
|
||||
help_completion_fn = "_borg_help_topics"
|
||||
_attach_help_completion(parser, {"bash": help_completion_fn, "zsh": help_completion_fn})
|
||||
|
||||
# Build preambles using partial_format to avoid escaping braces etc.
|
||||
sort_keys = " ".join(AI_HUMAN_SORT_KEYS)
|
||||
fcm_keys = " ".join(["ctime", "mtime", "size", "inode", "rechunk", "disabled"]) # keep in sync with parser
|
||||
|
||||
# Help completion templates
|
||||
help_choices = " ".join(sorted(help_choices))
|
||||
|
||||
# Compression spec choices (static list)
|
||||
comp_spec_choices = ["lz4", "zstd,3", "auto,zstd,10", "zlib,6", "lzma,6", "obfuscate,250,lz4", "none"]
|
||||
comp_spec_choices_str = " ".join(comp_spec_choices)
|
||||
|
||||
# Chunker params choices (static list)
|
||||
chunker_params_choices = ["default", "fixed,4194304", "buzhash,19,23,21,4095", "buzhash64,19,23,21,4095"]
|
||||
chunker_params_choices_str = " ".join(chunker_params_choices)
|
||||
|
||||
# Relative time marker choices (static list)
|
||||
relative_time_choices = ["60S", "60M", "24H", "7d", "4w", "12m", "1000y"]
|
||||
relative_time_choices_str = " ".join(relative_time_choices)
|
||||
|
||||
# File size choices (static list)
|
||||
file_size_choices = ["500M", "1G", "10G", "100G", "1T"]
|
||||
file_size_choices_str = " ".join(file_size_choices)
|
||||
|
||||
mapping = {
|
||||
"SORT_KEYS": sort_keys,
|
||||
"FCM_KEYS": fcm_keys,
|
||||
"COMP_SPEC_CHOICES": comp_spec_choices_str,
|
||||
"CHUNKER_PARAMS_CHOICES": chunker_params_choices_str,
|
||||
"RELATIVE_TIME_CHOICES": relative_time_choices_str,
|
||||
"FILE_SIZE_CHOICES": file_size_choices_str,
|
||||
"HELP_CHOICES": help_choices,
|
||||
}
|
||||
bash_preamble = partial_format(BASH_PREAMBLE_TMPL, mapping)
|
||||
zsh_preamble = partial_format(ZSH_PREAMBLE_TMPL, mapping)
|
||||
preamble = {"bash": bash_preamble, "zsh": zsh_preamble}
|
||||
script = shtab.complete(parser, shell=args.shell, preamble=preamble) # nosec B604
|
||||
print(script)
|
||||
|
||||
|
|
|
|||
|
|
@ -536,7 +536,9 @@ class HelpMixIn:
|
|||
do_maincommand_help = do_subcommand_help
|
||||
|
||||
def build_parser_help(self, subparsers, common_parser, mid_common_parser, parser):
|
||||
subparser = subparsers.add_parser("help", parents=[common_parser], add_help=False, description="Extra help")
|
||||
subparser = subparsers.add_parser(
|
||||
"help", parents=[common_parser], add_help=False, description="Extra help", help="Extra help"
|
||||
)
|
||||
subparser.add_argument("--epilog-only", dest="epilog_only", action="store_true")
|
||||
subparser.add_argument("--usage-only", dest="usage_only", action="store_true")
|
||||
subparser.set_defaults(func=functools.partial(self.do_help, parser, subparsers.choices))
|
||||
|
|
|
|||
|
|
@ -349,6 +349,7 @@ class TransferMixIn:
|
|||
metavar="UPGRADER",
|
||||
dest="upgrader",
|
||||
type=str,
|
||||
choices=("NoOp", "From12To20"),
|
||||
default="NoOp",
|
||||
action=Highlander,
|
||||
help="use the upgrader to convert transferred data (default: no conversion)",
|
||||
|
|
|
|||
|
|
@ -7,11 +7,15 @@ def test_bash_completion(archivers, request):
|
|||
"""Ensure the generated Bash completion includes our helper."""
|
||||
archiver = request.getfixturevalue(archivers)
|
||||
output = cmd(archiver, "completion", "bash")
|
||||
assert "_borg_complete_aid() {" in output
|
||||
assert "_borg_complete_archive() {" in output
|
||||
assert "_borg_complete_sortby() {" in output
|
||||
assert "_borg_complete_filescachemode() {" in output
|
||||
|
||||
|
||||
def test_zsh_completion(archivers, request):
|
||||
"""Ensure the generated Zsh completion includes our helper."""
|
||||
archiver = request.getfixturevalue(archivers)
|
||||
output = cmd(archiver, "completion", "zsh")
|
||||
assert "_borg_complete_aid() {" in output
|
||||
assert "_borg_complete_archive() {" in output
|
||||
assert "_borg_complete_sortby() {" in output
|
||||
assert "_borg_complete_filescachemode() {" in output
|
||||
|
|
|
|||
Loading…
Reference in a new issue