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

Git History Visualization Specification

Requirements

Functional Requirements

1. View Commit History: Display all commits in a repository
2. Graph Visualization: Show commits as nodes with branch/merge lines
3. List View: Alternative linear view of commits
4. Commit Details: Click to view full commit info and diff
5. Branch Display: Show branch names on commits
6. Tag Display: Show tags on commits
7. View Toggle: Switch between graph and list views

Non-Functional Requirements

1. Performance: Load first 100 commits in < 2 seconds
2. Responsiveness: Graph should render smoothly up to 500 commits
3. Compatibility: Work with bare repositories and mirror clones
4. Read-only: No write operations to repository

API Specification

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

Retrieve commit history for a repository.

Query Parameters:

Parameter	Type	Default	Description
view	string	"graph"	"graph" or "list"
branch	string	null	Filter by branch name
limit	integer	100	Max commits to return
offset	integer	0	Skip first N commits

Response 200:

{
  "commits": [
    {
      "hash": "full-sha-hash",
      "short_hash": "abc1234",
      "parents": ["parent-hash-1", "parent-hash-2"],
      "author": "John Doe",
      "email": "john@example.com",
      "date": "2026-05-19",
      "timestamp": 1716123456,
      "message": "feat: add new feature",
      "branches": ["main"],
      "tags": []
    }
  ],
  "branches": ["main", "develop", "feature/x"],
  "total_commits": 250,
  "graph_data": {
    "nodes": [
      {
        "hash": "abc1234",
        "x": 0,
        "y": 0,
        "column": 0
      }
    ],
    "edges": [
      {
        "from_hash": "abc1234",
        "to_hash": "def5678",
        "type": "parent"
      }
    ]
  }
}

GET /projects/{project_id}/repositories/{repo_id}/commits/{commit_hash}

Get detailed information about a specific commit.

Response 200:

{
  "hash": "full-sha-hash",
  "short_hash": "abc1234",
  "parents": ["parent-hash"],
  "author": "John Doe",
  "email": "john@example.com",
  "date": "2026-05-19",
  "timestamp": 1716123456,
  "message": "feat: add new feature",
  "body": "Detailed description here",
  "stats": {
    "files_changed": 3,
    "insertions": 45,
    "deletions": 12
  },
  "files": [
    {
      "path": "src/main.py",
      "change_type": "modified",
      "insertions": 20,
      "deletions": 5,
      "diff": "diff content here"
    }
  ]
}

Frontend Components

GitHistoryPage

Main page component that orchestrates the view.

GraphView

SVG-based commit graph visualization.

Props:

• commits: Commit[]
• graphData: GraphData
• selectedCommit: string | null
• onCommitSelect: (hash: string) => void

ListView

Linear commit list.

Props:

• commits: Commit[]
• selectedCommit: string | null
• onCommitSelect: (hash: string) => void

CommitDetails

Panel showing commit details and diff.

Props:

• commit: CommitDetail | null

DiffViewer

Component to display git diff with syntax highlighting.

Props:

• files: FileChange[]

Data Models

Commit

interface Commit {
  hash: string;
  short_hash: string;
  parents: string[];
  author: string;
  email: string;
  date: string;
  timestamp: number;
  message: string;
  branches: string[];
  tags: string[];
}

CommitDetail

interface CommitDetail extends Commit {
  body: string;
  stats: {
    files_changed: number;
    insertions: number;
    deletions: number;
  };
  files: FileChange[];
}

FileChange

interface FileChange {
  path: string;
  change_type: "added" | "modified" | "deleted" | "renamed";
  insertions: number;
  deletions: number;
  diff: string;
}

URL Structure

/projects/:projectId/repositories/:repoId/history

Error Codes

Error Code	Description	User Message
REPO_EMPTY	Repository has no commits	"This repository has no commits yet"
GIT_ERROR	Git command failed	"Failed to load repository history"
COMMIT_NOT_FOUND	Commit hash not found	"Commit not found"
INVALID_BRANCH	Branch doesn't exist	"Branch not found"

Testing Strategy

Backend Tests

• Test git log parsing with various repo structures
• Test commit detail extraction
• Test error handling for empty repos

Frontend Tests

• Test graph rendering with sample data
• Test list view rendering
• Test commit selection and details display
• Test view toggle

Integration Tests

• End-to-end flow: load history → select commit → view details