Documentation
¶
Overview ¶
Package worktree manages Git worktrees and Jujutsu workspaces for XenForo development environments.
Index ¶
- Constants
- Variables
- func BaseName(branch string) string
- func CheckRemovable(ctx context.Context, worktreePath string) error
- func ChooseName(sourcePath, branch string, taken func(name string) (bool, error)) (string, error)
- func CopyTree(ctx context.Context, src, dst string, progress ProgressFunc) error
- func CurrentBranch(ctx context.Context, repoDir string) (string, error)
- func Locate(ctx context.Context, sourcePath, ref string) (string, error)
- func RegistryPath() (string, error)
- func Remove(ctx context.Context, sourcePath, worktreePath string, force bool) error
- func SourceCheckout(ctx context.Context, dir string) (string, error)
- func WorktreesDir(sourcePath string) string
- type Entry
- type Options
- type ProgressFunc
- type Registry
- func (r *Registry) Add(entry Entry) error
- func (r *Registry) All() ([]Entry, error)
- func (r *Registry) ForSource(sourcePath string) ([]Entry, error)
- func (r *Registry) Prune(now time.Time) (int, error)
- func (r *Registry) Remove(worktreePath string) error
- func (r *Registry) Reserve(entry Entry) error
- type Result
- type WorktreeStatus
Constants ¶
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 ¶
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") )
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") )
var ErrNameReserved = errors.New("worktree name is already reserved")
ErrNameReserved indicates another entry already holds a worktree path or instance name.
var ErrNotADirectory = errors.New("not a directory")
ErrNotADirectory indicates a copy source exists but is not a directory.
var ErrNotARepository = errors.New("not a git or Jujutsu repository")
ErrNotARepository indicates a path is not inside a supported repository.
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
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 ¶
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
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 ¶
CurrentBranch returns the branch checked out in repoDir.
For a Jujutsu repository this returns the workspace name.
func Locate ¶ added in v0.2.2
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
NewRegistry opens the registry in the user's configuration directory.
func (*Registry) All ¶
All returns every recorded entry.
A missing registry returns no entries and no error.
func (*Registry) Prune ¶ added in v0.2.2
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 ¶
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
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.
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.