Metadata-Version: 2.4
Name: axm-git
Version: 0.3.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
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/axm-protocols/axm-forge/main/assets/logo.png" alt="AXM Logo" width="180" />
</p>

<p align="center">
  <strong>axm-git — Deterministic Git workflows for AI agents</strong>
</p>

<p align="center">
  <a href="https://github.com/axm-protocols/axm-forge/actions/workflows/ci.yml"><img src="https://github.com/axm-protocols/axm-forge/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://forge.axm-protocols.io/audit/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge/gh-pages/badges/axm-git/axm-audit.json" alt="axm-audit"></a>
  <a href="https://forge.axm-protocols.io/init/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge/gh-pages/badges/axm-git/axm-init.json" alt="axm-init"></a>
  <a href="https://github.com/axm-protocols/axm-forge/actions/workflows/axm-quality.yml"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge/gh-pages/badges/axm-git/coverage.json" alt="Coverage"></a>
  <a href="https://pypi.org/project/axm-git/"><img src="https://img.shields.io/pypi/v/axm-git" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
  <a href="https://forge.axm-protocols.io/git/"><img src="https://img.shields.io/badge/docs-live-brightgreen" alt="Docs"></a>
</p>

---

## 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 and optional author identity injection
- 🏷️ **Tag** — One-shot semver tagging from Conventional Commits
- 🚀 **Push** — Push with dirty-check, auto-upstream detection, and force support
- 🌲 **Worktree** — Add, remove, or list git worktrees
- 🔀 **PR** — Create GitHub pull requests with optional auto-merge
- 🧭 **Error Recovery** — When called on a non-git directory, tools suggest nearby git repos
- 🪝 **Hooks** — Lifecycle hook actions (preflight, create-branch, branch-delete, commit-phase, merge-squash, worktree-add, worktree-remove, push, create-pr, await-merge, pull-main) with `enabled` guard, auto-discovered via entry-points
- 🪪 **Identity** — Resolve git author from `git-profiles.toml` with schedule-based or explicit profile selection
- 🔎 **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) |
| `profile` | `None` | Identity profile name — overrides schedule-based resolution from `git-profiles.toml` |

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.

Identity is resolved once per call (not per commit). When resolved, each commit includes `--author="Name <email>"`. The result includes an `author` key (`{name, email}` or `null`).

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

### `git_worktree`

Add, remove, or list git worktrees.

| Parameter | Default | Description |
|---|---|---|
| `path` | `.` | Project root directory |
| `action` | *required* | `add`, `remove`, or `list` |
| `worktree_path` | `None` | Path for the new or existing worktree |
| `branch` | `None` | Branch name for `add` |

### `git_pr`

Create a GitHub pull request with optional auto-merge.

| Parameter | Default | Description |
|---|---|---|
| `path` | `.` | Project root directory |
| `title` | *required* | Pull request title |
| `body` | `None` | Pull request description |
| `base` | `None` | Base branch (defaults to repo default) |
| `auto_merge` | `False` | Enable auto-merge when checks pass |

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