worktree

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package worktree 管理 git worktree:为每个 session 创建独立工作树 + 分支, 实现并行隔离(参考 orca 的 parallel worktree 模型)。 项目 = 主 repo;session = 主 repo 的一个 worktree(独立分支 + 独立工作目录)。 opencode 仍走 ACP,只是 cwd 指向 worktree(不违反 §1.1 纯 ACP)。

Index

Constants

View Source
const MDPrefix = "md/"

MDPrefix is the prefix of app-created session branches (§1.4: md/<session-id-8>). Remove only deletes branches with this prefix; chat.worktreeKindOf uses it to tell owner from guest. Exported so the md/<id8> convention has a single source of truth.

Variables

View Source
var ErrNoBaseRef = errors.New("no default base ref found")

ErrNoBaseRef 探测不到默认基线分支(无 main/master 且无 origin/HEAD)。 Route A strict:不回退 HEAD,由调用方强制用户显式选(todo/worktree-base-ref-selection.md §2)。

View Source
var ErrNotARepo = errors.New("not a git repository")

ErrNotARepo 路径不是 git 仓库。

Functions

func BranchExists

func BranchExists(repoPath, branch string) bool

BranchExists 报告 branch 是否存在于 repoPath。

func BranchLog

func BranchLog(repoPath, branch, base string) (string, error)

BranchLog 返回 branch 相对 base 的 commit 列表(一行一条),供"这个分支干了什么"展示。 base 为空则用主仓库 HEAD(旧行为)。有显式基线的 session 应传 se.BaseRef。

func Commit

func Commit(worktreePath, message string) error

Commit 提交已暂存的改动(只 commit index,不自动 add;区别于 AutoCommit)。 无暂存改动时返回 git 的 "nothing to commit" 错误。

func Create

func Create(repoPath, branch, targetPath, baseRef string) error

Create 在 repoPath 的 baseRef 基础上,新建分支 branch 并检出工作树到 targetPath。 baseRef 为空则用 HEAD。targetPath 不能已存在。 --no-track:避免新建分支自动配置 upstream 跟踪,首次 push 前 git status 误报 "behind by N"(§1.4)。

func DiffStat

func DiffStat(repoPath, branch, base string) (string, error)

DiffStat 返回 branch 相对 base 的变更摘要(git diff --stat)。 base 为空则用主仓库 HEAD(旧行为:主仓库在基线分支时碰巧等价)。 有显式基线的 session 应传 se.BaseRef,避免主仓库 HEAD 飘走后增量算错(todo §13 review 补漏)。 格式如 "3 files changed, 15 insertions(+), 5 deletions(-)"。无变更返回空串。

func Discard

func Discard(worktreePath string, paths ...string) error

Discard 丢弃工作区改动:已跟踪文件 checkout 还原,未跟踪文件 clean 删除。 只应用于工作区(Staged=false)的文件;暂存区改动用 Unstage。路径为空无操作。

func FileDiff

func FileDiff(worktreePath, path string, staged bool) (string, error)

FileDiff 返回单个文件的 unified diff,供源代码管理面板点击文件查看改动(VSCode SCM 风格)。

  • staged=true:index 相对 HEAD(git diff --cached)。
  • staged=false:已跟踪文件取工作区相对 index(git diff);未跟踪文件无 index/HEAD 版本, 用 --no-index 对照 /dev/null 展示为纯新增。

func FindSubRepo

func FindSubRepo(root string) string

FindSubRepo 在 root 下(限深 + 剪枝)搜索第一个本身是 git 仓库的子目录,返回其绝对路径; 没找到(root 无 git 子仓库)返回 ""。root 自身不是候选(调用方应先用 IsRepo(root))。

搜索是 best-effort:浅层(默认 2 级)+ 跳过依赖 / 构建目录(那些常含 vendored .git,假阳性)。 每个候选先用 os.Stat 探 .git(快),再用 IsRepo 确认是有效工作树,避免坏 .git / 子模块 gitdir 指针失效等边界误报。命中即返回(ReadDir 已按名字排序,结果稳定可复现)。

func HasChanges

func HasChanges(worktreePath string) bool

HasChanges 报告 worktreePath 是否有未提交的改动(含 untracked)。

func HeadShort

func HeadShort(repoPath string) (string, error)

HeadShort 返回当前 HEAD 的短引用(分支名或 commit 前 7 位)。

func IsRepo

func IsRepo(path string) bool

IsRepo 报告 path 是否在一个 git 工作树内。

