Metadata-Version: 2.4
Name: axm-git
Version: 0.1.0
Summary: Git workflow automation for AXM agents
Project-URL: Homepage, https://github.com/axm-protocols/axm-git
Project-URL: Documentation, https://axm-protocols.github.io/axm-git/
Project-URL: Repository, https://github.com/axm-protocols/axm-git.git
Project-URL: Issues, https://github.com/axm-protocols/axm-git/issues
Author-email: Gabriel <gabriel@axm.dev>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: axm>=0.1.0
Description-Content-Type: text/markdown

  AXM Logo

  axm-git — Deterministic Git workflows for AI agents

  Python 3.12+

---

## Features

- 🔍 **Preflight** — Structured working tree status with diff summary
- 🌿 **Branch** — Create or checkout branches with one call
- 📦 **Commit** — Batched atomic commits with auto-retry on pre-commit fixes
- 🏷️ **Tag** — One-shot semver tagging from Conventional Commits
- 🚀 **Push** — Push with dirty-check, auto-upstream detection, and force support
- 🧭 **Error Recovery** — When called on a non-git directory, tools suggest nearby git repos
- 🪝 **Hooks** — Lifecycle hook actions (create-branch, commit-phase, merge-squash) with `enabled` guard, auto-discovered via entry-points
- 🔎 **Phase Lookup** — `get_phase_commit()` retrieves commit hashes for protocol phases

## Installation

```bash
uv add axm-git
```

## Quick Start

```python
# Check what changed
git_preflight(path="/path/to/repo")
# → {files: [{path: "foo.py", status: "M"}, ...], clean: false}

# Create or switch branch
git_branch(name="feat/new-feature", path="/path/to/repo")
# → {branch: "feat/new-feature"}

# Commit in batches
git_commit(path="/path/to/repo", commits=[
    {"files": ["src/foo.py"], "message": "feat: add foo"},
    {"files": ["tests/test_foo.py"], "message": "test: add foo tests"},
])
# → {results: [{sha: "abc1234", precommit_passed: true}, ...]}

# Tag a release
git_tag(path="/path/to/repo")
# → {tag: "v0.2.0", bump: "minor", pushed: true}

# Push to remote
git_push(path="/path/to/repo")
# → {branch: "main", remote: "origin", pushed: true}
```

## MCP Tools

### `git_preflight`

Report working tree changes so the agent can plan commits.

| Parameter | Default | Description |
|---|---|---|
| `path` | `.` | Project root directory |
| `diff_lines` | `200` | Max diff lines to include (0 to disable) |

Returns: file list with status (`M`, `A`, `D`, `??`), diff stat, clean flag.

### `git_branch`

Create or checkout a git branch.

| Parameter | Default | Description |
|---|---|---|
| `name` | *required* | Branch name |
| `from_ref` | `None` | Ref to branch from (tag, commit, branch) |
| `checkout_only` | `False` | If `True`, checkout existing branch without creating |
| `path` | `.` | Project root directory |

Returns: `{branch: "<current branch>"}` on success.

### `git_commit`

Execute one or more atomic commits with pre-commit hook handling.

| Parameter | Default | Description |
|---|---|---|
| `path` | `.` | Project root directory |
| `commits` | *required* | List of commit specs (see below) |

Each commit spec:

| Field | Required | Description |
|---|---|---|
| `files` | ✅ | Files to stage |
| `message` | ✅ | Commit summary (Conventional Commits) |
| `body` | | Extended commit body |

When a pre-commit hook auto-fixes files (e.g. ruff `--fix`), the tool re-stages and retries once automatically.

### `git_tag`

Compute the next semver version from Conventional Commits, create and push the tag.

| Parameter | Default | Description |
|---|---|---|
| `path` | `.` | Project root directory |
| `version` | *auto* | Override the computed version (e.g. `"v1.0.0"`) |

Pipeline: clean tree check → CI status check → semver bump → annotate tag → hatch-vcs verify → push.

### `git_push`

Push the current branch to a remote after verifying a clean working tree.

| Parameter | Default | Description |
|---|---|---|
| `path` | `.` | Project root directory |
| `remote` | `origin` | Remote name |
| `set_upstream` | `True` | Auto-set upstream for new branches |
| `force` | `False` | Force-push |

Pipeline: repo check → dirty check → detect branch → detect upstream → push.

## Development

This package is part of the [**axm-forge**](https://github.com/axm-protocols/axm-forge) workspace.

```bash
git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-groups
uv run --package axm-git --directory packages/axm-git pytest -x -q
```

📖 **[Full documentation](https://forge.axm-protocols.io/git/)**

## License

Apache-2.0 — © 2026 axm-protocols
