Metadata-Version: 2.4
Name: giton
Version: 0.1.11
Summary: Local AI layer for git: orchestrates policies & plugins between commit and push.
Author: semcod
Author-email: Tom Sapletta <tom@sapletta.com>
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: costs>=0.1.20; extra == 'dev'
Requires-Dist: goal>=2.1.0; extra == 'dev'
Requires-Dist: pfix>=0.1.60; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# giton


## AI Cost Tracking

![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.11-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.98-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-3.5h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)

- 🤖 **LLM usage:** $0.9799 (12 commits)
- 👤 **Human dev:** ~$345 (3.5h @ $100/h, 30min dedup)

Generated on 2026-05-27 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)

---

`giton` is a local AI layer for Git that works between `commit` and `push`.
It helps standardize commits, propose safe code fixes, and orchestrate external tools via plugins.

## Does something like this already exist?

Partially: there are tools for AI commit messages, git hooks, and commit-history rewriting.
What is still missing is one local operator that:

- interacts with the user right after commit,
- proposes code fixes as additional commits (`fixup!`),
- cleans up history before `push`,
- integrates plugins via MCP/REST/CLI/gRPC.

## Proposed direction for `giton`

1. **Local-first with safe defaults**
   - AI proposes changes, user approves them.
   - Prefer `fixup!` commits over automatic history rewriting.

2. **Git hook layer**
   - `pre-commit`: policy validation and quick fixes.
   - `post-commit`: inspect the fresh commit and propose follow-up patches.
   - `pre-push`: standardize history (`autosquash`, commit naming, final checks).

3. **Plugin architecture**
   - Shared input/output contract (JSON schema).
   - Plugin adapters: MCP, REST, CLI shell, gRPC/protobuf.

## MVP usage example

After `giton init`, hooks are installed and run automatically from Git lifecycle events.
The commands below show equivalent manual execution for demonstration/debugging.

```bash
# 1) initialize hooks in the repository
giton init

# 2) user makes a normal commit
git add -p
git commit -m "update stuff"

# 3) equivalent manual run: post-commit hook logic
giton hook post-commit

# 4) equivalent manual run: pre-push hook logic
giton hook pre-push
```

Example interaction:

```text
giton: Found 2 issues (example: null check, commit message policy).
giton: Apply patch and add commit "fixup! ..."? [Y/n]
```

## MVP plan

- MVP 1: hooks + policy engine + interactive CLI
- MVP 2: patching + fixup workflow + pre-push autosquash
- MVP 3: stable plugin API and MCP/REST/CLI/gRPC integrations

## Install

```bash
pip install giton
```

## Development

### Setup

```bash
# Clone the repository
git clone <repo-url>
cd gix

# Install in development mode
pip install -e .[dev]
```

### Dependencies

**Runtime:**
- `typer>=0.12`
- `rich>=13.7`
- `PyYAML>=6.0`

**Development:**
- `pytest>=8.0`
- `goal>=2.1.0`
- `costs>=0.1.20`
- `pfix>=0.1.60`

### Testing

```bash
# Run all tests
pytest

# Run specific test file
pytest tests/test_history.py

# Run with coverage
pytest --cov=src/giton
```

### Environment Variables

