worktree

package
v1.3.108-pre-2 Latest Latest
Warning

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

 Go to latest Published: Nov 11, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package worktree owns the git worktree mechanics used by the Runtime: name planning, materialization, listing, removal and reset. It never touches SQL, sessions or the Runtime; git is the only content authority it consults.

Index

Constants

View Source 
const (
	CodeNotGit               = "not_git"
	CodeNameGenerationFailed = "name_generation_failed"
	CodeCreateFailed         = "create_failed"
	CodePopulateFailed       = "populate_failed"
	CodeListFailed           = "list_failed"
	CodeRemoveFailed         = "remove_failed"
	CodeResetFailed          = "reset_failed"
	CodeDefaultBranchFailed  = "default_branch_failed"
	CodeRevisionFailed       = "revision_failed"
	CodeChangeSetFailed      = "change_set_failed"
	CodeApplyFailed          = "apply_failed"
	CodeApplyConflict        = "apply_conflict"
)

Error codes shared with the ACP/CLI projections.

View Source 
const DefaultChangeSetPatchBytes = 512 << 10

DefaultChangeSetPatchBytes bounds the patch retained in one immutable change-set snapshot. A truncated patch is still useful for review, but it is never safe to integrate without the complete snapshot.

View Source 
const DefaultChangeSetUntrackedBytes = 512 << 10

DefaultChangeSetUntrackedBytes bounds the raw content retained for untracked files. Git's patch format already handles tracked binary files.

Variables

This section is empty.

Functions

func RollbackChangeSet 

func RollbackChangeSet(ctx context.Context, root string, changeSet ChangeSet, applied ApplyResult) error

RollbackChangeSet reverses one ApplyChangeSet that already ran against root. It is used when a later selection in the same integration request conflicts: the Runtime must not leave a partially applied multi-selection behind. The function re-verifies created untracked bytes before deleting them and never removes a file whose content changed after integration.

func Slugify 

func Slugify(input string) string

Slugify lowercases input and reduces every run of non-alphanumeric runes to a single dash, trimming leading/trailing dashes.

Types

type ApplyResult 

type ApplyResult struct {
	AppliedFiles     []string
	PatchApplied     bool
	CreatedUntracked []string
}

ApplyResult reports the paths a Runtime-owned integration actually changed.

func ApplyChangeSet 

func ApplyChangeSet(ctx context.Context, root string, changeSet ChangeSet) (ApplyResult, error)

ApplyChangeSet applies one verified change-set snapshot to a repository worktree. It never uses the mutable child worktree: the patch and untracked bytes in the snapshot are the only inputs. The tracked patch is dry-run before mutation; untracked paths are resolved component-by-component with a symlink fence so a snapshot can never redirect a write outside root.

type ChangeFile 

type ChangeFile struct {
	Path         string `json:"path"`
	Status       string `json:"status"`
	OriginalPath string `json:"originalPath,omitempty"`
}

ChangeFile is one tracked path in a change-set snapshot.

type ChangeSet 

type ChangeSet struct {
	Version            int             `json:"version"`
	BaseRevision       string          `json:"baseRevision"`
	HeadRevision       string          `json:"headRevision"`
	Digest             string          `json:"digest"`
	Files              []ChangeFile    `json:"files"`
	UntrackedFiles     []UntrackedFile `json:"untrackedFiles,omitempty"`
	Patch              string          `json:"patch,omitempty"`
	PatchTruncated     bool            `json:"patchTruncated,omitempty"`
	UntrackedTruncated bool            `json:"untrackedTruncated,omitempty"`
}

ChangeSet is an immutable, bounded snapshot of a managed worktree relative to a recorded base revision. It is a review/integration input, not an artifact and never an authorization source.

func (ChangeSet) Verify 

func (c ChangeSet) Verify() error

Verify checks the immutable snapshot's digest and path/content integrity. Callers must also reject a truncated patch or untracked snapshot before applying it; truncation is explicit evidence, not a mergeable change.

type Error 

type Error struct {
	Code    string
	Message string
}

Error is a typed mechanism error carrying a stable machine code so adapters can map it to protocol errors without string matching.

