config

Documentation

Overview

Package config handles loading and validation of wt configuration.

Configuration is read from ~/.config/wt/config.toml with environment variable overrides for directory settings.

Configuration Sources (highest priority first)

• WT_WORKTREE_DIR env var: Target directory for worktrees
• WT_REPO_DIR env var: Directory to scan for repositories
• Config file settings
• Default values

Key Settings

• worktree_dir: Base directory for new worktrees (must be absolute or ~/...)
• repo_dir: Optional separate directory for repo scanning
• worktree_format: Template for worktree folder names (default: "{repo}-{branch}")
• base_ref: "local" or "remote" for new branch base (default: "remote")
• auto_fetch: Fetch base branch before creating new branches (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). 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
• func DefaultConfig() string
• func DefaultConfigWithDir(worktreeDir string) string
• func DefaultConfigWithDirs(worktreeDir, repoDir string) string
• func Init(worktreeDir, repoDir string, force bool) (string, error)
• func ValidatePath(path, fieldName string) error
• type Config
  • func Default() Config
  • func Load() (Config, error)
  • func (c *Config) GetAbsWorktreeDir() (string, error)
  • func (c *Config) RepoScanDir() string
• type ForgeConfig
  • func (c *ForgeConfig) GetForgeTypeForRepo(repoSpec string) string
  • func (c *ForgeConfig) GetUserForRepo(repoSpec string) string
• type ForgeRule
• type Hook
• type HooksConfig
• type MergeConfig

Constants

const DefaultWorktreeFormat = "{repo}-{branch}"

DefaultWorktreeFormat is the default format for worktree folder names

Functions

func DefaultConfig

func DefaultConfig() string

DefaultConfig returns the default configuration content.

func DefaultConfigWithDir

func DefaultConfigWithDir(worktreeDir string) string

DefaultConfigWithDir returns the default configuration with worktree_dir set.

func DefaultConfigWithDirs

func DefaultConfigWithDirs(worktreeDir, repoDir string) string

DefaultConfigWithDirs returns the default configuration with worktree_dir and optional repo_dir set.

func Init

func Init(worktreeDir, repoDir string, force bool) (string, error)

Init creates a default config file at ~/.config/wt/config.toml If force is true, overwrites existing file Returns the path to the created file

func ValidatePath

func ValidatePath(path, fieldName string) error

ValidatePath checks that the path is absolute or starts with ~ Returns error if path is relative (like "." or "..")

Types

type Config

type Config struct {
	WorktreeDir    string            `toml:"worktree_dir"`
	RepoDir        string            `toml:"repo_dir"` // optional: where to find repos for -r/-l
	WorktreeFormat string            `toml:"worktree_format"`
	BaseRef        string            `toml:"base_ref"`     // "local" or "remote" (default: "remote")
	AutoFetch      bool              `toml:"auto_fetch"`   // fetch before creating new branches (default: false)
	DefaultSort    string            `toml:"default_sort"` // "id", "repo", "branch", "commit" (default: "id")
	Hooks          HooksConfig       `toml:"-"`            // custom parsing needed
	Forge          ForgeConfig       `toml:"forge"`
	Merge          MergeConfig       `toml:"merge"`
	Hosts          map[string]string `toml:"hosts"` // domain -> forge type mapping
}

Config holds the wt configuration

func Default

func Default() Config

Default returns the default configuration

func Load

func Load() (Config, error)

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_WORKTREE_DIR overrides worktree_dir - WT_REPO_DIR overrides repo_dir

func (*Config) GetAbsWorktreeDir

func (c *Config) GetAbsWorktreeDir() (string, error)

GetAbsWorktreeDir returns the absolute worktree directory, defaulting to cwd.

func (*Config) RepoScanDir

func (c *Config) RepoScanDir() string

RepoScanDir returns the directory to scan for repositories. Returns RepoDir if set, otherwise falls back to WorktreeDir.

type ForgeConfig

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

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

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

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)
}

Hook defines a post-create hook

type HooksConfig

type HooksConfig struct {
	Hooks map[string]Hook `toml:"-"` // parsed from [hooks.NAME] sections
}

HooksConfig holds hook-related configuration

type MergeConfig

type MergeConfig struct {
	Strategy string `toml:"strategy"` // "squash", "rebase", or "merge"
}

MergeConfig holds merge-related configuration