Debugging

Build with profiling support

TAGS=pprof make clean install

This compiles in src/options_pprof.go (instead of src/options_no_pprof.go) which adds --profile-cpu, --profile-mem, --profile-block, and --profile-mutex flags. Each accepts a path; fzf writes the corresponding pprof file when it exits.

fzf --profile-cpu /tmp/cpu.pprof --profile-mem /tmp/mem.pprof < big-input
go tool pprof /tmp/cpu.pprof

Verbose terminal output

A handful of internal diagnostics can be turned on by editing the DEBUG flag in src/algo/algo.go. When DEBUG = true, the V2 algorithm prints per-character bonuses to stderr, which is useful when tuning scoring tweaks.

Common pitfalls

• Forgetting to refresh embedded shell scripts. shell/common.sh is spliced into shell/key-bindings.{bash,zsh} and shell/completion.{bash,zsh} by shell/update.sh. If you edit common.sh and skip make fmt, the embedded scripts will still contain the old copy and make lint will fail. The same applies if you edit one of the per-shell scripts inside the INCLUDE markers — your change will be overwritten on the next make fmt.
• Out-of-sync action enum. src/actiontype_string.go is generated by go generate. After adding an entry to the actionType constants in src/options.go, run make generate. Forgetting this leaves the binary working but breaks String() output for the new action, which matters in error messages and tests.
• Race on the chunk list during change-with-nth. src/core.go explicitly cancels in-flight matcher scans and pauses the terminal renderer before mutating items in place under change-with-nth (search the withNthChanged block in core.go). New code that mutates items in the chunk list should follow the same pattern.
• Tmux popup needs tmux 3.3+. --tmux calls tmux display-popup -E -d ...; older tmux releases lack -E. If you're testing popup behavior, confirm the tmux version first.
• Walker symlink loops. The readFiles function in src/reader.go has a guard for symlinks that point to a walker root or its ancestor (e.g. WSL Z: → /). If you change the walker, preserve that guard or you'll find users running fzf in a directory that contains such a symlink and traversing the entire host filesystem.

Useful environment variables for repro

• FZF_DEFAULT_COMMAND — overrides the default walker.
• FZF_DEFAULT_OPTS / FZF_DEFAULT_OPTS_FILE — base options applied before per-invocation flags.
• FZF_API_KEY — required for non-localhost --listen.
• TERM — controls the renderer's color and capability assumptions; reproduce a user's bug by matching their TERM.
• LANG / LC_ALL — affect the unicode segmenter (github.com/rivo/uniseg) used for grapheme widths.

Enabling tcell renderer

Some terminal-compatibility issues only reproduce under tcell. Build with:

TAGS=tcell make clean install

Then run with --no-color or --color=bw and compare to the default light renderer. The tcell renderer lives in src/tui/tcell.go and follows the Renderer interface from src/tui/tui.go.