func (*Error) Error 

func (e *Error) Error() string

type Info 

type Info struct {
	Name      string
	Branch    string
	Directory string
}

Info describes one git worktree derived from a repository. An empty Branch means the worktree is detached.

type Manager 

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

Manager owns git worktree mechanics under Root. It is safe for concurrent use as long as callers serialize per repository root (the Runtime does).

func NewManager 

func NewManager(root, branchPrefix string) *Manager

NewManager builds a Manager whose worktrees live under root. An empty branchPrefix falls back to "mothx".

func (*Manager) Add 

func (m *Manager) Add(ctx context.Context, repoRoot string, info Info) error

Add materializes the worktree directory without checking out files. The directory exists after a successful Add, so it can be authorized before the (slower) Populate step runs.

func (*Manager) CaptureChangeSet 

func (m *Manager) CaptureChangeSet(ctx context.Context, directory, baseRevision string, patchLimit int) (ChangeSet, error)

CaptureChangeSet snapshots tracked changes and bounded untracked content for a managed worktree. directory must live under the Manager root; callers must already have proved the directory is a registered worktree.

func (*Manager) DefaultBranch 

func (m *Manager) DefaultBranch(ctx context.Context, repoRoot string) (string, error)

DefaultBranch resolves the repository's default branch ref, preferring origin/HEAD and falling back to main/master.

func (*Manager) DirectoryFor 

func (m *Manager) DirectoryFor(repoRoot, name string) string

DirectoryFor returns the canonical worktree directory for name under the repository's key directory.

func (*Manager) List 

func (m *Manager) List(ctx context.Context, repoRoot string) ([]Info, error)

List returns the repository's worktrees excluding the primary worktree.

func (*Manager) LockDir 

func (m *Manager) LockDir(ctx context.Context, directory string) (func(), error)

LockDir acquires a cross-process lock for one worktree directory under the manager root. The returned release function is always non-nil on success.

func (*Manager) Plan 

func (m *Manager) Plan(ctx context.Context, repoRoot, requested string, detached bool) (Info, error)

Plan generates a unique name/directory/branch for a new worktree. requested is slugified; when empty, the repository basename is used. Conflicts on the directory or branch are retried with a random suffix.

func (*Manager) Populate 

func (m *Manager) Populate(ctx context.Context, info Info) error

Populate checks out the worktree's committed tree.

func (*Manager) Remove 

func (m *Manager) Remove(ctx context.Context, repoRoot, directory, branch string) error

Remove deletes a worktree directory and, when non-empty, its branch. It is the caller's responsibility to prove directory belongs to repoRoot's registered worktrees before calling Remove.

func (*Manager) RepoRoot 

func (m *Manager) RepoRoot(ctx context.Context, dir string) (string, error)

RepoRoot resolves the primary worktree (repository root) for dir.

func (*Manager) Reset 

func (m *Manager) Reset(ctx context.Context, repoRoot, directory string) error

Reset returns a worktree to the repository's default branch, discarding local changes. It fails rather than silently leaving the tree dirty.

func (*Manager) Revision 

func (m *Manager) Revision(ctx context.Context, directory string) (string, error)

Revision resolves the commit checked out by a worktree or repository.

func (*Manager) Root 

func (m *Manager) Root() string

Root returns the directory all managed worktrees live under.

type Runner 

type Runner func(ctx context.Context, cwd string, args ...string) (stdout, stderr string, code int, err error)

Runner executes git in cwd and returns stdout, stderr and the exit code. A non-nil error means the process could not be started at all; a non-zero code with a nil error is a normal git failure.

type UntrackedFile 

type UntrackedFile struct {
	Path             string `json:"path"`
	Size             int64  `json:"size"`
	Digest           string `json:"digest"`
	ContentBase64    string `json:"contentBase64,omitempty"`
	ContentTruncated bool   `json:"contentTruncated,omitempty"`
	Binary           bool   `json:"binary,omitempty"`
}

UntrackedFile carries bounded content for a file git does not track. The content is base64 encoded so arbitrary bytes survive JSON persistence.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.