worktree

Documentation

Index

• type MergeOutcome
• type Worktreer
  • func NewWorktreer(ctx context.Context, instanceID string) *Worktreer
  • func (w *Worktreer) Branch(name string) string
  • func (w *Worktreer) BranchExistsAt(path, branch string) (bool, error)
  • func (w *Worktreer) Create(repo, name, base string) (string, error)
  • func (w *Worktreer) IsCleanAt(path string) (bool, error)
  • func (w *Worktreer) MergeInto(leadPath, branch string) (MergeOutcome, []string, error)
  • func (w *Worktreer) Path(repo, name string) string
  • func (w *Worktreer) PreExisting(repo, name string) bool
  • func (w *Worktreer) Remove(repo, name string, force bool) error

Types

type MergeOutcome

type MergeOutcome int

MergeOutcome classifies a MergeInto result.

const (
	MergeApplied  MergeOutcome = iota // a merge commit was created
	MergeUpToDate                     // nothing to merge — branch already in lead
	MergeConflict                     // conflict — the merge was aborted
)

type Worktreer

type Worktreer struct {
	// contains filtered or unexported fields
}

Worktreer manages git worktrees. It is repo-stateless: the repo root is passed to each method, so one Worktreer serves every project in the workspace. With a non-empty instanceID, worktrees live under <repo>/.herrscher-sessions/<instanceID>/<name> on branch session/<instanceID>/<name>; with an empty instanceID (legacy) under <repo>/.herrscher-sessions/<name> on branch session/<name>, so multiple daemons sharing a repo never collide.

func NewWorktreer

func NewWorktreer(ctx context.Context, instanceID string) *Worktreer

NewWorktreer builds a repo-stateless Worktreer, namespaced by instanceID ("" means legacy, non-namespaced layout).

func (*Worktreer) Branch

func (w *Worktreer) Branch(name string) string

Branch returns the git branch backing a logical session name, namespaced by instanceID when set.

func (*Worktreer) BranchExistsAt

func (w *Worktreer) BranchExistsAt(path, branch string) (bool, error)

BranchExistsAt reports whether branch exists as a local ref, querying the repo that contains path (an existing worktree dir inside that repo). Exit code 1 from "show-ref --verify" means the ref is simply absent — that is the normal "free to use" case, not an error. Any other failure (e.g. path isn't a git repo at all, exit 128) is reported as an error so callers never mistake "couldn't verify" for "free".

func (*Worktreer) Create

func (w *Worktreer) Create(repo, name, base string) (string, error)

Create adds a worktree on branch session/<name> inside repo. When base is non-empty, the new branch starts at that ref (e.g. "session/<A>") so the worktree continues that tip without a merge; empty base keeps the default (branch from HEAD). Returns ("", nil) when repo is not a git repo (caller falls back to a shared session).

func (*Worktreer) IsCleanAt

func (w *Worktreer) IsCleanAt(path string) (bool, error)

IsCleanAt reports whether the worktree at path has no uncommitted changes. An error means the state can't be verified (missing dir, not a git repo) — the caller must treat that as "not safe", never as clean.

func (*Worktreer) MergeInto

func (w *Worktreer) MergeInto(leadPath, branch string) (MergeOutcome, []string, error)

MergeInto runs `git -C leadPath merge --no-edit branch`. On success it reports MergeApplied (a commit was created) or MergeUpToDate (HEAD unchanged). On a conflict it returns MergeConflict plus the conflicted file list and runs `git merge --abort`, so leadPath is left clean either way. Any other git failure is returned as an error (with a best-effort abort first, so a half-started merge never lingers); when err != nil the MergeOutcome is undefined and callers must branch on err first.

func (*Worktreer) Path

func (w *Worktreer) Path(repo, name string) string

Path returns the on-disk worktree directory for a logical session name inside repo, namespaced by instanceID when set.

func (*Worktreer) PreExisting

func (w *Worktreer) PreExisting(repo, name string) bool

PreExisting reports whether a worktree for this session is already on disk, so a caller that rolls back on a later failure removes only what it created. A state it cannot verify counts as pre-existing: the cost of being wrong that way is a worktree left behind, and the cost of being wrong the other way is deleting a session's uncommitted work.

func (*Worktreer) Remove

func (w *Worktreer) Remove(repo, name string, force bool) error

Remove removes the worktree. If it has uncommitted changes and !force, it refuses with the status. The branch session/<name> is always left intact.