fzf: Buscador Fuzzy para a Linha de Comando

2026-06-05 Tempo de leitura: Cerca de 9 min Dificuldade: Intermediário+

O Que é fzf?

Conclusão: fzf é um filtro UNIX que lê uma lista do stdin, permite busca fuzzy interativa e imprime a linha escolhida no stdout. Ele acelera qualquer tarefa de "escolher um de uma lista".

fzf (fuzzy finder) é um filtro interativo de propósito geral para a linha de comando. Seu modelo é simples e se resume a três passos:

1. Ler uma lista de linhas da entrada padrão (stdin)
2. Refinar candidatos conforme você digita, usando correspondência de substring e fuzzy
3. Imprimir a(s) linha(s) escolhida(s) na saída padrão (stdout)

Como lê stdin e escreve stdout, fzf se compõe com qualquer comando: find | fzf, ps -ef | fzf, git log | fzf. Qualquer lista se torna algo que você pode filtrar na hora e selecionar uma (ou várias) linhas.

Como Instalar o fzf?

Conclusão: O gerenciador de pacotes da sua distro (apt / dnf / brew) é o caminho mais fácil. Para a versão mais recente ou atalhos completos, use o script de instalação oficial do GitHub.

Instalar via gerenciador de pacotes é a rota mais simples.

# Ubuntu / Debian
sudo apt install fzf

# Fedora / familia RHEL
sudo dnf install fzf

# macOS (Homebrew)
brew install fzf

Se o pacote da distro for antigo, ou você quiser atalhos de teclado e autocompletar configurados de forma confiável, instale diretamente do repositório oficial.

git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
~/.fzf/install

O script de instalação é interativo: ele pergunta se deve ativar atalhos de teclado, autocompletar e atualizar a configuração do shell. Responder y a tudo é adequado para a maioria dos usuários.

fzf --version

0.55.0 (cabc3c0)

Ative os Três Atalhos de Teclado com Integração Shell

Conclusão: A integração shell ativa CTRL-R (histórico), CTRL-T (inserir arquivo) e ALT-C (mudar diretório). No fzf 0.48.0+ é uma única linha na configuração do shell.

Adicione uma linha ao arquivo de configuração do seu shell.

# ~/.bashrc (bash)
eval "$(fzf --bash)"

# ~/.zshrc (zsh)
source <(fzf --zsh)

Recarregue com source ~/.bashrc (ou abra um novo terminal). Os três atalhos de teclado agora estão ativos.

A maior vantagem é o CTRL-R. Diferente do CTRL-R padrão (busca reversa incremental), você pode digitar palavras parcialmente lembradas em qualquer ordem e obter uma lista rolável para escolher.

# Exemplo: quando instalado via metodo git clone
[ -f ~/.fzf.bash ] && source ~/.fzf.bash

Por Que a Busca do fzf é Tão Rápida? A Sintaxe de Correspondência

Conclusão: Por padrão, o fzf faz correspondência fuzzy AND entre termos separados por espaço. Adicione símbolos para exata, prefixo/sufixo, negação e OR para controlar a filtragem com precisão.

Na caixa de entrada, caracteres correspondem mesmo fora de ordem e de forma não contiqua (ex: ako corresponde a awk-oneliners). Símbolos alternam o modo de correspondência.

| Entrada | Significado | | ---------- | -------------------------------------------------------- | ------------------------------ | | git push | Contém ambos git e push (AND, fuzzy) | | 'wild | Contém wild como correspondência exata (sem fuzzy) | | ^core | Começa com core | | .md$ | Termina com .md | | !test | Não contém test (negação) | | ^src | ^app | Começa com src ou app (OR) |

# Manter apenas arquivos terminando em .log que nao contem "archive"
find . -type f | fzf --query "'.log$ !archive"

--query (abreviação -q) fornece uma consulta inicial, útil quando um script deve iniciar o fzf já parcialmente filtrado.

Como Usar na Prática? (Receitas)

Conclusão: O padrão central é incorporar $(... | fzf) em substituição de comando. Tarefas de "escolher e executar" (abrir no vim, matar processo, trocar branch do git) se tornam one-liners.

Escolher um arquivo e abrir no vim

vim "$(fzf)"

Escolher um processo e encerrá-lo

kill -9 "$(ps -ef | fzf | awk '{print $2}')"

Escolher uma branch do git e fazer checkout

git checkout "$(git branch --all | fzf | tr -d ' *')"

Escolher um diretório e entrar nele (sem ALT-C)

cd "$(find . -type d | fzf)"

# Marcar varios arquivos para remocao de uma vez
rm -i $(fzf -m)

Visualizar Conteúdo Enquanto Escolhe

Conclusão: Passe --preview com um comando que receba a linha atual como entrada, e o conteúdo aparece a direita. O placeholder {} expande para o candidato atual.

Espiar o conteúdo dos arquivos durante a seleção reduz escolhas erradas.

# Mostrar o conteudo do arquivo selecionado
fzf --preview 'cat {}'

# Com bat, obter preview colorizado (numeros de linha, destaque de sintaxe)
fzf --preview 'bat --color=always {}'

{} expande para "a linha atualmente destacada". Combinado com git log, você pode revisar um diff enquanto escolhe um commit.

git log --oneline | fzf --preview 'git show --color=always {1}'

{1} é o primeiro campo da linha selecionada (o hash do commit). Você pode referenciar campos dentro do comando de preview.

Opções Comuns e Variáveis de Ambiente

Conclusão: Modele a aparência com --height / --layout=reverse / --border. Defina padrões uma vez em FZF_DEFAULT_OPTS e FZF_DEFAULT_COMMAND para aplicá-los em todo lugar.

Opções frequentemente usadas

• --height 40%: Mostrar a janela nos 40% inferiores em vez de ocupar toda a tela
• --layout=reverse: Entrada no topo, candidatos abaixo (leitura de cima para baixo)
• --border: Desenhar uma borda
• --multi / -m: Multi-seleção com TAB
• --preview 'cmd {}': Janela de preview

Fixar padrões com variáveis de ambiente

# Adicionar ao ~/.bashrc ou similar
export FZF_DEFAULT_OPTS='--height 40% --layout=reverse --border'

# Trocar o comando de candidatos para fd / ripgrep (respeita .gitignore, ignora ocultos)
export FZF_DEFAULT_COMMAND='fd --type f --hidden --exclude .git'

FZF_DEFAULT_COMMAND gera candidatos quando você executa fzf sem argumentos e para CTRL-T. Usar fd ou rg --files fornece uma lista rápida que respeita .gitignore.

# ~/.bashrc
eval "$(fzf --bash)"
export FZF_DEFAULT_OPTS='--height 40% --layout=reverse --border'