Create a `.env` file in the project root (see `.env.example`):

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENROUTER_API_KEY` | *(not set)* | Required: OpenRouter API key (https://openrouter.ai/keys) |
| `LLM_MODEL` | `openrouter/qwen/qwen3-coder-next` | Model to use for AI operations |
| `PFIX_AUTO_APPLY` | `true` | Automatically apply fixes without asking |
| `PFIX_AUTO_INSTALL_DEPS` | `true` | Automatically pip/uv install dependencies |
| `PFIX_AUTO_RESTART` | `false` | Restart process after fix using os.execv |
| `PFIX_MAX_RETRIES` | `3` | Maximum retry attempts |
| `PFIX_DRY_RUN` | `false` | Run in dry-run mode without making changes |
| `PFIX_ENABLED` | `true` | Enable automatic fixing |
| `PFIX_GIT_COMMIT` | `false` | Automatically commit fixes |
| `PFIX_GIT_PREFIX` | `pfix:` | Commit message prefix for fixes |
| `PFIX_CREATE_BACKUPS` | `false` | Create backups in `.pfix_backups/` directory |

### Project Structure

```
gix/
├── src/giton/           # Main source code
│   ├── __init__.py      # Package initialization
│   ├── __main__.py      # Entry point for `python -m giton`
│   ├── catalog.py       # Plugin catalog management
│   ├── cli.py           # Command-line interface (Typer)
│   ├── config.py        # User plugin configuration
│   ├── context.py       # Git context collection
│   ├── history.py       # Safe history operations (fixup, autosquash)
│   ├── hooks.py         # Git hook installation
│   ├── interactive.py   # Interactive prompts
│   ├── plugins.py       # Plugin installation/management
│   ├── policies.py      # Built-in policy engine
│   ├── repo_config.py   # Repository configuration
│   ├── runner.py        # Plugin execution runner
│   └── shell.py         # Interactive REPL shell
├── tests/               # Test suite
│   ├── test_basic.py    # Basic functionality tests
│   ├── test_history.py  # History operations tests
│   └── test_policies.py # Policy engine tests
├── examples/            # Usage examples
│   ├── basic/           # Basic library usage
│   ├── advanced/        # Advanced features demo
│   └── testing/         # CI/CD integration example
├── pyproject.toml       # Project configuration
├── README.md            # This file
├── SUMD.md              # System documentation (SUMD)
├── TODO.md              # Auto-generated TODO list
└── CHANGELOG.md         # Version history
```

## Use Cases

### 1. Standardizing Commit Messages

Giton automatically validates commit messages against Conventional Commits spec:

```bash
# ❌ Blocked - doesn't follow conventional commits
git commit -m "fix bug"

# ✅ Allowed - follows conventional commits
git commit -m "fix(auth): handle null session token"
```

### 2. Preventing Secrets in Code

Giton scans staged files for sensitive data before commit:

```bash
# ❌ Blocked - AWS key detected
git add config.py
git commit -m "add config"
# giton: Found AWS key in config.py:4
```

### 3. Code Quality Gates

Automatically run linting and type checking before commits:

```bash
# With pyqual plugin installed
git commit -m "feat: add feature"
# giton: Running pyqual gates...
# giton: Type errors found in src/main.py:15
```

### 4. Safe History Cleanup

Use fixup commits and autosquash to clean up history before push:

```bash
# Create a fixup commit
giton fixup --target HEAD~1

# Clean up history before push
giton history clean --base main
```

### 5. Pre-push Validation

Run tests and generate test coverage before pushing:

```bash
# With testless plugin installed
git push origin feature-branch
# giton: Running testless scan...
# giton: All tests passed (42/42)
```

## Getting Started

### Step 1: Install

```bash
pip install giton
```

### Step 2: Initialize in Your Repository

```bash
cd your-project
giton init
```

This installs git hooks and default plugins (`pyqual`, `vallm`, `testless`).

### Step 3: Configure (Optional)

Create `.giton/config.yaml` to customize policies:

```yaml
policies:
  conventional_commits:
    max_subject_length: 100
  no_wip_commits:
    enabled: false  # allow WIP commits during development
hooks:
  pre-commit:
    fail_on_policy: true
```

### Step 4: Start Working

```bash
# Work as usual - giton will check automatically
git add .
git commit -m "feat: add new feature"

# Check status
giton status

# View available plugins
giton plugin catalog

# Install additional plugins
giton plugin install mypy
```

## Daily Workflow

A typical development day with giton:

```bash
# Morning: start working
git checkout -b feature/new-api

# During development: commit frequently
git add src/api.py
git commit -m "wip: add endpoint"  # blocked by no_wip_commits policy
git commit -m "feat(api): add endpoint"  # allowed

