worktree

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package worktree manages Git worktrees and Jujutsu workspaces for XenForo development environments.

Index

Constants

View Source
const ReservationTimeout = time.Hour

ReservationTimeout is how long a pending reservation survives pruning without its worktree appearing. Creating the checkout takes seconds, so a reservation this old belongs to a creation that was interrupted.

Variables

View Source
var (
	// ErrInvalidBranch indicates a branch name that cannot be used.
	ErrInvalidBranch = errors.New("invalid branch name")

	// ErrBranchExists indicates the branch is already present.
	ErrBranchExists = errors.New("branch already exists")

	// ErrWorktreeExists indicates the target directory is already in use.
	ErrWorktreeExists = errors.New("worktree already exists")

	// ErrWorktreeNotFound indicates no worktree matches a branch or name.
	ErrWorktreeNotFound = errors.New("worktree not found")

	// ErrNotXenForo indicates the source is not a XenForo installation.
	ErrNotXenForo = errors.New("not a XenForo directory")
)
View Source
var (
	// ErrDirtyWorktree indicates uncommitted changes would be lost.
	ErrDirtyWorktree = errors.New("worktree has uncommitted changes")

	// ErrUnmergedCommits indicates commits exist only in this worktree.
	ErrUnmergedCommits = errors.New("worktree has commits not present on any remote")
)
View Source
var ErrNameReserved = errors.New("worktree name is already reserved")

ErrNameReserved indicates another entry already holds a worktree path or instance name.

View Source
var ErrNotADirectory = errors.New("not a directory")

ErrNotADirectory indicates a copy source exists but is not a directory.

View Source
var ErrNotARepository = errors.New("not a git or Jujutsu repository")

ErrNotARepository indicates a path is not inside a supported repository.

View Source
var ErrRegistryCorrupt = errors.New("worktree registry is corrupt")

ErrRegistryCorrupt indicates the registry file exists but cannot be parsed.

Mutating calls tolerate this and rebuild from an empty registry, so a damaged file never blocks cleanup. Read failures are not tolerated: they mean the existing entries are unknown rather than absent.

Functions

func BaseName added in v0.2.2

func BaseName(branch string) string

BaseName converts a branch name into the preferred name for its worktree.

Only the last segment is used, so dev/xfs/slack-unfurl becomes slack-unfurl. The prefix in a conventional branch name describes where the work belongs rather than what it is, and repeating it in directory names, URLs and Docker instance names makes all three harder to read.

The result is lowercase letters, digits and single dashes, so it is safe as a path segment, a Compose project name and a hostname label at once. It can never contain a separator or resolve to a parent directory, whatever the branch name contains. An empty result means the branch yields no usable name.

This is deliberately lossy: dev/xfs/slack-unfurl and dev/xf/slack-unfurl both yield slack-unfurl. ChooseName resolves that by numbering.

func CheckRemovable

func CheckRemovable(ctx context.Context, worktreePath string) error

CheckRemovable reports whether a worktree can be removed without losing work.

It is separate from Remove so callers can run the check before destroying anything the removal depends on. Tearing down containers and volumes first and only then discovering that the worktree is dirty would refuse the removal after the data it was protecting had already been deleted.

func ChooseName added in v0.2.2

func ChooseName(sourcePath, branch string, taken func(name string) (bool, error)) (string, error)

ChooseName picks the name for a new worktree of branch.

The name is BaseName(branch), numbered -2, -3 and so on when that is taken. A name is taken when the checkout's worktrees directory already holds it or when taken reports it in use, which lets the caller check state this package does not own, such as Docker Compose projects. taken may be nil.

The result depends on what exists at the time, so it cannot be recomputed from the branch later. It does not need to be: the name is recorded in the worktree's environment and the registry, and Locate finds a worktree from its branch through the VCS.

func CopyTree

func CopyTree(ctx context.Context, src, dst string, progress ProgressFunc) error

CopyTree recursively copies src to dst, preserving file modes.

A missing source is not an error: a XenForo installation may legitimately have no data/ or internal_data/ yet.

This is implemented natively rather than by shelling out to rsync. macOS no longer ships GNU rsync — /usr/bin/rsync is openrsync, which lacks the progress options — and Windows has no rsync at all, so an external tool would behave differently depending on the machine.

func CurrentBranch

func CurrentBranch(ctx context.Context, repoDir string) (string, error)

CurrentBranch returns the branch checked out in repoDir.

For a Jujutsu repository this returns the workspace name.

func Locate added in v0.2.2

func Locate(ctx context.Context, sourcePath, ref string) (string, error)

Locate finds an existing worktree of the checkout at sourcePath.

ref may be the worktree's branch (or Jujutsu workspace) or its name, the directory it lives in. A branch match wins, so a branch that happens to be named like another worktree's directory still resolves to its own worktree. Only checkouts inside the worktrees directory are considered: the source checkout itself is never a match. Neither is a checkout whose directory was deleted without telling the VCS, which Git still lists as prunable.

The path is returned under WorktreesDir(sourcePath), the form Create reports and the registry records, rather than as the VCS spells it, which may have symlinks resolved.

func RegistryPath

func RegistryPath() (string, error)

RegistryPath returns where the registry is stored, so callers can name the file when telling the user how to deal with a damaged one.

func Remove

func Remove(ctx context.Context, sourcePath, worktreePath string, force bool) error

Remove deletes a worktree and its branch.

Unless force is set, it refuses when the worktree holds uncommitted changes or commits that exist nowhere else, listing what would be lost. Removing containers and volumes is the caller's responsibility.

