Git tools

Version control operations for repositories

Git tools enable AI agents to interact with Git repositories, including status checks, commits, diffs, and branch management.

Tool organization

All Git tools are accessed through the git namespace:

import { git } from "@/core/agent/tools/git";

// Read-only tools
const statusTool = git.status();
const logTool = git.log();
const diffTool = git.diff();

// Write tools (approval required)
const addTools = git.add();
yield* registerTool(addTools.approval);
yield* registerTool(addTools.execute);

Read-only tools

These tools query repository state without modifications.

git_status

Show current branch, modified files, staged changes, and untracked files.

Parameters:

path · string

Repository path (defaults to current working directory)

Returns:

workingDirectory · string

Resolved repository path

branch · string

Current branch name

hasChanges · boolean

Whether repository has uncommitted changes

summary · string[]

Git status short format output lines

rawStatus · string

Full git status output

Example:

const result = yield* statusTool.handler({ path: "./my-repo" }, context);
// {
//   success: true,
//   result: {
//     workingDirectory: "/home/user/my-repo",
//     branch: "main",
//     hasChanges: true,
//     summary: [
//       "M src/main.ts",
//       "?? new-file.ts"
//     ]
//   }
// }

git_log

Show commit history.

Parameters:

path · string

Repository path (defaults to current working directory)

limit · number · default: 20

Maximum commits to return (cap: 50)

oneline · boolean · default: false

Format commits as one-liners

Returns:

workingDirectory · string

Resolved repository path

commitCount · number

Number of commits returned

commits · array

Commit objects:

Show Commit object

hash · string

Full commit hash

shortHash · string

Short commit hash

author · string

Commit author name

relativeDate · string

Relative date (e.g., “2 days ago”)

subject · string

Commit subject line

oneline · string

One-line format (when oneline: true)

Example:

const result = yield* logTool.handler({ limit: 10, oneline: true }, context);
// {
//   success: true,
//   result: {
//     workingDirectory: "/home/user/my-repo",
//     commitCount: 10,
//     commits: [
//       {
//         hash: "a1b2c3d4e5f6...",
//         shortHash: "a1b2c3d",
//         author: "John Doe",
//         relativeDate: "2 hours ago",
//         subject: "Add new feature",
//         oneline: "a1b2c3d Add new feature"
//       },
//       // ...
//     ]
//   }
// }

git_diff

Show differences between commits, branches, or working tree.

Parameters:

path · string

Repository path (defaults to current working directory)

staged · boolean · default: false

Show staged changes (git diff —staged)

branch · string

Compare with branch

commit · string

Compare with commit hash

paths · string[]

Scope diff to specific files (e.g., ['src/foo.ts', 'docs/bar.md'])

nameOnly · boolean · default: false

Return only changed file paths (git diff —name-only)

maxLines · number · default: 500

Maximum diff lines to return (cap: 2000)

Returns:

workingDirectory · string

Resolved repository path

hasChanges · boolean

Whether there are differences

diff · string

Unified diff output (when nameOnly: false)

paths · string[]

Changed file paths (when nameOnly: true)

count · number

Number of changed files (when nameOnly: true)

truncated · boolean

Whether diff was truncated

totalLines · number

Total diff lines

returnedLines · number

Lines returned

options · object

Options used for diff

Example:

// Get diff of staged changes
const result1 = yield* diffTool.handler({ staged: true }, context);

// Compare with branch
const result2 = yield* diffTool.handler({ branch: "develop" }, context);

// Get changed file names only
const result3 = yield* diffTool.handler(
  { nameOnly: true, paths: ["src/"] },
  context
);

git_branch

List Git branches.

Parameters:

path · string

Repository path (defaults to current working directory)

Returns:

branches · string[]

List of branch names

current · string

Current branch name

git_blame

Show file annotations (who changed what line).

Parameters:

path · string

Repository path (defaults to current working directory)

file · string · required

File path to annotate

startLine · number

Start line (1-based)

endLine · number

End line (1-based)

Returns:

annotations · array

Line annotations with commit info

git_reflog

Show reference log of HEAD updates.

Parameters:

path · string

Repository path (defaults to current working directory)

limit · number · default: 20

Maximum entries to return

Returns:

entries · array

Reflog entries with hash, action, and message

git_tag (list)

List Git tags.

Parameters:

path · string

Repository path (defaults to current working directory)

Returns:

tags · string[]

List of tag names

Write tools

These tools modify repository state and require user approval.

git_add

Stage files for the next commit.

Parameters:

path · string

Repository path (defaults to current working directory)

files · string[] · required

File paths to stage (relative to repository root)

all · boolean · default: false

Stage all modified and untracked files (ignores files parameter)

Returns:

workingDirectory · string

Resolved repository path

addedFiles · string | string[]

Files added (“all files” or array of file paths)

message · string

Success message

Example:

const addTools = git.add();

