headquarter/openspec/changes/archive/2026-05-19-git-control/specs/spec.md

Git Control Specification

Requirements

Functional Requirements

1. Branch Management: Create, delete, list, and switch branches
2. Working Directory: View modified, added, deleted, and untracked files
3. Commit Changes: Stage and commit file changes with message
4. Remote Sync: Fetch, pull, and push to remote repositories
5. Merge Branches: Merge one branch into another
6. Status Indicators: Show file modification status in file tree

Non-Functional Requirements

1. Performance: Git operations complete in < 3 seconds
2. Feedback: Show progress for long operations (push, pull, merge)
3. Error Handling: Clear error messages for all git failures
4. Safety: Confirm destructive operations (delete branch, force push)

API Specification

Branch Operations

POST /projects/{project_id}/repositories/{repo_id}/branches

Create a new branch.

Request:

{
  "name": "feature/new-thing",
  "base_branch": "main"
}

Response 201:

{
  "name": "feature/new-thing",
  "base_commit": "abc123"
}

Response 400: Branch already exists

DELETE /projects/{project_id}/repositories/{repo_id}/branches/{branch_name}

Delete a branch.

Response 204: Success

Response 400: Cannot delete current branch

POST /projects/{project_id}/repositories/{repo_id}/checkout

Checkout a branch.

Request:

{
  "branch": "feature/new-thing"
}

Response 200:

{
  "branch": "feature/new-thing",
  "commit": "abc123"
}

Response 400: Uncommitted changes

Status Operations

GET /projects/{project_id}/repositories/{repo_id}/status

Get working directory status.

Response 200:

{
  "branch": "main",
  "ahead": 2,
  "behind": 1,
  "modified": ["src/main.py"],
  "added": ["new-file.txt"],
  "deleted": [],
  "untracked": ["temp.log"],
  "renamed": []
}

Commit Operations

POST /projects/{project_id}/repositories/{repo_id}/commits

Commit staged changes.

Request:

{
  "message": "Update greeting",
  "author_name": "User",
  "author_email": "user@example.com"
}

Response 201:

{
  "hash": "def789",
  "message": "Update greeting",
  "branch": "main"
}

Response 400: Nothing to commit

Remote Operations

POST /projects/{project_id}/repositories/{repo_id}/fetch

Fetch from remote.

Response 200:

{
  "success": true,
  "fetched_branches": ["origin/main", "origin/develop"]
}

POST /projects/{project_id}/repositories/{repo_id}/pull

Pull updates from remote.

Request:

{
  "branch": "main"
}

Response 200:

{
  "success": true,
  "commits": 3,
  "files_changed": ["src/main.py", "README.md"]
}

Response 409: Merge conflict

POST /projects/{project_id}/repositories/{repo_id}/push

Push to remote.

Request:

{
  "branch": "main"
}

Response 200:

{
  "success": true,
  "pushed_commits": 2
}

Response 400: Non-fast-forward

Merge Operations

POST /projects/{project_id}/repositories/{repo_id}/merge

Merge branches.

Request:

{
  "source_branch": "feature/new-thing",
  "target_branch": "main",
  "commit_message": "Merge feature into main"
}

Response 200:

{
  "success": true,
  "commit_hash": "abc789",
  "files_changed": 5
}

Response 409: Merge conflict

Data Model

GitStatus

interface GitStatus {
  branch: string;
  ahead: number;
  behind: number;
  modified: string[];
  added: string[];
  deleted: string[];
  untracked: string[];
  renamed: Array<{from: string, to: string}>;
}

CommitInfo

interface CommitInfo {
  hash: string;
  message: string;
  branch: string;
  author_name: string;
  author_email: string;
  date: string;
}

Frontend Specification

Components

GitToolbar:

• Fetch button
• Pull button (with behind count badge)
• Push button (with ahead count badge)
• Branch selector (with create/delete)
• Commit button (enabled when changes exist)
• Merge button

BranchSelector:

• Dropdown with all branches
• Current branch highlighted
• "Create new branch" option
• Delete option (with confirmation)

CommitPanel:

• Shows when files are modified
• Lists changed files with checkboxes
• Commit message input
• Commit button

StatusIndicator:

• Small badge on file tree items
• Shows modification type

State Management

interface GitControlState {
  status: GitStatus | null;
  isLoading: boolean;
  operations: Array<{
    type: string;
    status: 'pending' | 'success' | 'error';
    message: string;
  }>;
}

Error Handling

Error Code	Description	User Action
DIRTY_WORKING_TREE	Uncommitted changes	Commit or stash changes
MERGE_CONFLICT	Merge failed with conflicts	Resolve conflicts manually
NON_FAST_FORWARD	Push rejected	Pull first
AUTH_FAILED	Remote auth failed	Check SSH keys
BRANCH_EXISTS	Branch already exists	Choose different name
NOTHING_TO_COMMIT	Working tree clean	N/A
CANNOT_DELETE_CURRENT	Can't delete checked out branch	Switch branches first

Testing Strategy

Backend Tests

• Test branch creation/deletion
• Test checkout with/without changes
• Test commit operations
• Test fetch/pull/push
• Test merge (fast-forward and conflict)
• Test error cases

Frontend Tests

• Test toolbar buttons
• Test branch selector
• Test commit panel
• Test status indicators
• Test error handling

Integration Tests

• Full workflow: create branch → edit file → commit → push → merge