Documentation
¶
Overview ¶
Package config handles loading and validation of wt configuration.
Configuration is read from ~/.wt/config.toml with environment variable overrides for directory settings.
Configuration Sources (highest priority first) ¶
- Config file settings
- Default values
Key Settings ¶
- checkout.worktree_format: Template for worktree folder names (default: "{repo}-{branch}")
- checkout.base_ref: "local" or "remote" for new branch base (default: "remote")
- checkout.auto_fetch: Fetch from origin before checkout (default: false)
- default_sort: Default sort order for "wt list"
Hooks Configuration ¶
Hooks are defined in [hooks.NAME] sections:
[hooks.vscode]
command = "code {worktree-dir}"
description = "Open VS Code"
on = ["checkout"] # auto-run for checkout command
Hooks with "on" run automatically for matching commands (checkout, pr, prune, merge, all). Hooks without "on" only run via explicit --hook=name flag.
Forge Configuration ¶
The [forge] section configures default forge and pattern-based rules:
[forge] default = "github" [[forge.rules]] pattern = "company/*" type = "gitlab"
The [hosts] section maps custom domains to forge types for self-hosted instances.
Path Validation ¶
Directory paths must be absolute or start with ~ (no relative paths like "." or "..") to avoid confusion about the working directory.
Index ¶
- Constants
- Variables
- func DefaultConfig() string
- func DefaultLocalConfig() string
- func ValidateCloneMode(mode string) error
- func WithConfig(ctx context.Context, cfg *Config) context.Context
- func WithResolver(ctx context.Context, r *ConfigResolver) context.Context
- func WithWorkDir(ctx context.Context, dir string) context.Context
- func WorkDirFromContext(ctx context.Context) string
- type CheckoutConfig
- type CloneConfig
- type Config
- type ConfigResolver
- type ForgeConfig
- type ForgeRule
- type Hook
- type HooksConfig
- type ListConfig
- type LocalCheckout
- type LocalClone
- type LocalConfig
- type LocalForge
- type LocalMerge
- type LocalPrune
- type MergeConfig
- type PreserveConfig
- type PruneConfig
- type ThemeConfig
Constants ¶
const DefaultWorktreeFormat = "{repo}-{branch}"
DefaultWorktreeFormat is the default format for worktree folder names
const LocalConfigFileName = ".wt.toml"
LocalConfigFileName is the name of the per-repo local config file
Variables ¶
var ( ValidForgeTypes = []string{"github", "gitlab"} ValidMergeStrategies = []string{"squash", "rebase", "merge"} ValidBaseRefs = []string{"local", "remote"} ValidDefaultSortModes = []string{"date", "repo", "branch"} ValidCloneModes = []string{"bare", "regular"} )
Valid enum values for configuration fields.
var ValidThemeModes = []string{"auto", "light", "dark"}
ValidThemeModes is the list of supported theme modes
var ValidThemeNames = []string{"none", "default", "dracula", "nord", "gruvbox", "catppuccin"}
ValidThemeNames is the list of supported theme presets (families)
Functions ¶
func DefaultConfig ¶ added in v0.4.0
func DefaultConfig() string
DefaultConfig returns the default configuration content.
func DefaultLocalConfig ¶ added in v0.20.0
func DefaultLocalConfig() string
DefaultLocalConfig returns the default local configuration template content.
func ValidateCloneMode ¶ added in v0.22.0
ValidateCloneMode validates a clone mode value against ValidCloneModes. Exported for use in CLI flag validation.
func WithConfig ¶ added in v0.14.0
WithConfig returns a new context with the config stored in it.
func WithResolver ¶ added in v0.20.0
func WithResolver(ctx context.Context, r *ConfigResolver) context.Context
WithResolver returns a new context with the ConfigResolver stored in it.
func WithWorkDir ¶ added in v0.14.0
WithWorkDir returns a new context with the working directory stored in it.
func WorkDirFromContext ¶ added in v0.14.0
WorkDirFromContext returns the working directory from context. Falls back to os.Getwd() if not stored or empty.
Types ¶
type CheckoutConfig ¶ added in v0.13.0
type CheckoutConfig struct {
WorktreeFormat string `toml:"worktree_format"` // Template for worktree folder names
BaseRef string `toml:"base_ref"` // "local" or "remote" (default: "remote")
AutoFetch bool `toml:"auto_fetch"` // Fetch from origin before checkout
SetUpstream *bool `toml:"set_upstream"` // Auto-set upstream tracking (default: true)
}
CheckoutConfig holds checkout-related configuration
func (*CheckoutConfig) ShouldSetUpstream ¶ added in v0.14.0
func (c *CheckoutConfig) ShouldSetUpstream() bool
ShouldSetUpstream returns true if upstream tracking should be set (default: false)
type CloneConfig ¶
type CloneConfig struct {
Mode string `toml:"mode"` // "bare" or "regular" (default: "bare")
}
CloneConfig holds clone-related configuration
func (*CloneConfig) IsBare ¶ added in v0.22.0
func (c *CloneConfig) IsBare() bool
IsBare returns true if the clone mode is bare (the default).
func (*CloneConfig) ResolveIsBare ¶ added in v0.22.0
func (c *CloneConfig) ResolveIsBare(cliOverride string) (bool, error)
ResolveIsBare resolves the effective clone mode from a CLI flag override and returns whether bare mode should be used. The CLI flag takes precedence over the config value. Returns an error if the resolved mode is invalid.
type Config ¶
type Config struct {
RegistryPath string `toml:"-"` // Override ~/.wt/repos.json path (for testing)
HistoryPath string `toml:"-"` // Override ~/.wt/history.json path (for testing)
DefaultSort string `toml:"default_sort"` // "date", "repo", "branch" (default: "date")
DefaultLabels []string `toml:"default_labels"` // labels for newly registered repos
Hooks HooksConfig `toml:"-"` // custom parsing needed
Clone CloneConfig `toml:"clone"` // clone settings
Checkout CheckoutConfig `toml:"checkout"` // checkout settings
Forge ForgeConfig `toml:"forge"`
Merge MergeConfig `toml:"merge"`
Prune PruneConfig `toml:"prune"`
List ListConfig `toml:"list"` // list display settings
Preserve PreserveConfig `toml:"preserve"` // file preservation for new worktrees
Hosts map[string]string `toml:"hosts"` // domain -> forge type mapping
Theme ThemeConfig `toml:"theme"` // UI theme/colors for interactive mode
}
Config holds the wt configuration
func FromContext ¶ added in v0.14.0
FromContext returns the config from context. Returns nil if no config is stored.
func Load ¶
Load reads config from ~/.config/wt/config.toml Returns Default() if file doesn't exist (no error) Returns error only if file exists but is invalid Environment variables override config file values: - WT_THEME overrides theme.name - WT_THEME_MODE overrides theme.mode (auto, light, dark)
func MergeLocal ¶ added in v0.20.0
func MergeLocal(global *Config, local *LocalConfig) *Config
MergeLocal merges a local per-repo config into a global config, returning a new Config without mutating the global. Returns global unchanged if local is nil.
func (*Config) GetHistoryPath ¶ added in v0.14.0
GetHistoryPath returns the effective history file path. Returns HistoryPath if set (for testing), otherwise returns default ~/.wt/history.json.
type ConfigResolver ¶ added in v0.20.0
type ConfigResolver struct {
// contains filtered or unexported fields
}
ConfigResolver provides lazy per-repo config resolution with caching. It loads and merges per-repo .wt.toml files with the global config on demand.
func NewResolver ¶ added in v0.20.0
func NewResolver(global *Config) *ConfigResolver
NewResolver creates a new ConfigResolver backed by the given global config.
func ResolverFromContext ¶ added in v0.20.0
func ResolverFromContext(ctx context.Context) *ConfigResolver
ResolverFromContext returns the ConfigResolver from context. Returns nil if no resolver is stored.
func (*ConfigResolver) ConfigForRepo ¶ added in v0.20.0
func (r *ConfigResolver) ConfigForRepo(repoPath string) (*Config, error)
ConfigForRepo returns the effective config for a repo, merging any .wt.toml found at the repo path with the global config. Results are cached per repoPath.
func (*ConfigResolver) Global ¶ added in v0.20.0
func (r *ConfigResolver) Global() *Config
Global returns the global config (without any local overrides).
type ForgeConfig ¶ added in v0.8.0
type ForgeConfig struct {
Default string `toml:"default"` // default forge type
DefaultOrg string `toml:"default_org"` // default org for clone
Rules []ForgeRule `toml:"rules"`
}
ForgeConfig holds forge-related configuration
func (*ForgeConfig) GetForgeTypeForRepo ¶ added in v0.8.0
func (c *ForgeConfig) GetForgeTypeForRepo(repoSpec string) string
GetForgeTypeForRepo returns the forge type for a given repo spec (e.g., "org/repo") Matches against rules in order, returns default if no match
func (*ForgeConfig) GetUserForRepo ¶ added in v0.8.0
func (c *ForgeConfig) GetUserForRepo(repoSpec string) string
GetUserForRepo returns the gh/glab username for a repo spec Matches against rules in order, returns empty string if no match (use active account)
type ForgeRule ¶ added in v0.8.0
type ForgeRule struct {
Pattern string `toml:"pattern"` // glob pattern like "n26/*" or "company/*"
Type string `toml:"type"` // "github" or "gitlab"
User string `toml:"user"` // optional: gh/glab username for auth
}
ForgeRule maps a pattern to forge settings
type Hook ¶
type Hook struct {
Command string `toml:"command"`
Description string `toml:"description"`
On []string `toml:"on"` // commands this hook runs on (empty = only via --hook)
Enabled *bool `toml:"enabled"` // nil = true (default); false disables a global hook locally
}
Hook defines a post-create hook
type HooksConfig ¶
HooksConfig holds hook-related configuration
type ListConfig ¶ added in v0.21.0
type ListConfig struct {
StaleDays int `toml:"stale_days"` // days after which worktrees are highlighted as stale (0 = disabled)
}
ListConfig holds list-related configuration
type LocalCheckout ¶ added in v0.20.0
type LocalCheckout struct {
WorktreeFormat string `toml:"worktree_format"`
BaseRef string `toml:"base_ref"`
AutoFetch *bool `toml:"auto_fetch"`
SetUpstream *bool `toml:"set_upstream"`
}
LocalCheckout holds local checkout overrides
type LocalClone ¶ added in v0.22.0
type LocalClone struct {
Mode string `toml:"mode"`
}
LocalClone holds local clone overrides
type LocalConfig ¶ added in v0.20.0
type LocalConfig struct {
Hooks HooksConfig `toml:"-"` // merge by name into global
Clone LocalClone `toml:"clone"`
Checkout LocalCheckout `toml:"checkout"`
Merge LocalMerge `toml:"merge"`
Prune LocalPrune `toml:"prune"`
Preserve PreserveConfig `toml:"preserve"` // appended to global
Forge LocalForge `toml:"forge"`
}
LocalConfig holds per-repo configuration overrides from .wt.toml. Pointer fields and zero-value strings indicate "not set" (inherit from global).
func LoadLocal ¶ added in v0.20.0
func LoadLocal(repoPath string) (*LocalConfig, error)
LoadLocal reads a per-repo .wt.toml config from the given repo path. Returns nil (no error) if the file doesn't exist. Returns an error only on parse or validation failure.
type LocalForge ¶ added in v0.20.0
type LocalForge struct {
Default string `toml:"default"`
}
LocalForge holds local forge overrides
type LocalMerge ¶ added in v0.20.0
type LocalMerge struct {
Strategy string `toml:"strategy"`
}
LocalMerge holds local merge overrides
type LocalPrune ¶ added in v0.20.0
type LocalPrune struct {
DeleteLocalBranches *bool `toml:"delete_local_branches"`
}
LocalPrune holds local prune overrides
type MergeConfig ¶
type MergeConfig struct {
Strategy string `toml:"strategy"` // "squash", "rebase", or "merge"
}
MergeConfig holds merge-related configuration
type PreserveConfig ¶ added in v0.19.0
type PreserveConfig struct {
Patterns []string `toml:"patterns"` // Glob patterns matched against file basenames
Exclude []string `toml:"exclude"` // Path segments to exclude (e.g., "node_modules")
}
PreserveConfig holds file preservation settings for worktree creation. Matching git-ignored files are copied from an existing worktree into new ones.
type PruneConfig ¶ added in v0.14.0
type PruneConfig struct {
DeleteLocalBranches bool `toml:"delete_local_branches"`
}
PruneConfig holds prune-related configuration
type ThemeConfig ¶ added in v0.13.0
type ThemeConfig struct {
Name string `toml:"name"` // preset name: "none", "default", "dracula", "nord", "gruvbox", "catppuccin"
Mode string `toml:"mode"` // theme mode: "auto", "light", "dark" (default: "auto")
Primary string `toml:"primary"` // main accent color (borders, titles)
Accent string `toml:"accent"` // highlight color (selected items)
Success string `toml:"success"` // success indicators (checkmarks)
Error string `toml:"error"` // error messages
Muted string `toml:"muted"` // disabled/inactive text
Normal string `toml:"normal"` // standard text
Info string `toml:"info"` // informational text
Warning string `toml:"warning"` // warning indicators (stale items)
Nerdfont bool `toml:"nerdfont"` // use nerd font symbols (default: false)
}
ThemeConfig holds theme/color configuration for interactive UI