# Git Integration

> This documentation covers Pro edition features available in the agents-orchestrator/agents-orchestrator private repository.

Git Integration provides two features: Git Context Injection (branch, commit, and diff information formatted for agent prompts) and Branch Policy (session-level protection for sensitive branches).

---

## Git Context Injection

### Purpose

Git Context Injection gathers repository state and formats it as markdown for inclusion in agent system prompts. This gives agents awareness of the current branch, recent commits, and modified files without requiring them to run git commands.

### Context Gathering

The system collects three categories of information by invoking the `git` CLI:

#### Branch Information

- Current branch name (`git rev-parse --abbrev-ref HEAD`)
- Tracking branch and ahead/behind counts (`git rev-list --left-right --count`)
- Last commit on branch (hash, author, date, subject)

#### Recent Commits

- Last N commits on the current branch (default: 10)
- Each commit includes: short hash, author, relative date, subject line
- Collected via `git log --oneline --format`

#### Modified Files

- Staged files (`git diff --cached --name-status`)
- Unstaged modifications (`git diff --name-status`)
- Untracked files (`git ls-files --others --exclude-standard`)

### Formatted Output

The collected information is formatted as a markdown section:

```markdown
## Git Context

**Branch:** feature/new-dashboard (ahead 3, behind 0 of origin/main)

### Recent Commits (last 10)
- `a1b2c3d` (2 hours ago) fix: resolve null check in analytics
- `e4f5g6h` (5 hours ago) feat: add daily cost chart
- ...

### Working Tree
**Staged:**
- M src/lib/components/Analytics.svelte
- A src/lib/stores/analytics.svelte.ts

**Modified:**
- M src/lib/adapters/pro-bridge.ts

**Untracked:**
- tests/analytics.test.ts
```

### Commands

#### pro_git_context

Gathers all git context for a project directory and returns formatted markdown.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cwd` | `String` | Yes | Absolute path to the git repository |
| `commitCount` | `u32` | No | Number of recent commits to include (default: 10) |

**Response:**

```typescript
interface GitContext {
  markdown: string;      // Formatted markdown section
  branch: string;        // Current branch name
  isDirty: boolean;      // Has uncommitted changes
  aheadBehind: [number, number]; // [ahead, behind]
}
```

#### pro_git_inject

Convenience command that gathers git context and prepends it to a given system prompt.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cwd` | `String` | Yes | Repository path |
| `systemPrompt` | `String` | Yes | Existing system prompt to augment |
| `commitCount` | `u32` | No | Number of recent commits (default: 10) |

Returns the combined prompt string.

#### pro_git_branch_info

Returns structured branch information without formatting.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cwd` | `String` | Yes | Repository path |

**Response:**

```typescript
interface BranchInfo {
  name: string;
  trackingBranch: string | null;
  ahead: number;
  behind: number;
  lastCommitHash: string;
  lastCommitSubject: string;
  lastCommitDate: string;
}
```

### Implementation Notes

- All git commands are executed via `std::process::Command` (not libgit2). This avoids a heavy native dependency and matches the git CLI behavior users expect.
- Commands run with a 5-second timeout. If git is not installed or the directory is not a repository, commands return structured errors.
- Output encoding is handled as UTF-8 with lossy conversion for non-UTF-8 paths.

---

## Branch Policy

### Purpose

Branch Policy prevents agents from making commits or modifications on protected branches. This is a session-level safeguard -- the policy is checked when an agent session starts and when git operations are detected in tool calls.

### Protection Rules

Protected branch patterns are configurable per project. The defaults are:

| Pattern | Matches |
|---------|---------|
| `main` | Exact match |
| `master` | Exact match |
| `release/*` | Any branch starting with `release/` |

When an agent session starts on a protected branch, the system emits a warning notification. It does not block the session, because agents may need to read code on these branches. However, the branch name is included in the agent's system prompt with a clear instruction not to commit.

### Commands

#### pro_branch_check

Checks whether the current branch is protected.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cwd` | `String` | Yes | Repository path |
| `projectId` | `String` | Yes | Project identifier (for project-specific policies) |

**Response:**

```typescript
interface BranchCheckResult {
  branch: string;
  isProtected: boolean;
  matchedPattern: string | null; // Which pattern matched
}
```

#### pro_branch_policy_set

Sets custom protected branch patterns for a project. Replaces any existing patterns.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `projectId` | `String` | Yes | Project identifier |
| `patterns` | `Vec<String>` | Yes | Branch patterns (exact names or glob with `*`) |

#### pro_branch_policy_get

Returns the current branch policy for a project. Returns default patterns if none are set.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `projectId` | `String` | Yes | Project identifier |

#### pro_branch_policy_delete

Removes custom branch policy for a project, reverting to defaults.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `projectId` | `String` | Yes | Project identifier |

### Integration

Branch policy is checked at two points:

1. **Session start:** `AgentSession.startQuery()` calls `pro_branch_check`. If protected, a warning toast is shown and the branch protection instruction is appended to the system prompt.
2. **System prompt injection:** The formatted git context (from `pro_git_inject`) includes a `PROTECTED BRANCH` warning banner when applicable.