Git

A RocketRide tool node that exposes local Git repository operations to an AI agent.

+## About Git

Git is a distributed version-control system for tracking changes in source files. Its repositories preserve commit history and support local work as well as remote collaboration.

What it does

This node gives an agent repository inspection and modification operations without requiring a host git executable. Pick it when work must stay within one repository's history and working tree; use a GitHub-style service node when the task is primarily hosting-platform operations. It has no pipeline lanes.

As a tool

The tool server prefix is git by default. It registers the following functions:

Function	Description
`git.clone`	Clones a remote repository to a path.
`git.init`	Initializes a repository at a path.
`git.status`	Returns working-tree and branch state.
`git.log`	Returns filtered commit history.
`git.show`	Returns one commit's metadata, patch, and statistics.
`git.diff`	Produces a working-tree, staged, or ref-to-ref diff.
`git.blame`	Returns per-line commit and author information.
`git.file_at`	Returns a file's content at a ref.
`git.write_file`	Creates or overwrites a working-tree text file.
`git.stage`	Stages a non-empty list of paths.
`git.commit`	Commits the staged index.
`git.stash`	Pushes, pops, lists, or drops stash entries.
`git.branch_list`	Lists local and optional remote branches.
`git.branch_create`	Creates a branch, optionally from a ref.
`git.checkout`	Checks out an existing local branch.
`git.branch_delete`	Deletes a branch.
`git.merge`	Merges a branch into the current branch.
`git.fetch`	Fetches a remote without merging.
`git.pull`	Fetches then fast-forwards the current branch.
`git.push`	Pushes the current or requested branch.
`git.grep`	Searches tracked content with a regular expression.
`git.ls_files`	Lists tracked files, with optional prefix and untracked files.

All calls require an initialized repository and reject unknown arguments. clone requires url and path (optional branch); init requires path (optional initial_branch). show requires ref; blame requires path; file_at requires both path and ref; write_file requires path and content; and commit requires message. stash requires op of push, pop, list, or drop; branch creation, checkout, deletion, and merge require their named branch argument. grep requires pattern and bounds max_results to 1–10,000.

Validation, Git, and libgit2 failures return an {error: message} result. With read-only mode on, every write operation is blocked; stash remains callable only for op: list.

Configuration

Set the repository location and safety policy before connecting this node to an agent. Credentials are only needed when the selected remote requires them.

Repository Path

A local path is opened in place, so agent writes persist there. A URL is cloned to a temporary directory at pipeline start and removed on exit. Leave it blank when the agent should call clone or init itself; configure authentication first if that runtime clone needs a private remote.

Authentication Type

Choose none for public repositories, token for HTTPS username-and-token credentials, or ssh for an SSH key. An unrecognized value falls back to none with a warning; missing credentials for the selected authenticated mode also warn, so correct them before an agent starts remote work.

SSH Private Key

Use a PEM-encoded private key only when Authentication Type is ssh; provide SSH Key Passphrase if it is encrypted. The key is written to a temporary 0400 file for remote operations and then removed. Use token authentication instead when the provider issues a scoped HTTPS token and an SSH key is unnecessary.

Safe Mode and Read-Only Mode

Read-only mode defaults to on and blocks clone, initialization, writes, staging, commits, mutating stash operations, branch changes, merge, fetch, pull, and push. Turn it off only when the agent should modify the repository. Safe mode also defaults to on; it blocks force push and force branch deletion, but does not block ordinary writes. Keep both defaults for analysis-only agents.

Authentication

For HTTPS, set Authentication Type to token, then provide Username and Token / Password. For SSH, select ssh and provide the PEM private key plus an optional passphrase. Secret fields are stored as secure configuration fields.

Notes

Write boundaries

write_file and stage reject traversal and .git paths, but a local configured repository is otherwise writable once read-only mode is disabled. Use a temporary clone or a sandboxed working copy when an agent should not alter the original checkout.

