Configuration Reference

Field-by-field lookup for both config files. For explanations and examples, see the Configuration guide.

Global config

Path: $XDG_CONFIG_HOME/workFlow/config.yaml (typically ~/.config/workFlow/config.yaml). All fields optional. Manage with wf config path | show | edit.

Field	Type	Default	Description
clipboard_cmd	string	built-in clipboard	Copy command, run as sh -c <cmd> with the path on stdin
default_base	string	detected default branch	Fallback base branch for new workspaces
worktree_dir	string	sibling <repo>_worktrees	Default base directory for all worktrees
default_ide	string	first detected editor	Fallback editor id for wf edit / wf open when a repo pins none (Editors)
ides	list	none	Custom editors merged into the picker's catalog (id, name, cmd, gui)
status	map	nerdfont defaults	Agent-status icons/colours (preset, color_mode, scope, ttl, glyphs, colors)

# ~/.config/workFlow/config.yaml
clipboard_cmd: "xclip -selection clipboard"
default_base: development
worktree_dir: ~/worktrees
default_ide: code
ides:
  - id: lapce
    name: Lapce
    cmd: lapce
    gui: true
status:
  preset: nerdfont

Per-repo .workFlow.yaml

Path: .workFlow.yaml at the repository root. All fields optional. Generate a documented starter with wf init.

Field	Type	Default	Description
base	string	global/detected default	Default base branch for new workspaces in this repo
default_ide	string	global default_ide	Editor id wf edit prefers for this repo (Editors)
autolaunch	bool	false	Open default_ide without showing the picker
worktree_dir	string	global setting, else sibling dir	Where this repo's worktrees are created (overrides global)
setup	list of strings	none	Commands run via sh -c in each new worktree after creation
copy	list of strings	none	Repo-root-relative files copied into each new worktree
symlink	list of strings	none	Repo-root-relative files symlinked into each new worktree

# .workFlow.yaml
base: development
# default_ide: goland
# autolaunch: true
# worktree_dir: ../myrepo_worktrees
setup:
  - npm install
copy:
  - .env.example
symlink:
  - .env

Base-branch resolution

The base for a new workspace is the first of these that's set (details):

1. wf add --base <branch>
2. .workFlow.yaml → base
3. global config → default_base
4. the repo's detected default (origin/HEAD, else development → main → master)
5. the current branch

State & paths

Path	What
$XDG_CONFIG_HOME/workFlow/config.yaml	Global config
$XDG_CONFIG_HOME/workFlow/registry.json	The registry — registered projects + tracked worktrees (the only persisted state)
<repo>_worktrees/<branch-slug>	Default location of a workspace's worktree (a sibling of the repo)

$XDG_CONFIG_HOME defaults to ~/.config.