doctor

Documentation

Overview

Package doctor provides diagnostic and repair functionality for wt's worktree cache.

The doctor package detects and optionally repairs issues including:

• Cache integrity issues: orphaned keys, stale entries, path mismatches, missing metadata, and duplicate IDs.

• Git link issues: broken bidirectional links between worktrees and their parent repositories, repos that have moved, and stale git references.

• Orphan issues: worktrees on disk not tracked in cache, and ghost entries (cached but git doesn't recognize them).

Usage

Run diagnostics:

err := doctor.Run(cfg, false)  // check only
err := doctor.Run(cfg, true)   // check and fix

Reset cache:

err := doctor.Reset(cfg)  // rebuild from scratch

Issue Categories

Issues are grouped into three categories:

• CategoryCache: Problems with cache data (entries, paths, metadata)
• CategoryGit: Problems with git worktree links
• CategoryOrphan: Untracked worktrees or ghost entries

Each Issue includes a description and suggested fix action.

Index

• func Reset(ctx context.Context, cfg *config.Config) error
• func Run(ctx context.Context, cfg *config.Config, fix bool) error
• type Issue
• type IssueCategory
• type IssueStats

Functions

func Reset

func Reset(ctx context.Context, cfg *config.Config) error

Reset rebuilds the cache from scratch, discarding all existing entries.

func Run

func Run(ctx context.Context, cfg *config.Config, fix bool) error

Run performs diagnostic checks on the worktree cache and optionally fixes issues.

Types

type Issue

type Issue struct {
	Key         string        // cache key or path
	Description string        // human-readable description
	FixAction   string        // what --fix would do
	Category    IssueCategory // issue category
	RepoPath    string        // for git repair operations
}

Issue represents a problem detected by doctor.

type IssueCategory

type IssueCategory string

IssueCategory groups issues by type.

const (
	// CategoryCache represents problems with cache data.
	CategoryCache IssueCategory = "cache"
	// CategoryGit represents problems with git worktree links.
	CategoryGit IssueCategory = "git"
	// CategoryOrphan represents untracked worktrees or ghost entries.
	CategoryOrphan IssueCategory = "orphan"
)

type IssueStats

type IssueStats struct {
	CacheValid      int // valid cache entries
	CacheIssues     int // cache entries with issues
	GitHealthy      int // worktrees with healthy git links
	GitRepairable   int // worktrees with repairable git links
	GitUnrepairable int // worktrees with unrepairable git links
	GitPrunable     int // stale git references that can be pruned
	OrphanUntracked int // worktrees on disk but not in cache
	OrphanGhost     int // entries in cache but not recognized by git
}

IssueStats tracks counts by category.