Merge safety

merge first checks whether the requested branch is already incorporated into the current branch; that read-only check succeeds even when the repository contains local changes. If the merge would change the repository, the index and working tree must be clean — no staged, unstaged, or untracked changes — so commit, stash, or remove them before retrying. When a merge starts from a clean repository and encounters conflicts, the node aborts it and restores the index and working tree to the original HEAD; because the clean-worktree check runs before the merge begins, conflict cleanup cannot discard pre-existing local work.

Upstream docs

Git documentation

What it does

Gives an agent safe, full-featured access to a git repository. The agent can open an existing local repository, clone a remote one, or initialize a fresh one, then work with the complete toolset: status and logs, diffs, staging and commits, branches, remotes, and history search.

Uses pygit2 / libgit2: the libgit2 native library is bundled inside the pygit2 wheel, so no host git binary is required on the machine running the engine.

Write operations are guarded by two toggles, both on by default: read-only mode blocks all writes, and safe mode blocks force-push and force branch deletion. A freshly added node can only inspect a repository until you turn read-only mode off.

Configuration

Field	Type	Description
`repoPath`	string	Default empty. Local path to an existing repository, or a remote URL (https://, git@, ssh://). A remote URL is cloned into a temporary directory at pipeline start and cleaned up on exit. Leave blank to let the agent call clone or init at runtime.
`authType`	string	Default "none". How to authenticate with remote repositories.
`username`	string	Default empty. Git username for token-based HTTPS authentication.
`token`	string	Default empty. Personal access token or password for HTTPS authentication. Leave empty when using SSH.
`sshKey`	string	Default empty. PEM-encoded SSH private key content (starts with -----BEGIN ...). Used when Auth Type is SSH.
`sshPassphrase`	string	Default empty. Passphrase for the SSH private key, if encrypted. Leave empty for unencrypted keys.
`safeMode`	boolean	Default true. Block destructive operations: force-push and force branch deletion. Normal branch deletion is allowed only when the branch is fully merged into HEAD; deleting an unmerged branch requires force=true (which is blocked in safe mode). Recommended for agent use.
`readOnlyMode`	boolean	Default true. Block ALL write operations (clone, init, write_file, stage, commit, stash push/pop/drop, branch create/delete, checkout, merge, fetch, pull, push). Read-only tools (status, log, show, diff, blame, file_at, branch_list, grep, ls_files, stash list) remain available. Strictly stronger than Safe Mode. Recommended when the agent only needs to inspect a repository.

repoPath: local path vs remote URL

repoPath is interpreted differently depending on its value:

Value	Behaviour
Remote URL (`https://`, `http://`, `git://`, `git@`, `ssh://`)	The repository is cloned into a temporary directory when the pipeline starts. The temp directory is deleted automatically when the pipeline ends. Use this for read-only analysis or ephemeral write workflows.
Local path	The existing directory is opened in place. No copy is made. Changes made by the agent persist on disk.
Empty	No repository is opened at startup. The agent must call `clone` or `init` as its first action.

Note: when using a remote URL with write operations (push), ensure authType and credentials are configured, since the cloned temp repo retains the remote origin from the URL.

Available tools

Repository

| Tool | Description | |---|---|---| | clone | Clone a remote git repository to a local path. Returns clone summary including the checked-out branch and HEAD SHA. | | init | Initialise a new empty git repository at the given path. Creates the directory if it does not exist. | | status | Return the working-tree status: current branch, staged files, unstaged modifications, and untracked files. | | log | Return commit history. Supports filtering by branch, file path, author name, and date range. | | show | Show full details of a single commit: metadata, diff patch, and file-change statistics. | | diff | Produce a unified diff. Can diff working tree vs HEAD, two refs, or the staged index vs HEAD. | | blame | Return per-line blame for a file: which commit and author last modified each line. | | file_at | Return the raw content of a file at a specific commit or ref. | | write_file | Write text content to a file in the working tree (creates or overwrites). Call stage then commit after writing to save the change. | | stage | Stage files for the next commit (equivalent to git add). Deleted files are removed from the index. | | commit | Create a commit from the current staged index. | | stash | Manage the git stash. Operations: push, pop, list, drop. | | branch_list | List local branches, and optionally remote-tracking branches. | | branch_create | Create a new branch, optionally from a specific ref. | | checkout | Check out an existing local branch. | | branch_delete | Delete a branch. Normal deletion is always allowed. Force deletion (force=true) is blocked when safeMode=true. | | merge | Merge a branch into the current branch. A merge that would change the repository requires a clean working tree. Fast-forwards if possible, otherwise creates a merge commit. Raises on conflicts. | | fetch | Fetch updates from a remote without merging. | | pull | Fetch from a remote and fast-forward merge the current branch. | | push | Push the current (or specified) branch to a remote. Force-push is blocked unless safeMode=false. | | grep | Search tracked file contents for a regex pattern. Returns file, line number, and matching line for each hit. Capped at max_results hits to keep responses bounded. | | ls_files | List all tracked files in the repository, optionally filtered by path prefix. |

Status & info

Tool	Description
`status`	Working-tree status: staged, unstaged, untracked files
`log`	Commit history with optional filters
`show`	Full details + diff for a single commit

Diff & inspection

Tool	Description
`diff`	Unified diff (working tree, two refs, or staged)
`blame`	Per-line blame for a file
`file_at`	File content at a specific commit or ref

Working tree & commits

Tool	Description
`write_file`	Write text content to a file in the working tree (creates or overwrites)
`stage`	Stage files (git add)
`commit`	Create a commit from staged index
`stash`	Push / pop / list / drop stash

Branches

Tool	Description
`branch_list`	List local (and/or remote) branches
`branch_create`	Create a branch from any ref
`checkout`	Check out an existing branch
`branch_delete`	Delete a branch
`merge`	Merge a branch into the current one

Remote

Tool	Description
`fetch`	Fetch from a remote
`pull`	Fetch + fast-forward merge
`push`	Push to a remote (force-push blocked in safe mode)

Search

Tool	Description
`grep`	Regex search across tracked file contents
`ls_files`	List tracked (and optionally untracked) files

Safe mode

When safeMode is true (the default), the following operations raise an error instead of executing:

force push: push with force: true
force branch deletion: branch_delete with force: true

Normal branch deletion (force: false) is not gated by safe mode, but it only succeeds when the branch is fully merged into HEAD; deleting an unmerged branch requires force: true, which safe mode blocks. In practice, an unmerged branch cannot be deleted while safe mode is on.

Set safeMode: false in the node config to allow force operations.

Security note: write scope

Safe mode does not restrict file writes. Anything outside the .git/ directory is fair game for write_file, including .gitignore, CI configs, build scripts, source files, and lockfiles. Path traversal (../) and writes inside .git/ are blocked, but otherwise the agent has full read/write access to the working tree.

When pointing the node at a real repository (rather than a remote URL that auto-clones into a temp directory), treat the agent as a human contributor with commit rights to that tree. If you need stricter scoping, run the agent against a temp clone or a sandboxed working copy.

Read-only mode

When readOnlyMode is true (the default), every mutating tool is blocked at dispatch and returns a JSON error. This is strictly stronger than safeMode and is the recommended setting when the agent only needs to inspect a repository.

Blocked tools: clone, init, write_file, stage, commit, stash (op push / pop / drop), branch_create, checkout, branch_delete, merge, fetch, pull, push.

Always allowed: status, log, show, diff, blame, file_at, branch_list, grep, ls_files, and stash with op: "list".

Set readOnlyMode: false in the node config to allow write operations (subject to safeMode).

Merge safety

merge first checks whether the requested branch is already incorporated into the current branch. That read-only check succeeds even when the repository contains local changes. If the merge would change the repository, the index and working tree must be clean: no staged, unstaged, or untracked changes. Commit, stash, or remove those changes before retrying.

When a merge starts from a clean repository and encounters conflicts, the node aborts it and restores the index and working tree to the original HEAD. Because the clean-worktree check runs before the merge begins, conflict cleanup cannot discard pre-existing local work.

Authentication

Token (HTTPS)

Set authType: token, then provide username (e.g. "git" for GitHub/GitLab) and token (personal access token or app password).

SSH

Set authType: ssh, then paste the PEM-encoded private key content into sshKey. If the key has a passphrase, set sshPassphrase as well.

The key content is written to a temporary file with chmod 0400 during remote operations and deleted immediately after.

Running the tests

# Unit tests only (no git binary or real repo needed)
pytest nodes/test/tool_git/test_tools.py -v

# Integration tests against a real local repository
export GIT_TEST_REPO_PATH=/path/to/any/local/git/repo
pytest nodes/test/tool_git/test_tools.py -v

-->

Schema

Field	Type	Description	Default
`git.authType`	`string`	Authentication Type How to authenticate with remote repositories.	`"none"`
`git.readOnlyMode`	`boolean`	Read-Only Mode Block ALL write operations (clone, init, write_file, stage, commit, stash push/pop/drop, branch create/delete, checkout, merge, fetch, pull, push). Read-only tools (status, log, show, diff, blame, file_at, branch_list, grep, ls_files, stash list) remain available. Strictly stronger than Safe Mode. Recommended when the agent only needs to inspect a repository.	`true`
`git.repoPath`	`string`	Repository Path Local path to an existing repository, or a remote URL (https://, git@, ssh://). A remote URL is cloned into a temporary directory at pipeline start and cleaned up on exit. Leave blank to let the agent call clone or init at runtime.	`""`
`git.safeMode`	`boolean`	Safe Mode Block destructive operations: force-push and force branch deletion. Normal branch deletion is allowed only when the branch is fully merged into HEAD; deleting an unmerged branch requires force=true (which is blocked in safe mode). Recommended for agent use.	`true`
`git.sshKey`	`string`	SSH Private Key PEM-encoded SSH private key content (starts with -----BEGIN ...). Used when Auth Type is SSH.	`""`
`git.sshPassphrase`	`string`	SSH Key Passphrase Passphrase for the SSH private key, if encrypted. Leave empty for unencrypted keys.	`""`
`git.token`	`string`	Token / Password Personal access token or password for HTTPS authentication. Leave empty when using SSH.	`""`
`git.username`	`string`	Username Git username for token-based HTTPS authentication.	`""`

Dependencies

pygit2 >=1.19.2

What it does​

As a tool​

Configuration​

Repository Path​

Authentication Type​

SSH Private Key​

Safe Mode and Read-Only Mode​

Authentication​

Notes​

Write boundaries​

Merge safety​

Upstream docs​

What it does​

Configuration​

repoPath: local path vs remote URL​

Available tools​

Repository​

Status & info​

Diff & inspection​

Working tree & commits​

Branches​

Remote​

Search​

Safe mode​

Security note: write scope​

Read-only mode​

Merge safety​

Authentication​

Token (HTTPS)​

SSH​

Running the tests​

Schema​

Dependencies​

What it does

As a tool

Configuration

Repository Path

Authentication Type

SSH Private Key

Safe Mode and Read-Only Mode

Authentication

Notes

Write boundaries

Merge safety

Upstream docs

What it does

Configuration

repoPath: local path vs remote URL

Available tools

Repository

Status & info

Diff & inspection

Working tree & commits

Branches

Remote

Search

Safe mode

Security note: write scope

Read-only mode

Merge safety

Authentication

Token (HTTPS)

SSH

Running the tests

Schema

Dependencies