// Stage specific files
const result1 = yield* addTools.execute.handler(
  {
    files: ["src/main.ts", "src/utils.ts"],
  },
  context
);

// Stage all changes
const result2 = yield* addTools.execute.handler({ all: true }, context);

git_commit

Create a commit from staged changes.

Parameters:

path · string

Repository path (defaults to current working directory)

message · string · required

Commit message. Use imperative mood, keep first line under 72 characters

all · boolean · default: false

Commit all modified tracked files, skipping staging (git commit -a)

Returns:

workingDirectory · string

Resolved repository path

message · string

Commit message

commitHash · string

Full commit hash

Example:

const commitTools = git.commit();
const result = yield* commitTools.execute.handler(
  {
    message: "Add new feature\n\nDetailed description of the feature.",
  },
  context
);
// {
//   success: true,
//   result: {
//     workingDirectory: "/home/user/my-repo",
//     message: "Add new feature...",
//     commitHash: "a1b2c3d4e5f6..."
//   }
// }

git_push

Push commits to remote repository.

Parameters:

path · string

Repository path (defaults to current working directory)

remote · string · default: "origin"

Remote name

branch · string

Branch name (defaults to current branch)

force · boolean · default: false

Force push (use with caution)

Returns:

workingDirectory · string

Resolved repository path

remote · string

Remote pushed to

branch · string

Branch pushed

git_pull

Pull changes from remote repository.

Parameters:

path · string

Repository path (defaults to current working directory)

remote · string · default: "origin"

Remote name

branch · string

Branch name (defaults to current branch)

Returns:

workingDirectory · string

Resolved repository path

message · string

Pull result message

git_checkout

Switch branches or restore working tree files.

Parameters:

path · string

Repository path (defaults to current working directory)

branch · string

Branch name to checkout

create · boolean · default: false

Create new branch (git checkout -b)

files · string[]

Restore specific files

git_merge

Merge branches.

Parameters:

path · string

Repository path (defaults to current working directory)

branch · string · required

Branch to merge into current branch

strategy · string

Merge strategy (e.g., “recursive”, “ours”)

git_rm

Remove files from working tree and index.

Parameters:

path · string

Repository path (defaults to current working directory)

files · string[] · required

File paths to remove

cached · boolean · default: false

Remove from index only (keep working tree)

git_tag (create/delete)

Create or delete tags.

Parameters:

path · string

Repository path (defaults to current working directory)

name · string · required

Tag name

message · string

Tag message (creates annotated tag)

delete · boolean · default: false

Delete tag instead of creating

Utility functions

resolveGitWorkingDirectory

Resolve and validate a Git repository path.

import { resolveGitWorkingDirectory } from "@/core/agent/tools/git/utils";

const workingDir = yield* resolveGitWorkingDirectory(
  shell,
  context,
  fs,
  "./my-repo"
);

runGitCommand

Execute a Git command with proper error handling.

import { runGitCommand } from "@/core/agent/tools/git/utils";

const result = yield* runGitCommand({
  args: ["status", "--short"],
  workingDirectory: "/home/user/my-repo",
  timeoutMs: 10_000, // Optional
});
// {
//   stdout: string,
//   stderr: string,
//   exitCode: number
// }

DEFAULT_GIT_TIMEOUT

Default timeout for Git commands (20 seconds):

import { DEFAULT_GIT_TIMEOUT } from "@/core/agent/tools/git/utils";

Best practices

Always check status first

Before committing, check what will be committed:

// 1. Check status
const status = yield* git.status().handler({}, context);

if (status.success && status.result.hasChanges) {
  // 2. Review changes
  const diff = yield* git.diff().handler({ staged: true }, context);

  // 3. Commit
  const commitTools = git.commit();
  yield* commitTools.execute.handler(
    { message: "Fix bug in parser" },
    context
  );
}

Use descriptive commit messages

Follow conventional commit format:

git.commit().execute.handler(
  {
    message:
      "feat: Add user authentication\n\n" +
      "- Implement JWT token generation\n" +
      "- Add login/logout endpoints\n" +
      "- Update user model with password hashing",
  },
  context
);

Scope diffs to relevant files

When working with large repositories:

// Good: Scope to relevant files
git.diff().handler(
  {
    paths: ["src/auth/", "tests/auth/"],
    maxLines: 200,
  },
  context
);

// Bad: Request full repository diff
git.diff().handler({}, context);

Use nameOnly for file lists

When you only need to know which files changed:

// Get list of modified files
const result = yield* git.diff().handler(
  { staged: true, nameOnly: true },
  context
);
// result.result.paths = ["src/main.ts", "tests/main.test.ts"]

Handle merge conflicts

Always check for conflicts after pulling:

const pullTools = git.pull();
const pullResult = yield* pullTools.execute.handler({}, context);

if (pullResult.success) {
  // Check for conflicts
  const status = yield* git.status().handler({}, context);
  if (status.result.summary.some((line) => line.startsWith("UU"))) {
    // Handle conflicts
  }
}