adachsoft / git-tool

v0.9.0 2026-09-30 11:40 UTC

Requires

• php: ^8.3
• adachsoft/ai-tool-call: *
• adachsoft/gitlib: ^4.0
• adachsoft/normalized-safe-path: *

Requires (Dev)

• adachsoft/php-code-style: ^0.7
• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: 2.1.34
• phpunit/phpunit: ^12.4
• rector/rector: 2.3.3
• symplify/phpstan-rules: ^14.9.8

MIT

• Arkadiusz Adach

• git
• adapter
• spi
• ai-tool-call
• ai-tool

Published on Packagist.org on 2026-09-30 09:41 UTC

README

Git tool adapter for adachsoft/ai-tool-call.

This library exposes a small, well-defined subset of Git operations as AI-callable tools. It is built on top of adachsoft/gitlib and is intended to be used by agents via the SPI layer of adachsoft/ai-tool-call.

There are currently three main SPI tools provided:

• GitTool – full Git tool with both read and write operations.
• ReadOnlyGitTool – read-only Git tool exposing only non-mutating operations.
• GitWorkflowTool – higher-level Git workflow tool exposing compound actions such as staging+commit+push, tagging with push, hard reset, and repository initialization.

Supported operations

Common operation model

Both tools share the same conceptual parameters shape:

{
  "operation": "operation-name",
  "options": {
    // operation-specific
  }
}

GitTool operations (read & write)

• status – read repository status (branch, staged/modified/untracked/deleted files, conflicted files, operation state, raw output).
• add – stage files in the index.
• commit – create a new commit with a message.
• push – push commits or tags to a remote.
• tag_list – list tags (optionally filtered by pattern).
• tag_create – create a new tag (lightweight by default, annotated when annotated: true or message provided, optional target, signing and force).
• tag_delete – delete a local tag.
• checkout – switch branches/tags/commits and optionally create a new branch.
• show – show details of a Git object (commit, tag, etc.), excluding diff by default (use no_diff: false to include diff).
• diff – show changes for a given path or commit range.
• remote_list – list configured remotes with their URLs.
• log – retrieve commit log entries with optional filters (limit, author, since, until, grep).
• git_rm – remove files from tracking (git rm / git rm --cached).
• branch_list – list branches (local, remote, or all).
• branch_merge – merge the specified branch into the current branch.
• pull_rebase – pull changes with rebase (git pull --rebase).
• rebase – run git rebase (target branch, abort, continue, skip).
• merge_abort – abort in-progress merge (git merge --abort).
• merge_continue – continue merge after conflict resolution (git merge --continue).
• init – initialize a new Git repository.
• remote_add – add a new remote (git remote add).
• remote_set_url – update URL of an existing remote (git remote set-url).
• add_commit_push – stage all changes, commit, and push.
• list_changed_files – list modified/staged/untracked/conflicted files and repository state.
• current_branch – get current branch name.
• create_and_push_tag – create local tag (lightweight by default) and push to remote; note that this operation does not commit changes.
• reset_hard – perform hard reset (git reset --hard).
• checkout_file_from_branch – restore specific file from a branch.

GitWorkflowTool operations (high-level workflows)

Higher-level compound operations designed for agent workflows:

• add_commit_push – stages all changes (git add .), creates a commit with the given message, and pushes to the current or specified branch on the remote.
• create_and_push_tag – creates a local tag and pushes it to the remote. By default, it creates a lightweight tag pointing directly to HEAD (or specified target). Set annotated: true to create an annotated tag with message. This operation does not create a commit; commit changes using add_commit_push prior to calling this operation.
• init_and_push – initializes a Git repository if needed, sets up remote, stages all files, commits, and pushes with upstream tracking.
• list_changed_files – returns lists of staged, modified, untracked, deleted, and conflicted files along with active repository state flags.
• current_branch – returns the active branch name.
• reset_hard – resets the working directory and index (git reset --hard to optional ref).
• checkout_file_from_branch – restores a single file from a given branch (git checkout <branch> -- <path>).

ReadOnlyGitTool operations (read-only)

The read-only tool exposes only non-mutating operations:

• status
• tag_list
• show (excludes diff by default, configurable via no_diff)
• diff
• remote_list
• log

This is useful for agents that must never change repository state but still need rich visibility into the Git history and configuration.

Installation

Install via Composer:

composer require adachsoft/git-tool

This package depends on:

• adachsoft/ai-tool-call – SPI + public API for calling tools from agents.
• adachsoft/gitlib – Git operations backend.

Check their respective composer.json files for exact PHP version requirements.

Architecture overview

The package is intentionally small and split into three main layers:

• SPI Tools (integration layer)
  • AdachSoft\GitTool\Tool\GitTool – implementation of AdachSoft\AiToolCall\SPI\ToolInterface.
  • AdachSoft\GitTool\Tool\GitToolFactory – implementation of AdachSoft\AiToolCall\SPI\Factory\ToolFactoryInterface.
  • AdachSoft\GitTool\Tool\ReadOnlyGitTool – read-only tool implementation of ToolInterface.
  • AdachSoft\GitTool\Tool\ReadOnlyGitToolFactory – factory for the read-only tool.
  • AdachSoft\GitTool\Tool\GitWorkflowTool – workflow tool implementation of ToolInterface.
  • AdachSoft\GitTool\Tool\GitWorkflowToolFactory – factory for the workflow tool.
• Service layer
  • AdachSoft\GitTool\Service\GitToolService / GitToolServiceInterface.
  • AdachSoft\GitTool\Service\GitOperationRegistry / GitOperationRegistryInterface.
• DTOs & Exceptions
  • AdachSoft\GitTool\Dto\GitToolRequestDto, GitToolResultDto.
  • Domain-specific exceptions under AdachSoft\GitTool\Exception.

The SPI layer knows only about the generic operation and options structure. The service layer maps these operations to concrete calls on Adachsoft\GitLab\Contracts\GitRepositoryInterface from adachsoft/gitlib.

Configuration: base_path

The Git repository location is configured once, when the tool is created by the factory. It is not provided per call.

GitToolFactory::create() and ReadOnlyGitToolFactory::create() accept an AdachSoft\AiToolCall\SPI\Collection\ConfigMap with the following option:

• base_path (string, optional)
  • Base path of the Git repository.
  • When omitted, the current working directory (getcwd()) is used.
  • When provided, it must be a non-empty string and an existing directory.

Example:

use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\GitTool\Tool\GitToolFactory;
use AdachSoft\GitTool\Tool\GitWorkflowToolFactory;
use AdachSoft\GitTool\Tool\ReadOnlyGitToolFactory;

$config = new ConfigMap([
    'base_path' => '/path/to/your/git/repository',
]);

$writeFactory = new GitToolFactory();
$writeTool = $writeFactory->create($config); // AdachSoft\GitTool\Tool\GitTool

$readOnlyFactory = new ReadOnlyGitToolFactory();
$readOnlyTool = $readOnlyFactory->create($config); // AdachSoft\GitTool\Tool\ReadOnlyGitTool

$workflowFactory = new GitWorkflowToolFactory();
$workflowTool = $workflowFactory->create($config); // AdachSoft\GitTool\Tool\GitWorkflowTool

The hosting application is responsible for wiring the factories into the SPI infrastructure of adachsoft/ai-tool-call (see that package's documentation for exact integration steps).

Tool interface: operations and options

The tool parameters are described by GitTool::getDefinition() and ReadOnlyGitTool::getDefinition() via SpiToolDefinitionDto. Conceptually, the parameters have the following shape:

{
  "operation": "status | add | commit | push | tag_list | tag_create | tag_delete | checkout | show | diff | remote_list",
  "options": {
    // operation-specific
  }
}

Refer to the PHPDoc blocks in GitTool and ReadOnlyGitTool for the exact list of parameters and result structures.

Result format

Every successful tool call returns a ToolCallResultDto that wraps a KeyValueMap with the following structure:

{
  "operation": "operation-name",
  "data": { /* operation-specific result */ }
}

Examples:

// status
{
  "operation": "status",
  "data": {
    "branch": "main",
    "staged": ["src/GitTool.php"],
    "modified": [],
    "untracked": ["README.md"],
    "deleted": [],
    "raw_output": "On branch main..."
  }
}

// remote_list
{
  "operation": "remote_list",
  "data": {
    "remotes": [
      {
        "name": "origin",
        "fetch_url": "[e-mail]:adachsoft/git-tool.git",
        "push_url": "[e-mail]:adachsoft/git-tool.git"
      }
    ]
  }
}

Error handling

The tools validate input at the SPI boundary:

• missing or empty operation – InvalidToolCallException.
• non-array options – InvalidToolCallException.
• unsupported operation for the given tool (e.g. write operation on read-only tool) – InvalidToolCallException.

Domain-level errors are mapped to ToolExecutionException:

• unsupported operation value in the registry.
• invalid per-operation options (e.g. missing message for commit).
• failures coming from the underlying Git library.

The original domain exception is attached as the previous exception for easier debugging.

Development & tests

The repository includes a set of PHPUnit tests covering:

• the SPI tools (GitTool, ReadOnlyGitTool, GitWorkflowTool).
• the factories (GitToolFactory, ReadOnlyGitToolFactory, GitWorkflowToolFactory).
• the service layer (GitToolService).
• the operation registry (GitOperationRegistry).

Run the test suite with:

composer install
vendor/bin/phpunit