fzf: Buscador Fuzzy para a Linha de Comando

2026-06-05 Tempo de leitura: Cerca de 9 min Dificuldade: Intermediate

O Que e fzf?

Conclusao: fzf e um filtro UNIX que le 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) e um filtro interativo de proposito geral para a linha de comando. Seu modelo e simples e se resume a tres passos:

1. Ler uma lista de linhas da entrada padrao (stdin)
2. Refinar candidatos conforme voce digita, usando correspondencia de substring e fuzzy
3. Imprimir a(s) linha(s) escolhida(s) na saida padrao (stdout)

Como le stdin e escreve stdout, fzf se compoe com qualquer comando: find | fzf, ps -ef | fzf, git log | fzf. Qualquer lista se torna algo que voce pode filtrar na hora e selecionar uma (ou varias) linhas.

Como Instalar o fzf?

Conclusao: O gerenciador de pacotes da sua distro (apt / dnf / brew) e o caminho mais facil. Para a versao mais recente ou atalhos completos, use o script de instalacao oficial do GitHub.

Instalar via gerenciador de pacotes e 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 voce quiser atalhos de teclado e autocompletar configurados de forma confiavel, instale diretamente do repositorio oficial.

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

O script de instalacao e interativo: ele pergunta se deve ativar atalhos de teclado, autocompletar e atualizar a configuracao do shell. Responder y a tudo e adequado para a maioria dos usuarios.

fzf --version

0.55.0 (cabc3c0)

Ative os Tres Atalhos de Teclado com Integracao Shell

Conclusao: A integracao shell ativa CTRL-R (historico), CTRL-T (inserir arquivo) e ALT-C (mudar diretorio). No fzf 0.48.0+ e uma unica linha na configuracao do shell.

Adicione uma linha ao arquivo de configuracao do seu shell.

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

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

Recarregue com source ~/.bashrc (ou abra um novo terminal). Os tres atalhos de teclado agora estao ativos.

A maior vantagem e o CTRL-R. Diferente do CTRL-R padrao (busca reversa incremental), voce pode digitar palavras parcialmente lembradas em qualquer ordem e obter uma lista rolavel para escolher.

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

Por Que a Busca do fzf e Tao Rapida? A Sintaxe de Correspondencia

Conclusao: Por padrao, o fzf faz correspondencia fuzzy AND entre termos separados por espaco. Adicione simbolos para exata, prefixo/sufixo, negacao e OR para controlar a filtragem com precisao.

Na caixa de entrada, caracteres correspondem mesmo fora de ordem e de forma nao contiqua (ex: ako corresponde a awk-oneliners). Simbolos alternam o modo de correspondencia.

| Entrada | Significado | | ---------- | -------------------------------------------------------- | ------------------------------ | | git push | Contem ambos git e push (AND, fuzzy) | | 'wild | Contem wild como correspondencia exata (sem fuzzy) | | ^core | Comeca com core | | .md$ | Termina com .md | | !test | Nao contem test (negacao) | | ^src | ^app | Comeca com src ou app (OR) |

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

--query (abreviacao -q) fornece uma consulta inicial, util quando um script deve iniciar o fzf ja parcialmente filtrado.

Como Usar na Pratica? (Receitas)

Conclusao: O padrao central e incorporar $(... | fzf) em substituicao 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 encerra-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 diretorio e entrar nele (sem ALT-C)

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

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

Visualizar Conteudo Enquanto Escolhe

Conclusao: Passe --preview com um comando que receba a linha atual como entrada, e o conteudo aparece a direita. O placeholder {} expande para o candidato atual.

Espiar o conteudo dos arquivos durante a selecao 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, voce pode revisar um diff enquanto escolhe um commit.

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

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

Opcoes Comuns e Variaveis de Ambiente

Conclusao: Modele a aparencia com --height / --layout=reverse / --border. Defina padroes uma vez em FZF_DEFAULT_OPTS e FZF_DEFAULT_COMMAND para aplica-los em todo lugar.

Opcoes 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-selecao com TAB
• --preview 'cmd {}': Janela de preview

Fixar padroes com variaveis 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 voce executa fzf sem argumentos e para CTRL-T. Usar fd ou rg --files fornece uma lista rapida que respeita .gitignore.

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