git-back-dots 0.2.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 scan packages      # pacman-aware config suggestions per naming schema
gbd repo suggest       # turn package suggestions into snapshot repos
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 workaround add NAME --target PATH   # track a live patch
gbd workaround check                    # drift report (exit 1 when stale)
gbd workaround apply NAME               # re-apply now

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.

Repository naming schema

Prefix	Scope	Use
dots-<pkg>	user	dotfiles owned by a package
etc-<pkg>	system	package-owned system configuration
etc-base	system	the whole /etc tree (inplace)
wa-<name>	any	workaround repos (see below)

Workarounds

A workaround is a live patch applied to another tool's files — for example a hotfix inside an installed application that its next update will clobber. git-back-dots tracks the patched files in a dedicated snapshot repo under ~/.local/share/git-back-dots/workarounds/<name>/, generates an idempotent apply.sh, and can re-apply automatically:

gbd workaround add my-fix --target ~/.local/lib/tool/patched.py
gbd workaround schedule my-fix   # path unit watches the live file

The path unit fires when the target changes. The runner then checks drift: if the live file differs from the snapshot (the update clobbered the patch), apply.sh installs the tracked copy back before committing — the repo always records the patched state. Your own edits are safe: the runner syncs them into the snapshot on the same pass, so intentional changes are committed, not reverted. Disable with --no-auto and apply manually with gbd workaround apply NAME.

apply.sh runs as the installing user (via sudo -E for --system workarounds). It is generated from the repo and committed to git history — review it like any other privileged script. Keep workaround repos private if the patched files come from proprietary or third-party source.

Packages

gbd scan packages combines a well-known profile list (Emacs, KDE/Plasma, fish, common AI CLIs, …) with an /etc sweep over everything pacman has installed. Library, framework, and game packages are filtered out by default; --all shows them dimmed, and ignore_packages in the config extends the filter. AI-CLI profiles are explicit allowlists — auth tokens, session databases, and history files are never tracked, and the pre-commit secret scanner is the backstop.

gbd repo suggest --apply registers the suggestions as snapshot repos using the naming schema above.

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.