# How to Implement Custom Fuzzy Completion for Specific Commands in fzf

> Implement custom fuzzy completion for any command in fzf using _fzf_setup_completion. Define custom generators for specialized inputs like Docker or Git.

- Repository: [Junegunn Choi/fzf](https://github.com/junegunn/fzf)
- Tags: how-to-guide
- Published: 2026-03-01

---

**Use the `_fzf_setup_completion` function provided in [`shell/completion.bash`](https://github.com/junegunn/fzf/blob/main/shell/completion.bash) to register fuzzy completion for any custom command, or define custom candidate generators using the `_fzf_compgen_*` naming convention for specialized inputs like Docker containers or Git branches.**

The `junegunn/fzf` repository provides a sophisticated Bash completion system that replaces static tab completion with interactive fuzzy finding. If you want to implement **custom fuzzy completion for specific commands**, you can leverage the public API exposed in [`shell/completion.bash`](https://github.com/junegunn/fzf/blob/main/shell/completion.bash) without modifying the core fzf source code or the Go binary.

## Architecture of fzf's Bash Completion System

The completion system in [`shell/completion.bash`](https://github.com/junegunn/fzf/blob/main/shell/completion.bash) operates through three distinct layers that handle command registration and candidate generation.

### Layer 1: Default Completion Bootstrap

The `__fzf_default_completion` function (lines 41-47) registers a generic fuzzy handler for all commands lacking specific completion definitions. It uses `complete -D -F __fzf_default_completion` to establish the fallback behavior, ensuring that any command can use fuzzy completion when the trigger pattern is detected.

### Layer 2: Command-Specific Registration

For known commands like `git`, `vim`, or `cd`, the `__fzf_defc` helper (lines 82-92) registers concrete completion functions such as `_fzf_path_completion` or `_fzf_dir_completion`. This layer maps specific commands to their appropriate candidate generators using the Bash `complete -F` builtin.

### Layer 3: Public API for Extensions

The `_fzf_setup_completion` function (lines 200-238) serves as the official entry point for custom fuzzy completion. It dispatches to `__fzf_defc` with appropriate options based on the completion type: `path`, `dir`, `var`, `alias`, `host`, or `proc`.

## Using the Public API: _fzf_setup_completion

The `_fzf_setup_completion` function provides the simplest method to add fuzzy completion to your custom commands without modifying fzf's source files.

### Path Completion for Custom Commands

To enable fuzzy file path completion for a command that accepts file arguments, use the `path` type:

```bash

# In ~/.bashrc, after sourcing fzf's completion.bash

_fzf_setup_completion path mycat myedit mytool

```

This registers `_fzf_path_completion` for the specified commands, allowing users to type `mycat **<TAB>` to trigger fuzzy file selection. The function respects the `FZF_COMPLETION_TRIGGER` environment variable (defaulting to `**`).

### Directory-Only Completion

For commands that require directory arguments, use the `dir` type to restrict candidates to directories:

```bash
_fzf_setup_completion dir myproj mycd

```

This invokes `_fzf_dir_completion` (defined around lines 74-76 in [`shell/completion.bash`](https://github.com/junegunn/fzf/blob/main/shell/completion.bash)), which adds the `-o nospace -o dirnames` flags to the `complete` builtin and filters the candidate list to show only directories.

### Variable, Alias, and Host Completion

The API supports additional completion types for specific use cases:

```bash

# Environment variable completion

_fzf_setup_completion var myenv

# Alias completion

_fzf_setup_completion alias myalias

# SSH host completion

_fzf_setup_completion host myssh

# Process completion (for kill-like commands)

_fzf_setup_completion proc mykill

```

Each type maps to a specific completion function that generates appropriate candidates (variables from `env`, hosts from `~/.ssh/known_hosts`, processes from `ps`, etc.).

## Advanced: Custom Candidate Generators

When built-in completion types are insufficient, you can define custom candidate generators using the `_fzf_compgen_*` naming convention.

### Implementing a Custom Generator

Define a function following the pattern `_fzf_compgen_<name>` that outputs candidates one per line:

```bash

# Custom generator for Docker containers

_fzf_compgen_docker() {
  docker ps --format '{{.Names}}'
}

```

### Wiring the Generator to Your Command

Use the low-level completion API to connect your generator to a command. The fourth argument to `_fzf_setup_completion path` specifies the generator suffix:

```bash

# Args: type, command, generator suffix, trigger, cmd-placeholder

_fzf_setup_completion path mydocker docker "" ""

```

Alternatively, invoke the completion machinery directly:

```bash
_fzf_complete -m --preview 'docker inspect {}' -- \
  < <(_fzf_compgen_docker)

```

This bypasses the standard registration and allows custom `fzf` options like preview windows.

## Low-Level API for Fine-Grained Control

For scenarios requiring precise control over `fzf` flags or completion behavior, use the `_fzf_complete` function directly.

### Direct Invocation Pattern

The `_fzf_complete` function (lines 146-164 in [`shell/completion.bash`](https://github.com/junegunn/fzf/blob/main/shell/completion.bash)) accepts `fzf` options followed by a `--` separator and a candidate list:

```bash

# Example: Custom completion for git branches with preview

_fzf_complete -m --preview 'git log -1 --pretty=oneline {}' \
  -- "--walker=file,dir,follow" < <(
    git branch --all --color=never | sed 's#^\* ##'
  )

```

### Understanding COMPREPLY Population

The completion functions ultimately populate the `COMPREPLY` array variable that Bash uses to display completion candidates. When `_fzf_complete` finishes execution, it writes selected items to `COMPREPLY`, which Bash then inserts into the command line.

## Summary

- **Use `_fzf_setup_completion`** as the primary API to register fuzzy completion for custom commands, specifying types like `path`, `dir`, `var`, `alias`, `host`, or `proc`.

- **Define custom generators** using the `_fzf_compgen_*` naming convention when you need to complete non-standard inputs like Docker containers or Git branches.

- **Leverage `_fzf_complete` directly** for advanced scenarios requiring custom `fzf` flags, preview windows, or specialized candidate filtering.

- **All customization happens in [`shell/completion.bash`](https://github.com/junegunn/fzf/blob/main/shell/completion.bash)**—no modifications to the Go source code are necessary, making upgrades safe and configurations portable.

## Frequently Asked Questions

### How do I trigger fuzzy completion for my custom command?

Type your command followed by the trigger sequence (default is `**`) and press Tab. For example, `mycat **<TAB>` opens the fuzzy finder. You can change the trigger by setting the `FZF_COMPLETION_TRIGGER` environment variable.

### Can I use fuzzy completion with commands that already have Bash completions?

Yes. The `_fzf_setup_completion` function overrides existing completion specifications for the specified commands. It uses `complete -F` to replace the default completion handler with the fzf fuzzy completion wrapper, preserving the original behavior for non-triggered tabs.

### What is the difference between `path` and `dir` completion types?

The `path` type uses `_fzf_path_completion` which completes both files and directories, while the `dir` type uses `_fzf_dir_completion` which restricts candidates to directories only and adds the `-o nospace` option to prevent Bash from appending a space after directory names, allowing further navigation.

### How can I pass extra options to `fzf` during completion?

For simple cases, set the `FZF_COMPLETION_OPTS` environment variable to include global options. For command-specific customization, bypass `_fzf_setup_completion` and call `_fzf_complete` directly with your desired flags, placing them before the `--` separator as shown in the low-level API examples.