# After review: fix issues
git add src/api.py
giton fixup --target HEAD~1  # create fixup commit

# Before push: clean up history
giton history clean --base main

# Push
git push origin feature/new-api
```

## Working with Multiple Plugins

Giton supports installing and running multiple plugins across different triggers. Here's how to set up a comprehensive plugin ecosystem:

### Install by Category

Install all plugins for a specific category at once:

```bash
# Install all Python-related plugins
giton plugin install-category lang:python

# Install all autofix plugins
giton plugin install-category task:autofix

# Install all security plugins
giton plugin install-category task:security
```

### View Installed Plugins

```bash
giton plugin list
```

Output shows all plugins with their triggers and status:

```
┏━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ name    ┃ category      ┃ triggers    ┃ command            ┃ status          ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ pyqual  │ lang:python   │ pre-commit  │ pyqual run         │ enabled / cmd:✓ │
│ prefact │ task:autofix  │ pre-commit  │ prefact scan       │ enabled / cmd:✓ │
│ vallm   │ task:validate │ post-commit │ vallm batch        │ enabled / cmd:✓ │
│ testless│ task:test     │ pre-push    │ testless scan      │ enabled / cmd:✓ │
└─────────┴───────────────┴─────────────┴────────────────────┴─────────────────┘
```

### Multi-Plugin Workflow Example

With multiple plugins installed, giton runs them in sequence based on their triggers:

```bash
# 1. Pre-commit: pyqual + prefact run automatically
git add src/main.py
git commit -m "feat: add feature"
# → pyqual runs: checks code quality
# → prefact runs: scans for LLM-introduced issues
# → policies check: validates commit message

# 2. Post-commit: vallm + tagi run after commit
# → vallm runs: validates LLM-generated code
# → tagi runs: scans and groups uncommitted changes for next commits

# 3. Pre-push: testless runs before push
git push origin feature-branch
# → testless runs: scans tests and coverage
```

### Commit Grouping with tagi

The `tagi` plugin provides automatic change grouping and commit orchestration:

```bash
# Install tagi for commit grouping
giton plugin install tagi

# After installation, tagi automatically scans changes on each commit
# and shows grouped analysis via post-commit hook

# Manual tagi commands:
tagi scan . --grouped        # Scan and group uncommitted changes
tagi list-groups .           # List available change groups
tagi send . small docs       # Send specific groups in order
tagi auto .                  # Auto-scan, order, commit and push
```

### Install Additional Plugins

```bash
# Install specific plugins
giton plugin install domd          # Markdown linter
giton plugin install code2llm      # LLM context packer
giton plugin install tagi          # Commit grouping and orchestration
giton plugin install redsl         # Auto-fix lint issues
giton plugin install pfix          # Generic patch fixer
giton plugin install todocs        # Docs generator
giton plugin install prellm        # Pre-LLM security gate
```

### Plugin Categories

Browse available plugins by category:

```bash
giton plugin catalog
```

Categories include:
- **Languages:** `lang:python`, `lang:markdown`, `lang:any`
- **Tasks:** `task:validate`, `task:test`, `task:refactor`, `task:autofix`, `task:fix`, `task:docs`, `task:security`
- **Integrations:** `integration:mcp`

## Quick start

```bash
giton init                # install git hooks + 3 default plugins
giton shell               # interactive REPL
giton plugin catalog      # browse all available plugins
giton plugin install domd # install a specific extension
giton plugin install-category lang:python   # install everything for a language
```

### Default plugins

The 3 plugins activated by `giton init` cover the most common
day-to-day needs in a `commit → push` loop:

| name      | category        | trigger      | role                                       |
| --------- | --------------- | ------------ | ------------------------------------------ |
| `pyqual`  | `lang:python`   | `pre-commit` | Python lint / type / complexity checks      |
| `vallm`   | `task:validate` | `post-commit`| Validate AI-generated code/patches          |
| `testless`| `task:test`     | `pre-push`   | Run / generate tests before push            |

### Quick-extend categories

Each plugin in the catalog is tagged with a category, so you can install
groups at once:

- **languages:** `lang:python`, `lang:markdown`, `lang:any`
- **tasks:** `task:validate`, `task:test`, `task:refactor`,
  `task:autofix`, `task:fix`, `task:docs`, `task:security`
- **integrations:** `integration:mcp`

```bash
giton plugin install-category task:autofix
```

### Interactive shell

```text
$ giton shell
giton> help
giton> install-defaults
giton> hook pre-commit
giton> catalog
giton> install prefact
```

### Built-in policies

`giton` ships with a small zero-dependency policy engine that runs on
every hook trigger — even before any plugin is installed:

- **`conventional_commits`** — subject must match
  `type(scope)?: subject` and stay within `max_subject_length`.
- **`no_wip_commits`** — blocks subjects matching `wip`, `tmp`, `xxx`, `fixme`.
- **`no_secrets`** — scans staged additions for AWS keys, private-key
  headers and `api_key=`/`secret=` patterns.
- **`max_file_size`** — rejects staged files larger than `kb` (default 512 KB).

Inspect or customize them per repo:

```bash
giton policy list                    # show active policies
giton policy check -t pre-commit     # evaluate without running plugins
giton policy fix                     # apply auto-fixes from the last check
giton policy init                    # write .giton/config.yaml
```

Policies that can be auto-fixed (e.g. `conventional_commits`, `no_wip_commits`)
generate a `git commit --amend -m "…"` command.  Run `giton policy fix` to
apply it interactively, or pass `--yes` to skip the prompt.

`.giton/config.yaml` is a deep-merge over the defaults — disable a
single check or tweak `max_subject_length` without restating everything:

```yaml
policies:
  no_wip_commits:
    enabled: false
  conventional_commits:
    max_subject_length: 100
