CoreRasurae
112 lines
4.1 KiB
Markdown
112 lines
4.1 KiB
Markdown
# Git Operation Skills (C4.git)
|
|
|
|
This document describes the built-in git operation skills that agents can
|
|
use to inspect repository state safely. All git tools are **read-only** --
|
|
no destructive operations (commit, push, reset, checkout) are available in
|
|
the MVP.
|
|
|
|
## Tools
|
|
|
|
| Tool | Description | Read-only |
|
|
|------------------------|-------------------------------------|-----------|
|
|
| `builtin/git-status` | Show working tree status | Yes |
|
|
| `builtin/git-diff` | Show changes in working tree | Yes |
|
|
| `builtin/git-log` | Show commit log | Yes |
|
|
| `builtin/git-blame` | Show line-by-line file attribution | Yes |
|
|
|
|
## Safety Settings
|
|
|
|
All git tools run with the following environment variables to ensure
|
|
deterministic output and prevent interactive prompts:
|
|
|
|
| Variable | Value | Purpose |
|
|
|-------------------------|---------|--------------------------------------|
|
|
| `GIT_PAGER` | `cat` | Disable paging |
|
|
| `GIT_TERMINAL_PROMPT` | `0` | Disable interactive credential input |
|
|
| `GIT_ASKPASS` | (empty) | Disable GUI credential helpers |
|
|
| `NO_COLOR` | `1` | Strip ANSI colour codes |
|
|
| `GIT_CONFIG_NOSYSTEM` | `1` | Ignore system-wide config |
|
|
| `TERM` | `dumb` | Prevent terminal escape sequences |
|
|
|
|
Additionally, git commands are run with `--no-pager -c color.ui=never`
|
|
flags, and the target directory is marked as `safe.directory` via
|
|
environment-based git config injection.
|
|
|
|
## Path Guards
|
|
|
|
All tools accept an optional `repo_path` parameter. Path validation
|
|
follows these rules:
|
|
|
|
1. **No input** -- uses the current working directory.
|
|
2. **Absolute paths** -- accepted as-is (trusted sandbox paths).
|
|
3. **Relative paths** -- resolved against cwd, then checked for `..`
|
|
traversal. Paths that escape the sandbox root are rejected with a
|
|
`ValueError`.
|
|
|
|
## Error Mapping
|
|
|
|
Common git errors are translated to user-friendly messages:
|
|
|
|
| Git Error Pattern | Friendly Message |
|
|
|--------------------------------|-------------------------------------------------------------------|
|
|
| `not a git repository` | The specified path is not a git repository. |
|
|
| `fatal: bad default revision` | No commits exist in this repository yet. |
|
|
| `HEAD detached` | Repository is in a detached HEAD state; some operations may ... |
|
|
| `pathspec` | The specified file or path does not exist in the repository. |
|
|
| `unknown revision or path` | Unknown revision or path not in the working tree. |
|
|
|
|
## Usage
|
|
|
|
### Registration
|
|
|
|
```python
|
|
from cleveragents.tool.builtins import register_git_tools
|
|
from cleveragents.tool.registry import ToolRegistry
|
|
|
|
registry = ToolRegistry()
|
|
register_git_tools(registry)
|
|
```
|
|
|
|
### Execution
|
|
|
|
```python
|
|
from cleveragents.tool.runner import ToolRunner
|
|
|
|
runner = ToolRunner(registry)
|
|
|
|
# Show working tree status
|
|
result = runner.execute("builtin/git-status", {"repo_path": "/sandbox/repo"})
|
|
print(result.output["output"])
|
|
|
|
# Show diff with stat summary
|
|
result = runner.execute("builtin/git-diff", {
|
|
"repo_path": "/sandbox/repo",
|
|
"stat": True,
|
|
})
|
|
|
|
# Show last 5 commits in oneline format
|
|
result = runner.execute("builtin/git-log", {
|
|
"repo_path": "/sandbox/repo",
|
|
"max_count": 5,
|
|
"oneline": True,
|
|
})
|
|
|
|
# Blame a specific file range
|
|
result = runner.execute("builtin/git-blame", {
|
|
"repo_path": "/sandbox/repo",
|
|
"path": "src/main.py",
|
|
"line_start": 10,
|
|
"line_end": 20,
|
|
})
|
|
```
|
|
|
|
## Security Rationale
|
|
|
|
Only read-only operations are exposed because:
|
|
|
|
1. Agents should **observe** repository state, not mutate it directly.
|
|
2. Mutations (commits, merges, pushes) must go through the plan
|
|
lifecycle -- strategize, execute, apply -- with human review gates.
|
|
3. Limiting the git tool surface prevents accidental data loss from
|
|
agent hallucinations (e.g. `git reset --hard`).
|