func MergeBranch

func MergeBranch(repoPath, branch, message string) (string, error)

MergeBranch 把 branch 合并进 repoPath 的当前 HEAD,用 message 作为合并提交信息, 返回 git 合并输出(含变更统计)。--no-ff 强制生成 merge commit(即使可快进), 使指定的 message 生效并保留分支历史。

失败(冲突或其它原因)时自动 git merge --abort 回滚主仓库到合并前,保证主仓库始终干净: 冲突返回 *MergeConflictError(含冲突文件);非冲突失败返回原始 git 错误。

func MergeBranchInto

func MergeBranchInto(repoPath, branch, target, message string) (string, error)

MergeBranchInto 把 branch 合并进本地分支 target(用 message 作 merge commit 信息)。 target = 该 session 的基线分支(从哪 checkout 就合回哪,对称)。 先用 worktree list --porcelain 定位 target 当前 checkout 在哪:

  • 主仓库(repoPath)在 target 且干净 → 直接在主仓库 merge(现有语义)。
  • 主仓库在 target 但脏 → 报错(脏工作区 merge 必爆)。
  • target 空闲(主仓库在别的分支,且 target 未在别处被检出)→ 建 target 的临时 worktree,在其中 merge 后删除;主仓库不动。
  • target 在主仓库之外被检出 → 报错。

临时 worktree 路径必 defer 删除(无论成功/冲突/失败),保证不留垃圾(todo §6.2)。

func PreflightMerge

func PreflightMerge(repoPath, base, branch string) (conflicts []string, ok bool, err error)

PreflightMerge 用 git merge-tree --write-tree 预演「branch 合并进 base」,不碰工作区/index。 git ≥ 2.38 支持。返回:

  • conflicts 非空 + ok=true:有冲突(已去重),调用方应直接报错不发起合并。
  • nil + ok=true:无冲突,可安全合并。
  • ok=false:git 不支持 --write-tree(<2.38),调用方走原「合并+abort」兜底路径。
  • err!=nil:预演本身失败(非冲突),透传。

func RefExists

func RefExists(repoPath, ref string) bool

RefExists 报告 ref 是否解析到一个 commit,尝试常见命名空间(heads/remotes/原样)。 接受短名(main)、远程跟踪名(origin/main)或完整 ref(refs/heads/main)。 供「记住上次选择」验证分支仍存在(分支可能被删后 setting 残留)。

func Remove

func Remove(repoPath, targetPath, branch string) error

Remove 删除 linked worktree targetPath 与其分支 branch。owner-only 的原子操作。

四道护栏(defense in depth —— 绝不删主工作树 / 客户真实代码):

  1. targetPath 归一化后 ≠ 主工作树(repoPath);
  2. branch 必须以 md/ 开头(只删 app 自建会话分支;main / develop / feature 等真实分支一律拒);
  3. targetPath 必须仍是 git 登记中的 linked worktree(已 prune / 已被手动删 → 拒,避免误伤);
  4. git 自身拒删主工作树(兜底)。

任一护栏不满足 → 返回 error,worktree 与 branch 都不动(宁可留孤儿 md/ 分支,也不冒险删错)。

func ResolveAddBaseRef

func ResolveAddBaseRef(repoPath, baseRef string) string

ResolveAddBaseRef 把用户选的 baseRef 消歧成 git 能安全传给 worktree add 的 ref, 避免短名(如 main)被 git 解析成同名 tag。

  • 以 refs/ 开头 → 原样用(已是完整 ref)。
  • 含 / (如 origin/main)→ 先试 refs/remotes/<base>,再 refs/heads/<base>。
  • 纯名(如 main / develop)→ 只试 refs/heads/<base>。

都不命中 → 回退原串(让 git 自己报错,透传 git 的诊断信息)。

func ResolveDefaultBaseRef

func ResolveDefaultBaseRef(repoPath string) (string, error)

ResolveDefaultBaseRef 探测仓库的默认基线分支(返回本地分支短名,如 main)。 顺序(todo §3,本地优先):

  1. git symbolic-ref refs/remotes/origin/HEAD → 得默认名(如 main)→ 本地 refs/heads/<name> 存在 → 返回。
  2. 本地优先 probe list:refs/heads/main → master → refs/remotes/origin/main → origin/master,第一个存在的返回短名。
  3. 全空 → ErrNoBaseRef(不回退 HEAD)。

v1 写死 origin(绝大多数项目;fork/多 remote 让用户手选,文档标注限制)。

