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