🚧 WIP

2026-09-12 09:01:14 +02:00
parent e8d6e70f42
commit 17b8525de1
38 changed files with 3247 additions and 57 deletions
@@ -0,0 +1,65 @@
+# git-auto-tracker
+
+Unattended change tracker that records modifications to SCADA project and
+configuration files in a Git repository.
+
+The tracker periodically inspects a configured repository, detects
+added / modified / deleted files, resolves the last modifying user for each
+change (where a metadata source is available), and creates one Git commit per
+collection cycle with a structured, auditable commit message.
+
+See `functional specification.md` for the full specification.
+
+## Features
+
+- Run-once execution, designed for Windows Task Scheduler / cron / systemd timers
+- Change detection via `git status --porcelain -z` (NUL-safe, UTF-8)
+- Configurable include/exclude file filters (globs)
+- Security validation with forbidden patterns (abort by default)
+- Pluggable author resolvers with priority chain and confidence levels
+- Per-file attribution recorded in the commit message
+- Structured commit trailers (`Tracker-Run`, `Tracker-Host`, ...)
+- Repository-level lock with stale-lock detection (stored outside the repo)
+- Rotating file logs plus console logging
+- Dry-run mode, exit codes suitable for external monitoring
+- Cross-platform: Windows / Linux / macOS
+
+## Installation
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate   # Windows
+source .venv/bin/activate  # Linux/macOS
+pip install -e .
+```
+
+## Usage
+
+```bash
+git-auto-tracker run [--dry-run]   # collect changes and commit
+git-auto-tracker status            # show detected changes without committing
+git-auto-tracker validate          # validate configuration / repository / resolvers
+git-auto-tracker config            # print effective configuration
+```
+
+Global options:
+
+```text
+--config PATH      Path to configuration file (default: git-auto-tracker.yaml)
+--log-level LEVEL  Override the configured log level
+--version          Print version and exit
+```
+
+## Configuration
+
+See [`config/example.yaml`](config/example.yaml). Configuration is YAML;
+deployment-specific values can be overridden through environment variables
+using the `GIT_AUTO_TRACKER_<SECTION>__<KEY>` convention.
+
+## Development
+
+```bash
+pip install -e . --group dev
+pytest
+ruff check src tests
+```