func ResolveWorktreeBranch

func ResolveWorktreeBranch(repoPath, target string) (branch string, ok bool, err error)

ResolveWorktreeBranch reports whether target is a current linked worktree of repoPath (non-main); if so returns its checked-out branch short name (empty for detached HEAD). CreateGuestSession uses it to validate the entered path AND resolve its branch from git truth (the branch is not trusted from the caller — single source).

func Stage

func Stage(worktreePath string, paths ...string) error

Stage 把 paths 加入暂存区。paths 为空表示暂存全部(git add -A)。

func UncommittedStat

func UncommittedStat(worktreePath string) (string, error)

UncommittedStat 返回 worktreePath 里未提交的改动摘要(staged + unstaged + untracked)。 agent 改了文件但没 commit 时,DiffStat(已提交差异)看不到——这里补上。

func Unstage

func Unstage(worktreePath string, paths ...string) error

Unstage 把 paths 移出暂存区(git restore --staged)。paths 为空表示移出全部。

Types

type BranchInfo

type BranchInfo struct {
	Name string `json:"name"` // 短名(如 main / origin/main)
	Kind string `json:"kind"` // "local" | "remote"
	Date int64  `json:"date"` // committerdate unix 秒(供排序 + 前端按当前时区格式化:同年省年、带时分秒)
}

BranchInfo 一条分支的信息(供选择器列表)。

func ListBranches

func ListBranches(repoPath string) ([]BranchInfo, error)

ListBranches 列出仓库的本地 + 远程跟踪分支,排除 */HEAD 伪 ref, 按 committerdate 倒序封顶 200 条(供选择器一次性拉取 + 前端过滤,KISS)。

type DefaultBaseRef

type DefaultBaseRef struct {
	BaseRef string `json:"baseRef"`
	Ok      bool   `json:"ok"`
}

DefaultBaseRef 默认基线探测结果(BaseRef=短名,Ok=是否探测到)。供前端预选 + 星标。

type FileChange

type FileChange struct {
	Path   string `json:"path"`
	Status string `json:"status"` // M=修改 A=新增 D=删除 U=未跟踪 R=重命名
	// Staged=true 表示已进暂存区(index 有改动);false 表示工作区改动。
	// 一个文件可能同时出现在两组(如 MM:已暂存后又有新改动),参考 VS Code 的 Changes / Staged Changes 两组。
	Staged bool `json:"staged"`
}

FileChange 一个文件的变更状态(VS Code 风格)。

func StatusFiles

func StatusFiles(worktreePath string) ([]FileChange, error)

StatusFiles 返回 worktreePath 里的文件级变更(VS Code 风格:暂存 / 工作区两组)。 解析 git status --porcelain 的 XY 两列:X=index(暂存),Y=worktree(工作区)。 一个文件若同时被暂存又有工作区改动(如 MM),会返回两条:一条 Staged=true、一条 Staged=false。

type MergeConflictError

type MergeConflictError struct {
	Files []string
}

MergeConflictError 表示合并因冲突失败。Files 为冲突文件路径(相对仓库根)。 MergeBranch 在冲突时会自动 git merge --abort,把主仓库回滚到合并前——主仓库是项目 所有 session 的共享根,绝不能卡在半合并状态(否则后续 worktree 创建 / diff / 同项目 其它 session 合并全部受影响,且应用内无冲突解决 UI,只能靠终端救场)。

func (*MergeConflictError) Error

func (e *MergeConflictError) Error() string

type WorktreeInfo

type WorktreeInfo struct {
	Path   string `json:"path"`   // 工作目录绝对路径
	Branch string `json:"branch"` // 检出的分支短名(如 main / md/abc12345 / feat/x);detached HEAD 时为空
	IsMain bool   `json:"isMain"` // 是否主工作树(= 项目目录;true = 永不可删,Remove 护栏)
	Date   int64  `json:"date"`   // 该 worktree HEAD 的 committerdate(unix 秒);前端取「最近 N 个」快捷项用
}

WorktreeInfo 一条 worktree 信息(供 NewSessionModal「使用已有工作目录」选择器)。

func ListWorktrees

func ListWorktrees(repoPath string) ([]WorktreeInfo, error)

ListWorktrees 列出仓库全部 worktree(主 + linked),主工作树(IsMain=true)排第一。 Date = 各 worktree HEAD 的 committerdate(一条批量 git log --no-walk 取齐,仅 1 次调用), 供前端「最近 worktree」快捷项。detached 的 Branch 留空。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL