Metadata-Version: 2.4
Name: git-back-dots
Version: 0.1.0
Summary: TUI for managing git-backed configuration backups on CachyOS/Arch
Project-URL: Repository, https://github.com/boundring/git-back-dots
Author: boundring
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: backup,dotfiles,etc,git,systemd,tui
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Archiving :: Backup
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: textual>=3.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

```sh
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:

```sh
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:

```sh
uv tool install git-back-dots
```

For an unreleased GitHub checkout:

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

## Commands

```sh
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:

```sh
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

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

## License

GPL-3.0-only. See [LICENSE](LICENSE).
