Relevant source files

The following files were used as context for generating this wiki page: - [apps/desktop/src/main/services/git/GitBranchService.ts](https://github.com/AgentOrchestrator/AgentBase/blob/main/apps/desktop/src/main/services/git/GitBranchService.ts) - [apps/desktop/src/main/main.ts](https://github.com/AgentOrchestrator/AgentBase/blob/main/apps/desktop/src/main/main.ts) - [apps/desktop/src/renderer/components/NewAgentModal.tsx](https://github.com/AgentOrchestrator/AgentBase/blob/main/apps/desktop/src/renderer/components/NewAgentModal.tsx) - [apps/desktop/src/main/worktree/WorktreeManager.ts](https://github.com/AgentOrchestrator/AgentBase/blob/main/apps/desktop/src/main/worktree/WorktreeManager.ts) - [apps/desktop/src/renderer/hooks/__tests__/useWorktreeConfigState.test.ts](https://github.com/AgentOrchestrator/AgentBase/blob/main/apps/desktop/src/renderer/hooks/__tests__/useWorktreeConfigState.test.ts) - [apps/desktop/src/renderer/utils/worktreeUtils.ts](https://github.com/AgentOrchestrator/AgentBase/blob/main/apps/desktop/src/renderer/utils/worktreeUtils.ts)

# Git Branch & Fork Services The Git Branch & Fork Services provide the infrastructure for managing version control state and isolated execution environments within AgentBase. These services allow the application to resolve repository metadata, manage branches, and provision isolated git worktrees for parallel agent executions. By leveraging native git commands and automated worktree management, the system ensures that multiple AI agents can work on the same project simultaneously without conflicting edits. ## Git Metadata & Branch Management The core of git integration lies in the `GitBranchService`, which executes low-level git commands to resolve repository state. This service is used by the main process to provide strict information about the current branch, remote tracking, and working directory status. ### Git Information Resolution The system fetches a comprehensive `GitInfo` object that includes the current branch name, remote name, sync status (ahead/behind counts), and whether the repository is "dirty" (has uncommitted changes). ```mermaid flowchart TD A[Request Git Info] --> B{Path Exists?} B -- No --> C[Throw Error] B -- Yes --> D[Run: git rev-parse --abbrev-ref HEAD] D --> E[Check Remote: git config --get branch.BRANCH.remote] E --> F[Check Status: git status --porcelain] F --> G[Check Sync: git rev-list --left-right --count] G --> H[Return GitInfo Object] subgraph GitInfo Fields H1[branch] H2[remote] H3[status: clean/dirty] H4[ahead/behind counts] end ``` Sources: [apps/desktop/src/main/services/git/GitBranchService.ts:60-116](), [apps/desktop/src/main/main.ts:1040-1043]() ### Branch Operations The application supports creating new branches and switching between existing ones. The `NewAgentModal` UI provides a search and selection interface for branches, while the main process handles the execution of `git checkout` and `git branch` commands. | Operation | Git Command Equivalent | Description | | :--- | :--- | :--- | | **List Branches** | `git branch --format=%(refname:short)` | Retrieves all local branches for a workspace. | | **Create Branch** | `git checkout -b ` | Creates and immediately switches to a new branch. | | **Checkout** | `git checkout ` | Switches the working directory to an existing branch. | | **Get Info** | `git rev-parse --git-dir` | Validates if a directory is a valid git repository. | Sources: [apps/desktop/src/main/main.ts:1003-1100](), [apps/desktop/src/main/services/git/GitBranchService.ts:46-52]() ## Forking & Isolated Worktrees Forking in AgentBase involves creating a new agent session from an existing one, often accompanied by an isolated git worktree to prevent file conflicts. ### Worktree Management Architecture The `WorktreeManager` is responsible for provisioning and releasing git worktrees. A worktree allows a single repository to have multiple linked working directories, each checked out to a different branch. ```mermaid sequenceDiagram participant UI as New Agent Modal participant WM as Worktree Manager participant Git as Git CLI participant DB as Worktree Store UI->>WM: provision(repoPath, branchName, options) WM->>Git: validateRepository(repoPath) WM->>DB: insert(status: 'provisioning') WM->>Git: branch exists? Note right of Git: If No: git branch WM->>Git: git worktree add WM->>DB: updateStatus('active') WM-->>UI: WorktreeInfo (Ready) ``` Sources: [apps/desktop/src/main/worktree/WorktreeManager.ts:41-98](), [apps/desktop/src/main/main.ts:1145-1158]() ### Worktree Configuration Logic When a user prepares to fork or start a new agent, the `useWorktreeConfigState` hook manages the automatic generation of branch and folder names based on the task description. * **Sanitization**: Task descriptions are sanitized to remove special characters and spaces for branch compatibility. * **Truncation**: Descriptions are truncated to 30 characters for path safety. * **Defaults**: If no description is provided, the system uses a timestamp-based fallback (e.g., `feature/agent-1712345678`). * **Manual Override**: Once a user manually edits a branch or folder name, the auto-generation from description is disabled for that field to preserve user intent. Sources: [apps/desktop/src/renderer/hooks/__tests__/useWorktreeConfigState.test.ts:80-155](), [apps/desktop/src/renderer/components/NewAgentModal.tsx:440-455]() ## Path Resolution and Matching In the renderer process, `worktreeUtils` provide helpers to bridge the gap between file system paths and the visual canvas. ### Workspace Identification The system identifies which workspace a file belongs to by comparing normalized paths. This is critical for the "Isolated Edits" feature where the UI must know if a file is being opened from the original repository or an agent-specific worktree. ```typescript export async function arePathsFromSameRepo(path1: string, path2: string): Promise { const repoRoot1 = await getGitRepoRoot(path1); const repoRoot2 = await getGitRepoRoot(path2); if (!repoRoot1 || !repoRoot2) return false; return path.normalize(repoRoot1) === path.normalize(repoRoot2); } ``` Sources: [apps/desktop/src/renderer/utils/worktreeUtils.ts:109-122](), [apps/desktop/src/renderer/utils/worktreeUtils.ts:130-150]() ### Matching Files Across Worktrees When a user is viewing a file in one agent's workspace, the `findMatchingWorktrees` utility can locate the equivalent file in other agents' workspaces. It performs a "filename-only" match across all active agent nodes to allow users to quickly compare how different parallel agents have modified the same logical file. Sources: [apps/desktop/src/renderer/utils/worktreeUtils.ts:124-220]() ## Conclusion The Git Branch & Fork Services form the backbone of the AgentBase parallel execution model. By combining strict metadata resolution via `GitBranchService` with automated lifecycle management in `WorktreeManager`, the application enables complex multi-agent workflows while maintaining version control integrity. The integration of UI-level configuration hooks ensures that developers can spawn isolated environments with minimal manual overhead.