Imported from egustafson/cfgr (AGENTS.md). Install upstream with npx skills add egustafson/cfgr. Copyright stays with the author.

cfgr — Agent Guidelines

Project Summary

cfgr is a Click-based CLI tool for managing OS configuration files under version control. It bridges a source directory (versioned) and a target directory (deployed location), providing diff, push, pull, and init commands.

Build & Test

# Install / sync dependencies
uv sync

# Lint + test (must pass before every commit)
make pre-release

# Individual steps
uv run ruff check . && uv run ruff format --check .
uv run pytest tests

All source files are formatted with ruff (line length 100). Run uv run ruff format <file> to auto-fix formatting issues.

Module Responsibilities

CLI Commands

.cfgr.yml Schema

The config file lives inside the source directory — that directory is implicitly the source root. target must be an absolute path.

target: /etc          # required; absolute path to the deployed location
hostname: myhost      # optional; short or FQDN — diff warns, push/pull abort on mismatch
include:              # optional allowlist (gitignore patterns); evaluated before ignore
  - subdir/
ignore:               # optional denylist (gitignore patterns); evaluated after include
  - logs/
  - "*.bak"

Child configs in source subdirectories may have include and ignore; target is forbidden and raises an error.

Key Design Decisions

• --force on push/pull requires explicit file paths (UsageError otherwise).
• --force on an ignored file triggers click.confirm to remove the pattern from .cfgr.yml.
• ops.get_tracked_pairs returns the union of source and target files so target-only files appear in diff.
• .cfgr.yml files are excluded from tracked pairs.
• FileTree in filetree.py has no ignore awareness — do not add it without a specific reason.
• Hostname matching is liberal: only the first dot-separated component is compared, case-insensitively.

Test Conventions

• All filesystem tests use tmp_path and copy test_data/ via _setup(tmp_path).
• _setup rewrites .cfgr.yml with an absolute target path and returns the source dir path.
• Pass the source dir as the working directory: runner.invoke(cli, ["-d", wd, ...]).
• Source file paths: os.path.join(wd, "base.ini")
• Target file paths: os.path.normpath(os.path.join(wd, "..", "target", "base.ini"))
• test_about contains a hard-coded version assertion — update it on every release.

Release Process

1. Move [Unreleased] content to [X.Y.Z] - YYYY-MM-DD in CHANGELOG.md.
2. Add an empty [Unreleased] section above it.
3. Update comparison links at the bottom of CHANGELOG.md.
4. Bump version in pyproject.toml.
5. Update the version string in test_about in tests/test_cfgr.py.
6. Run uv sync to reinstall the package at the new version.
7. Run make pre-release — must be green.
8. Commit: git add -A && git commit -m "release: prepare vX.Y.Z ...".
9. Tag separately when ready to publish.

Commit Policy

Never commit automatically. Only run git commit when the user explicitly asks.

Commit messages should be short and to the point. If more detail is needed, reference the CHANGELOG.md rather than embedding a long description in the commit message.