func SourceCheckout

func SourceCheckout(ctx context.Context, dir string) (string, error)

SourceCheckout returns the main checkout for the repository containing dir.

When dir is inside a linked worktree or workspace this returns the *original* checkout, not the linked one. That keeps new checkouts siblings of the source rather than nesting them, so running the command from within one behaves the same as running it from the source.

func WorktreesDir

func WorktreesDir(sourcePath string) string

WorktreesDir returns the directory holding the worktrees for a checkout.

Worktrees are siblings of the source checkout, so ~/Sites/main yields ~/Sites/main.worktrees. This keeps them on the same filesystem as the source, which matters for Docker bind mounts, and makes them discoverable without knowing an xf-specific convention.

Types

type Entry

type Entry struct {
	// SourcePath is the checkout the worktree was created from.
	SourcePath string `json:"source_path"`

	// SourceBranch is the branch the source was on at creation time.
	SourceBranch string `json:"source_branch"`

	// WorktreePath is the resolved location of the worktree.
	WorktreePath string `json:"worktree_path"`

	// Branch is the branch checked out in the worktree.
	Branch string `json:"branch"`

	// Instance is the Docker instance name for the worktree.
	Instance string `json:"instance"`

	// Cloned records whether the environment was cloned from the source.
	Cloned bool `json:"cloned"`

	// CreatedAt is when the worktree was created.
	CreatedAt time.Time `json:"created_at"`

	// Pending marks a reservation for a worktree that is still being created.
	// Add clears it by replacing the entry once the worktree exists.
	Pending bool `json:"pending,omitempty"`
}

Entry records a worktree created by xf.

type Options

type Options struct {
	// SourcePath is the checkout to branch from.
	SourcePath string

	// Branch is the branch (Git) or workspace (Jujutsu) to create in the new
	// checkout.
	Branch string

	// Name names the new directory. Defaults to ChooseName's choice for
	// Branch.
	Name string

	// Base is the revision to base the new checkout on, interpreted with the
	// selected backend's revision syntax. Defaults to the source's current HEAD.
	Base string

	// Instance overrides the Docker instance name, which defaults to Name.
	Instance string
}

Options describes a worktree to create.

type ProgressFunc

type ProgressFunc func(copied, total int)

ProgressFunc reports copy progress as files are written.

type Registry

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

Registry is the on-disk record of worktrees xf has created.

It exists so that worktrees can be listed across projects, which git alone cannot do. It is deliberately *not* the source of truth: git and Docker are. Worktrees can be removed behind xf's back, so callers must reconcile entries against reality rather than trusting the file.

A missing registry reads as empty, and the operations that rewrite it -- Add and Remove -- recover from a damaged one by replacing it, so creating and removing worktrees never fail on registry damage. Reading is the exception: All reports a corrupt file rather than silently presenting an empty list, because "no worktrees" and "the record is unreadable" call for different responses from the user. Listing and pruning therefore surface the error and say what to do about it.

func NewRegistry

func NewRegistry() (*Registry, error)

NewRegistry opens the registry in the user's configuration directory.

func (*Registry) Add

func (r *Registry) Add(entry Entry) error

Add records a worktree, replacing any existing entry for the same path.

func (*Registry) All

func (r *Registry) All() ([]Entry, error)

All returns every recorded entry.

A missing registry returns no entries and no error.

func (*Registry) ForSource

func (r *Registry) ForSource(sourcePath string) ([]Entry, error)

ForSource returns the entries belonging to a single checkout.

func (*Registry) Prune added in v0.2.2

func (r *Registry) Prune(now time.Time) (int, error)

Prune drops entries whose worktree directory no longer exists and returns how many were dropped.

A pending reservation has no directory yet by design, so it is kept until ReservationTimeout has passed. The check runs under the registry lock, so a reservation made while pruning is either seen as pending or not seen at all, never dropped as stale.

func (*Registry) Remove

func (r *Registry) Remove(worktreePath string) error

Remove drops the entry for a worktree path. Removing an absent entry is not an error, so cleanup is idempotent.

func (*Registry) Reserve added in v0.2.2

func (r *Registry) Reserve(entry Entry) error

Reserve records entry before its worktree exists, unless another entry already holds its path or instance name.

The check and the write happen under the registry lock, so two concurrent creations cannot both claim a name: the second sees the first's entry and gets ErrNameReserved. The caller replaces the entry with Add once the worktree exists, or drops it with Remove if creation fails.

Unlike Add, a corrupt registry is an error here. Its entries are what keep names unique, so an unreadable one cannot be treated as empty.

type Result

type Result struct {
	// Path is the worktree location.
	Path string

	// Branch is the branch checked out in the worktree.
	Branch string

	// SourcePath is the checkout it was created from.
	SourcePath string

	// SourceBranch is the branch the source was on at creation time.
	SourceBranch string

	// Instance is the Docker instance name for the worktree.
	Instance string

	// CreatedAt is when the worktree was created.
	CreatedAt time.Time
}

Result describes a created worktree.

func Create

func Create(ctx context.Context, opts Options) (*Result, error)

Create makes a worktree on a new branch.

It does not configure Docker or install anything; that is the caller's job. Pre-flight runs first, so a failure here leaves the source checkout untouched.

type WorktreeStatus

type WorktreeStatus struct {
	// Modified lists paths with uncommitted changes, including untracked files.
	Modified []string

	// UnmergedCommits lists commits not reachable from any remote branch.
	UnmergedCommits []string
}

WorktreeStatus describes the state of a worktree's working tree and branch.

Jump to

Keyboard shortcuts

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