Documentation
¶
Overview ¶
Package worktree 管理 git worktree:为每个 session 创建独立工作树 + 分支, 实现并行隔离(参考 orca 的 parallel worktree 模型)。 项目 = 主 repo;session = 主 repo 的一个 worktree(独立分支 + 独立工作目录)。 opencode 仍走 ACP,只是 cwd 指向 worktree(不违反 §1.1 纯 ACP)。
Index ¶
- Constants
- Variables
- func BranchExists(repoPath, branch string) bool
- func BranchLog(repoPath, branch, base string) (string, error)
- func Commit(worktreePath, message string) error
- func Create(repoPath, branch, targetPath, baseRef string) error
- func DiffStat(repoPath, branch, base string) (string, error)
- func Discard(worktreePath string, paths ...string) error
- func FileDiff(worktreePath, path string, staged bool) (string, error)
- func FindSubRepo(root string) string
- func HasChanges(worktreePath string) bool
- func HeadShort(repoPath string) (string, error)
- func IsRepo(path string) bool
- func MergeBranch(repoPath, branch, message string) (string, error)
- func MergeBranchInto(repoPath, branch, target, message string) (string, error)
- func PreflightMerge(repoPath, base, branch string) (conflicts []string, ok bool, err error)
- func RefExists(repoPath, ref string) bool
- func Remove(repoPath, targetPath, branch string) error
- func ResolveAddBaseRef(repoPath, baseRef string) string
- func ResolveDefaultBaseRef(repoPath string) (string, error)
- func ResolveWorktreeBranch(repoPath, target string) (branch string, ok bool, err error)
- func Stage(worktreePath string, paths ...string) error
- func UncommittedStat(worktreePath string) (string, error)
- func Unstage(worktreePath string, paths ...string) error
- type BranchInfo
- type DefaultBaseRef
- type FileChange
- type MergeConflictError
- type WorktreeInfo
Constants ¶
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 ¶
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)。
var ErrNotARepo = errors.New("not a git repository")
ErrNotARepo 路径不是 git 仓库。
Functions ¶
func BranchExists ¶
BranchExists 报告 branch 是否存在于 repoPath。
func BranchLog ¶
BranchLog 返回 branch 相对 base 的 commit 列表(一行一条),供"这个分支干了什么"展示。 base 为空则用主仓库 HEAD(旧行为)。有显式基线的 session 应传 se.BaseRef。
func Commit ¶
Commit 提交已暂存的改动(只 commit index,不自动 add;区别于 AutoCommit)。 无暂存改动时返回 git 的 "nothing to commit" 错误。
func Create ¶
Create 在 repoPath 的 baseRef 基础上,新建分支 branch 并检出工作树到 targetPath。 baseRef 为空则用 HEAD。targetPath 不能已存在。 --no-track:避免新建分支自动配置 upstream 跟踪,首次 push 前 git status 误报 "behind by N"(§1.4)。
func DiffStat ¶
DiffStat 返回 branch 相对 base 的变更摘要(git diff --stat)。 base 为空则用主仓库 HEAD(旧行为:主仓库在基线分支时碰巧等价)。 有显式基线的 session 应传 se.BaseRef,避免主仓库 HEAD 飘走后增量算错(todo §13 review 补漏)。 格式如 "3 files changed, 15 insertions(+), 5 deletions(-)"。无变更返回空串。
func Discard ¶
Discard 丢弃工作区改动:已跟踪文件 checkout 还原,未跟踪文件 clean 删除。 只应用于工作区(Staged=false)的文件;暂存区改动用 Unstage。路径为空无操作。
func FileDiff ¶
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 ¶
FindSubRepo 在 root 下(限深 + 剪枝)搜索第一个本身是 git 仓库的子目录,返回其绝对路径; 没找到(root 无 git 子仓库)返回 ""。root 自身不是候选(调用方应先用 IsRepo(root))。
搜索是 best-effort:浅层(默认 2 级)+ 跳过依赖 / 构建目录(那些常含 vendored .git,假阳性)。 每个候选先用 os.Stat 探 .git(快),再用 IsRepo 确认是有效工作树,避免坏 .git / 子模块 gitdir 指针失效等边界误报。命中即返回(ReadDir 已按名字排序,结果稳定可复现)。
func HasChanges ¶
HasChanges 报告 worktreePath 是否有未提交的改动(含 untracked)。
func MergeBranch ¶
MergeBranch 把 branch 合并进 repoPath 的当前 HEAD,用 message 作为合并提交信息, 返回 git 合并输出(含变更统计)。--no-ff 强制生成 merge commit(即使可快进), 使指定的 message 生效并保留分支历史。
失败(冲突或其它原因)时自动 git merge --abort 回滚主仓库到合并前,保证主仓库始终干净: 冲突返回 *MergeConflictError(含冲突文件);非冲突失败返回原始 git 错误。
func MergeBranchInto ¶
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 ¶
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 ¶
RefExists 报告 ref 是否解析到一个 commit,尝试常见命名空间(heads/remotes/原样)。 接受短名(main)、远程跟踪名(origin/main)或完整 ref(refs/heads/main)。 供「记住上次选择」验证分支仍存在(分支可能被删后 setting 残留)。
func Remove ¶
Remove 删除 linked worktree targetPath 与其分支 branch。owner-only 的原子操作。
四道护栏(defense in depth —— 绝不删主工作树 / 客户真实代码):
- targetPath 归一化后 ≠ 主工作树(repoPath);
- branch 必须以 md/ 开头(只删 app 自建会话分支;main / develop / feature 等真实分支一律拒);
- targetPath 必须仍是 git 登记中的 linked worktree(已 prune / 已被手动删 → 拒,避免误伤);
- git 自身拒删主工作树(兜底)。
任一护栏不满足 → 返回 error,worktree 与 branch 都不动(宁可留孤儿 md/ 分支,也不冒险删错)。
func ResolveAddBaseRef ¶
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 ¶
ResolveDefaultBaseRef 探测仓库的默认基线分支(返回本地分支短名,如 main)。 顺序(todo §3,本地优先):
- git symbolic-ref refs/remotes/origin/HEAD → 得默认名(如 main)→ 本地 refs/heads/<name> 存在 → 返回。
- 本地优先 probe list:refs/heads/main → master → refs/remotes/origin/main → origin/master,第一个存在的返回短名。
- 全空 → ErrNoBaseRef(不回退 HEAD)。
v1 写死 origin(绝大多数项目;fork/多 remote 让用户手选,文档标注限制)。
func ResolveWorktreeBranch ¶
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 UncommittedStat ¶
UncommittedStat 返回 worktreePath 里未提交的改动摘要(staged + unstaged + untracked)。 agent 改了文件但没 commit 时,DiffStat(已提交差异)看不到——这里补上。
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 ¶
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 留空。