git-back-dots 0.1.0

TUI for managing git-backed configuration backups on CachyOS/Arch

git-back-dots

Git-backed configuration backups for CachyOS and Arch Linux.

git-back-dots discovers configuration files, groups them by package or component, and manages git repos with a Textual terminal UI. It has a headless runner for systemd timers, path triggers, and shutdown commits.

This is an early development build. Discovery, the git runner, logging, scheduling, environment-token detection, snapshot repositories, and the core TUI all work and are covered by tests. The GitHub/Codeberg account-creation flow and branch-merge UI are not finished yet.

Repository modes

inplace — the git root contains the tracked files. /etc is the canonical example: gbd run etc commits changes directly inside /etc. Use this for system configuration trees.

snapshot — a managed repo stores copies of scattered source files under a deterministic files/… tree. Before every commit the runner syncs each tracked source into the snapshot; restore copies back atomically. Use this for dotfiles and package configs that live anywhere on disk.

gbd repo add dots ~/.local/share/git-back-dots/dots --mode snapshot \
    --track ~/.config/fish/config.fish --track ~/.bashrc
gbd run dots --mode commit
gbd repo restore dots ~/.config/fish/config.fish

Install

For the checkout being developed here:

cd ~/Projects/etc/20260725/git-back-dots
uv tool install --editable .

That installs gbd and git-back-dots into uv's tool bin directory. Once a public release exists, install with:

uv tool install git-back-dots

For an unreleased GitHub checkout:

uv tool install git+https://github.com/boundring/git-back-dots.git

Commands

gbd                    # launch the TUI
gbd doctor             # git, systemd, ssh-key, PAT, and registry checks
gbd scan etc           # discover /etc candidates and package owners
gbd scan home          # discover dotfiles and ~/.config candidates
gbd auth env           # detect GITHUB_TOKEN, GH_TOKEN, CODEBERG_TOKEN
gbd auth ssh           # list public keys and test provider SSH auth
gbd repo list          # show registered repositories
gbd run NAME --mode push

gbd run is the command generated systemd units execute. It commits only when the repo is dirty, then pushes with BatchMode SSH and hard timeouts.

Authentication

Authentication sources are resolved in this order:

1. SSH remotes and local SSH authentication.
2. Provider PATs in the current process environment.
3. Tokens stored through the system keyring, falling back to an owner-only file.

GitHub environment variables: GITHUB_TOKEN, then GH_TOKEN.

Codeberg environment variables: CODEBERG_TOKEN, then GITEA_TOKEN.

gbd auth env masks token values and only prints the final four characters. Tokens are never put in a remote URL or written to the run journal.

System services do not inherit your login environment. For root-owned repos, use a root-owned SSH key and SSH remote. The system registry is copied to /etc/git-back-dots/config.toml during schedule installation; it contains repo metadata only, never PAT values.

Scheduling model

Per repo, git-back-dots generates:

• a delayed boot/interval timer that runs push after networking is available;
• an optional PathChanged= unit for selected hot files;
• a shutdown service that performs a local commit only.

The shutdown unit never attempts a network push. A later timer or the next boot sends the committed change. Pushes use a 15-second limit and SSH batch mode, so they cannot request a password or hang indefinitely.

Validate the generated units before installing them:

gbd schedule install NAME
systemctl --user list-timers 'gbd-*'       # user repos
systemctl list-timers 'gbd-*'              # system repos
journalctl -t git-back-dots

Current limits

• A timer can fire while a file is mid-edit; git commits whatever bytes are on disk. Inherent to any file-based backup — prefer quiescent times (boot, shutdown, idle intervals) for system repos.
• GitHub and Codeberg API support, PAT discovery, and OAuth device-flow primitives exist. OAuth requires a registered provider client ID (GBD_GITHUB_CLIENT_ID or GBD_CODEBERG_CLIENT_ID). The account-creation UI and HTTPS credential injection for git pushes are not wired yet — use SSH remotes or env-var PATs for now.
• The TUI includes dashboard, discovery, repo files/history/schedule views, accounts, logs, notifications, and a per-file history browser with restore-from-any-version. Branch merge UI is still planned.
• The project is not published to PyPI yet; uv tool install git-back-dots will work after publishing.

Development

uv sync --extra dev
uv run ruff check src/ tests/
uv run pytest tests/ -q
uv build

License

GPL-3.0-only. See LICENSE.