Search by

adachsoft / git-tool

Arkadiusz Adach

Git tool adapter for adachsoft/ai-tool-call built on top of adachsoft/gitlib.

Package info

gitlab.com/a.adach/git-tool

Issues

pkg:composer/adachsoft/git-tool

Statistics

Installs: 24

Dependents: 0

Suggesters: 0

Stars: 0

v0.12.0 2026-11-12 09:21 UTC

This package is auto-updated.

Last update: 2026-11-12 08:23:04 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.
  • adachsoft/command-executor-lib – process execution with configurable per-operation timeouts.

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: repository path and process timeouts

The Git repository location and process timeout limits are configured once, when the tool is created by the factory. They are not provided per call.

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

  • 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.
  • local_timeout_seconds (positive integer, optional)
    • Maximum execution time for local operations such as status, diff, add, and commit.
    • Defaults to 120 seconds.
  • network_timeout_seconds (positive integer, optional)
    • Maximum execution time for network operations such as push, pull, fetch, clone, and ls-remote.
    • Defaults to 600 seconds.

Every Git process is run non-interactively with terminal prompts disabled, an empty askpass helper, and editor input suppressed. Its standard input is redirected from the platform null device.

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',
    'local_timeout_seconds' => 120,
    'network_timeout_seconds' => 600,
]);

$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": "git@github.com:adachsoft/git-tool.git",
        "push_url": "git@github.com: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