feat: add bash completionHEADmaster

Completes the flags, and directories for --archive-dir in both the
--opt value and --opt=value forms. --target offers only "me": real chat
handles would need a network round-trip inside a tab press, and
--list-chats already answers that question.

Installed by hand, nothing automates it. A new flag has to be added to
opts in the completion as well.

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

3 files changed, 52 insertions, 1 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index e0fb0e1..f55e570 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this is
 
-Single-file Python script (`tg_backup.py`, ~115 lines) that incrementally downloads media (photos + documents) from a Telegram chat/group via Telethon. No package, no tests, no build step. Keep it single-file unless there is a real reason not to.
+Single-file Python script (`tg_backup.py`) that incrementally downloads media (photos + documents) from a Telegram chat/group via Telethon. No package, no tests, no build step. Keep it single-file unless there is a real reason not to.
+
+`tg_backup.bash-completion` sits alongside it: an optional bash completion for the flags, with directory completion for `--archive-dir` (both `--opt value` and `--opt=value` forms) and no completion for `--target`, which would need a network round-trip. It relies on `_filedir` from the bash-completion package. Installed by hand to `/usr/share/bash-completion/completions/tg_backup.py`; nothing automates that. Adding a flag to the script means adding it to `opts` there too.
 
 Dependency: `telethon` only.
 
diff --git a/README.md b/README.md
index 29c7521..05707ea 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,15 @@ pip install telethon
 cp tg_backup.py ~/bin/ && chmod +x ~/bin/tg_backup.py
 ```
 
+Tab completion for the options, if you want it:
+
+```bash
+sudo install -m 644 tg_backup.bash-completion \
+    /usr/share/bash-completion/completions/tg_backup.py
+```
+
+Without root, `source` that file from your `~/.bashrc` instead. It completes flags and directories for `--archive-dir`; chat targets are not completed, since listing them needs a network round-trip.
+
 ## Setup
 
 Run it once with no arguments to create the config:
@@ -116,6 +125,7 @@ Only media is saved. Message text and captions are not.
 | `<archive-dir>/state.json` | Resume position and saved target for that chat |
 | `<archive-dir>/failures.json` | Message IDs whose media never downloaded |
 | `<archive-dir>/*` | Downloaded media |
+| `/usr/share/bash-completion/completions/tg_backup.py` | Tab completion, if installed |
 
 The session file is account credentials: anyone holding it can read your Telegram. It is created mode `0600` inside a `0700` directory. Keep it out of version control and off shared storage.
 
diff --git a/tg_backup.bash-completion b/tg_backup.bash-completion
new file mode 100644
index 0000000..5aca64f
--- /dev/null
+++ b/tg_backup.bash-completion
@@ -0,0 +1,39 @@
+#   bash completion for tg_backup.py
+#
+#   Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+#
+#   This program is free software; you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License version 2 as
+#   published by the Free Software Foundation.
+
+_tg_backup() {
+    local cur prev opts
+    cur=${COMP_WORDS[COMP_CWORD]}
+    prev=${COMP_WORDS[COMP_CWORD-1]}
+    opts="--target --archive-dir --list-chats --force-target --self-check --help"
+
+    # --archive-dir takes a directory. Handles both "--archive-dir <tab>" and
+    # the --opt=value form, where bash leaves the = in prev.
+    case $prev in
+        --archive-dir)
+            _filedir -d
+            return
+            ;;
+    esac
+    if [[ $cur == --archive-dir=* ]]; then
+        cur=${cur#--archive-dir=}
+        _filedir -d
+        return
+    fi
+
+    # --target is a chat: no local source of completions without hitting the
+    # network, so offer only the one value that is not chat-specific.
+    if [[ $prev == --target || $cur == --target=* ]]; then
+        [[ $cur == --target=* ]] && cur=${cur#--target=}
+        COMPREPLY=($(compgen -W "me" -- "$cur"))
+        return
+    fi
+
+    COMPREPLY=($(compgen -W "$opts" -- "$cur"))
+}
+complete -F _tg_backup tg_backup.py tg_backup