Feature: Branch Operations (checkout, merge, rebase)

[BishopMowle]

Overview

Implement advanced branch operations to enable switching branches, merging, and rebasing, matching isomorphic-git feature parity.

Commands to Implement

• checkout - Switch branches or restore working tree files
• switch - Switch branches (modern alternative to checkout)
• merge - Merge one branch into another
• abortMerge - Abort an in-progress merge
• rebase - Reapply commits on top of another base tip
• listBranches - List all local (and optionally remote) branches
• deleteBranch - Delete a branch
• currentBranch - Get the current branch name

Acceptance Criteria (AC)

1. AC1: Checkout Functionality - Can switch between branches, preserving working tree changes
2. AC2: Merge Functionality - Can perform fast-forward and recursive merges with conflict detection
3. AC3: Rebase Functionality - Can rebase a branch onto another with proper commit replay
4. AC4: Branch Listing - Can list all branches and identify current branch
5. AC5: Merge Conflict Handling - Properly detects and reports merge conflicts without auto-resolving
6. AC6: Abort Operations - Can abort in-progress merge/rebase operations

Definition of Done (DoD)

• All commands implemented with proper error handling
• Unit tests with >80% coverage
• Interop tests passing
• Documentation in README.md
• No TypeScript errors or warnings

Interop Test Method

// Setup test repo
const repoDir = '/tmp/test-branch-ops';
await tsGit.init({ fs, dir: repoDir, defaultBranch: 'main' });
// Create commits on main and feature branches...

// Test merge
await tsGit.merge({ fs, dir: repoDir, ours: 'main', theirs: 'feature' });
const tsGitLog = await tsGit.log({ fs, dir: repoDir, depth: 3 });

// Compare with canonical git
execSync('git merge feature', { cwd: '/tmp/ref-repo' });
const refLog = execSync('git log --oneline -3', { cwd: '/tmp/ref-repo' }).toString();

// Verify merge commit structure matches

Validation Strategy:

1. Create identical repo state in ts-git and canonical git
2. Perform branch operations (checkout, merge, rebase)
3. Compare resulting commit graph, tree state, and branch refs
4. Test conflict scenarios with prepared conflict files

Priority

High - Essential for collaborative workflows

Dependencies

• Requires plumbing commands (cat-file, update-index) for tree manipulation

[BishopMowle]

Issue #6: Branch Operations - AC/DoD

Context

Following Issue #5 (Remote Operations), branch management is the logical next step for a complete Git implementation.

Commands to Implement

Command	Description
checkout	Switch branches or restore files
checkout -b	Create and switch to new branch
merge	Join two or more development histories
rebase	Reapply commits on top of another base
branch	List, create, or delete branches

Acceptance Criteria (AC)

AC1: Checkout Functionality

• Can switch to existing branch
• Can create new branch with -b flag
• Handles detached HEAD state
• Discards uncommitted changes appropriately

AC2: Merge Functionality

• Can fast-forward merge when possible
• Can perform three-way merge
• Handles merge conflicts (detect and report)
• Creates merge commit when needed

AC3: Rebase Functionality

• Can rebase onto another branch
• Handles merge conflicts during rebase
• Preserves commit history

AC4: Branch Management

• List all local branches
• List all remote tracking branches
• Create new branch
• Delete branch (-d, -D)

AC5: Type Safety

• All functions have strict TypeScript types
• No any or unknown types in parameters/returns

Definition of Done (DoD)

• All commands implemented with error handling
• Unit tests with >80% coverage
• Interop tests passing (canonical git CLI)
• Documentation in README.md
• Zero TypeScript errors/warnings

---

Waiting for Edwards approval before implementation begins

[BishopMowle]

Issue #6: Branch Operations - AC/DoD (Revised)

Context

Rebase has been split into Issue #8. This issue covers basic branch operations.

Commands to Implement

Command	Description
checkout	Switch branches or restore files
checkout -b	Create and switch to new branch
merge	Join two or more development histories
branch	List, create, or delete branches

Note: Rebase moved to Issue #8

Acceptance Criteria (AC)

AC1: Checkout Functionality

• Can switch to existing branch
• Can create new branch with -b flag
• Handles detached HEAD state
• Discards uncommitted changes appropriately

AC2: Merge Functionality

• Can fast-forward merge when possible
• Can perform three-way merge
• Handles merge conflicts (detect and report)
• Creates merge commit when needed

AC3: Branch Management

• List all local branches
• List all remote tracking branches
• Create new branch
• Delete branch (-d, -D)

AC4: Type Safety

• All functions have strict TypeScript types
• No any or unknown types in parameters/returns

Definition of Done (DoD)

• All commands implemented with error handling
• Unit tests with >80% coverage
• Interop tests passing (canonical git CLI)
• Documentation in README.md
• Zero TypeScript errors/warnings

---

Waiting for Edwards approval before implementation begins