How-To Guides

Task-oriented guides for common workflows.

Commit deleted files

When a file has been removed from disk, git_commit stages the deletion automatically — stage_spec_files() probes git ls-files -d per spec file, so a tracked-but-deleted path is staged as a deletion without any extra step:

Python

from axm_git.tools.commit import GitCommitTool

# File was already deleted from disk
result = GitCommitTool().execute(
    path="/path/to/repo",
    commits=[{"files": ["old_module.py"], "message": "fix: remove dead module"}],
)
# success=True — deletion is committed

Handle commit-hook auto-fixes

When ruff or another tool auto-fixes files during git commit, the tool retries automatically:

Python

result = GitCommitTool().execute(
    path="/path/to/repo",
    commits=[{"files": ["src/foo.py"], "message": "feat: add foo"}],
)
# If ruff auto-fixed, result.data["results"][0]["retried"] == True

If the retry also fails (e.g. mypy error), the result includes:

Python

result.data["failed_commit"]["auto_fixed_files"]  # ["src/foo.py"]
result.data["failed_commit"]["retried"]  # True
result.data["failed_commit"]["precommit_output"]  # full hook output

Tag without GitHub CLI

The git_tag tool works without gh installed — CI checks are simply skipped:

Python

result = GitTagTool().execute(path="/path/to/repo")
# result.data["ci_check"] == "skipped" if gh not available

Handle non-git directory errors

When a tool is called on a directory that isn't a git repository but contains git subdirectories (e.g. a monorepo parent), the error includes suggestions:

Python

result = GitPreflightTool().execute(path="/path/to/monorepo")
# result.success == False
# result.error == "fatal: not a git repository. This directory contains
#   git repos: axm-ast, axm-core, axm-git. Pass one of these as the path instead."
# result.data["suggestions"] == ["axm-ast", "axm-core", "axm-git"]

This works for all tools (git_preflight, git_branch, git_commit, git_tag, git_push).

Use with MCP

All tools are auto-discovered via axm.tools entry points and served through the AXM MCP server. See Use via MCP for the full tool list and call examples.