hooks:
  post-commit:
    fail_on_policy: true   # turn advisory checks into blocking
```

### Plugin contract

A plugin is any executable command (CLI). The catalog entry declares its
trigger, category, install target (PyPI/local path) and command template.
The runner expands `{paths}`, `{diff_file}` and `{root}` placeholders
with the current git context before invocation.

Future exec types (`mcp`, `rest`) will share the same JSON in/out
contract: input = git context + policy findings, output = list of
proposed actions (patches, fixup commits, warnings).

## Examples

The `examples/` directory contains working demonstrations of giton:

- **[examples/basic](examples/basic/)** - Basic usage example showing how to use giton as a Python library to collect git context, run triggers, and handle policy findings and plugin results. Can be run directly or with pytest.

- **[examples/advanced](examples/advanced/)** - Advanced usage example demonstrating plugin management (add, remove, list), custom policy configuration, hook installation/uninstallation, and running multiple triggers in sequence.

- **[examples/testing](examples/testing/)** - Testing example with pytest integration and Docker support. Shows how to integrate giton into CI/CD pipelines with containerized testing environments. Includes Dockerfile and docker-compose.yml for easy setup.

- **[examples/plugins](examples/plugins/)** - Plugin lifecycle example. Demonstrates how to register a custom shell-script plugin in an isolated repo, execute it via `giton hook pre-commit`, and verify that placeholders (`{paths}`, `{root}`) are expanded and output is captured. Useful for authors who want to build their own plugins.

### Running examples with Docker

All examples include Dockerfiles for containerized execution:

```bash
# Basic example
docker build -f examples/basic/Dockerfile -t giton-example-basic .
docker run --rm -v $(pwd)/examples/basic/logs:/app/logs giton-example-basic

# Advanced example
docker build -f examples/advanced/Dockerfile -t giton-example-advanced .
docker run --rm -v $(pwd)/examples/advanced/logs:/app/logs giton-example-advanced

# Testing example
docker build -f examples/testing/Dockerfile -t giton-test .
docker run --rm -v $(pwd)/examples/testing/logs:/app/logs giton-test
```

See each example's README.md for detailed usage instructions.


## License

Licensed under Apache-2.0.
