9894cdd06f
Adds FileStatEntry type and two new primitives to the BranchManager port and SimpleGitBranchManager adapter, enabling split diff procedures in the tRPC layer without returning raw multi-megabyte diffs. - FileStatEntry captures path, status, additions/deletions, oldPath (renames), and optional projectId for multi-project routing - diffBranchesStat uses --name-status + --numstat, detects binary files (shown as - / - in numstat), handles spaces in filenames - diffFileSingle returns raw unified diff for a single file path
114 lines
4.1 KiB
TypeScript
114 lines
4.1 KiB
TypeScript
/**
|
|
* BranchManager Port Interface
|
|
*
|
|
* Manages branch-level git operations (create, merge, diff, delete)
|
|
* across project clones. Works directly on branches without requiring
|
|
* a worktree to be checked out.
|
|
*/
|
|
|
|
import type { MergeResult, MergeabilityResult, BranchCommit, FileStatEntry } from './types.js';
|
|
|
|
export interface BranchManager {
|
|
/**
|
|
* Ensure a branch exists. Creates it from baseBranch if it doesn't.
|
|
* Idempotent — no-op if the branch already exists.
|
|
*/
|
|
ensureBranch(repoPath: string, branch: string, baseBranch: string): Promise<void>;
|
|
|
|
/**
|
|
* Merge sourceBranch into targetBranch.
|
|
* Uses an ephemeral worktree for merge safety.
|
|
* Returns conflict info if merge fails.
|
|
*/
|
|
mergeBranch(repoPath: string, sourceBranch: string, targetBranch: string): Promise<MergeResult>;
|
|
|
|
/**
|
|
* Get the raw unified diff between two branches.
|
|
* Uses three-dot diff (baseBranch...headBranch) to show changes
|
|
* introduced by headBranch since it diverged from baseBranch.
|
|
*/
|
|
diffBranches(repoPath: string, baseBranch: string, headBranch: string): Promise<string>;
|
|
|
|
/**
|
|
* Get per-file metadata for changes between two branches.
|
|
* Uses three-dot diff (baseBranch...headBranch) — same divergence model as diffBranches.
|
|
* Binary files are included with status 'binary' and additions/deletions both 0.
|
|
* Does NOT return hunk content.
|
|
*/
|
|
diffBranchesStat(repoPath: string, baseBranch: string, headBranch: string): Promise<FileStatEntry[]>;
|
|
|
|
/**
|
|
* Get the raw unified diff for a single file between two branches.
|
|
* Uses three-dot diff (baseBranch...headBranch).
|
|
* Returns empty string for binary files (caller must detect binary separately).
|
|
* filePath must be URL-decoded before being passed here.
|
|
*/
|
|
diffFileSingle(repoPath: string, baseBranch: string, headBranch: string, filePath: string): Promise<string>;
|
|
|
|
/**
|
|
* Delete a branch. No-op if the branch doesn't exist.
|
|
*/
|
|
deleteBranch(repoPath: string, branch: string): Promise<void>;
|
|
|
|
/**
|
|
* Check if a branch exists in the repository.
|
|
*/
|
|
branchExists(repoPath: string, branch: string): Promise<boolean>;
|
|
|
|
/**
|
|
* Check if a branch exists as a remote tracking branch (origin/<branch>).
|
|
* Useful for validating branch names against what the remote has,
|
|
* since local branches may not include all remote branches.
|
|
*/
|
|
remoteBranchExists(repoPath: string, branch: string): Promise<boolean>;
|
|
|
|
/**
|
|
* List commits that headBranch has but baseBranch doesn't.
|
|
* Used for commit-level navigation in code review.
|
|
*/
|
|
listCommits(repoPath: string, baseBranch: string, headBranch: string): Promise<BranchCommit[]>;
|
|
|
|
/**
|
|
* Get the raw unified diff for a single commit.
|
|
*/
|
|
diffCommit(repoPath: string, commitHash: string): Promise<string>;
|
|
|
|
/**
|
|
* Get the merge base (common ancestor) of two branches.
|
|
* Returns the commit hash of the merge base.
|
|
*/
|
|
getMergeBase(repoPath: string, branch1: string, branch2: string): Promise<string>;
|
|
|
|
/**
|
|
* Push a branch to a remote.
|
|
* Defaults to 'origin' if no remote specified.
|
|
*/
|
|
pushBranch(repoPath: string, branch: string, remote?: string): Promise<void>;
|
|
|
|
/**
|
|
* Dry-run merge check — determines if sourceBranch can be cleanly merged
|
|
* into targetBranch without actually performing the merge.
|
|
* Uses `git merge-tree --write-tree` (git 2.38+).
|
|
*/
|
|
checkMergeability(repoPath: string, sourceBranch: string, targetBranch: string): Promise<MergeabilityResult>;
|
|
|
|
/**
|
|
* Fetch all refs from a remote.
|
|
* Defaults to 'origin' if no remote specified.
|
|
*/
|
|
fetchRemote(repoPath: string, remote?: string): Promise<void>;
|
|
|
|
/**
|
|
* Fast-forward a local branch to match its remote-tracking counterpart.
|
|
* No-op if already up to date. Throws if fast-forward is not possible
|
|
* (i.e. the branches have diverged).
|
|
*/
|
|
fastForwardBranch(repoPath: string, branch: string, remote?: string): Promise<void>;
|
|
|
|
/**
|
|
* Force-update a branch ref to point at a specific commit.
|
|
* Used to roll back a merge when a subsequent push fails.
|
|
*/
|
|
updateRef(repoPath: string, branch: string, commitHash: string): Promise<void>;
|
|
}
|