06 nov 2026 · linux, terminal, zsh · 4 min

autocomplete no terminal: o que o zsh faz sozinho e o que precisa de plugin

Zsh traz completion nativo via compinit. Autosuggestions, syntax highlighting e completions extras sao plugins que voce clona e carrega por conta propria. A ordem de carga importa: syntax-highlighting deve ser o ultimo a carregar, senao a cor quebra.

O que o zsh faz sozinho

Zsh nao precisa de plugin para completar comandos, caminhos e opcoes. Basta ativar compinit no .zshrc:

autoload -Uz compinit && compinit

Com isso, git che<TAB> lista subcomandos e cd /usr/loc<TAB> completa caminhos. A completion e contextual: conhece as opcoes de cada comando se o arquivo de completion existir, o que vem com o zsh ou com o pacote do programa. O bash tambem tem completion, mas o do zsh e mais rico e nao precisa de pacote extra.

compinit le um cache em ~/.zcompdump para nao reparsear tudo a cada abertura. Se voce instalou um programa novo e o Tab nao sugere as opcoes dele, o cache esta velho. Rode rm -f ~/.zcompdump && compinit uma vez. Em disco lento, use compinit -C para pular a verificacao de seguranca e abrir mais rapido.

A completion nativa cobre a maioria dos programas instalados, mas programas novos ou pouco conhecidos podem nao ter arquivo de completion. Nesse caso o Tab nao sugere nada ou sugere arquivos. zsh-completions preenche essa lacuna com mais de 500 definitions, sem custo de execucao perceptivel.

O que precisa de plugin

Tres coisas que as pessoas querem e que nao vem no zsh base:

• Autosuggestion, o texto cinza apos o cursor baseado no historico: zsh-users/zsh-autosuggestions, licenca MIT.
• Syntax highlighting, vermelho para comando inexistente: zsh-users/zsh-syntax-highlighting, licenca BSD-3.
• Completions extras para programas sem completion nativo: zsh-users/zsh-completions.

O artefato

Script que verifica o zsh, lista os 3 plugins faltantes, cria backup do .zshrc e anexa o bloco minimo. Rode numa maquina com zsh instalado.

#!/usr/bin/env bash
set -euo pipefail

ZSHRC="$HOME/.zshrc"
PLUGIN_DIR="${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins"

echo "== 1. zsh que voce ja tem =="
if command -v zsh >/dev/null 2>&1; then
  zsh --version
else
  echo "zsh nao encontrado neste ambiente (contêiner minimo)."
  echo "no seu sistema: apt install zsh  (ou brew install zsh)"
fi

echo

echo "== 2. completion nativo (sem plugin) =="
echo "zsh traz compinit. basta ativar:"
echo "  autoload -Uz compinit && compinit"
echo "teste: digite 'git che<TAB>' e veja as subcomandos."

echo

echo "== 3. plugins que precisam de clone =="
for p in zsh-autosuggestions zsh-syntax-highlighting zsh-completions; do
  if [ -d "$PLUGIN_DIR/$p" ]; then
    echo "ok: $p ja esta em $PLUGIN_DIR/$p"
  else
    echo "falta: $p (clone em $PLUGIN_DIR/$p)"
  fi
done

echo

echo "== 4. escrevendo bloco em $ZSHRC (backup antes) =="
if [ -f "$ZSHRC" ]; then
  cp "$ZSHRC" "$ZSHRC.bak.$(date +%s)"
  echo "backup criado"
fi
mkdir -p "$PLUGIN_DIR"
cat >> "$ZSHRC" <<'EOF'

# --- autocomplete minimo ---
autoload -Uz compinit && compinit
# plugins (clone antes de ativar; ver README de cada um)
# source $ZSH_CUSTOM/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh
# source $ZSH_CUSTOM/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
EOF
echo "bloco anexado (linhas comentadas: descomente apos clonar)"

echo

echo "== 5. ordem importa =="
echo "syntax-highlighting deve ser o ultimo a carregar; autosuggestions antes dele."
echo "pronto."

Como verificar

Rode o script e confira a saida: ele deve listar o zsh instalado, mostrar o comando compinit e apontar quais dos 3 plugins faltam. Depois de clonar os plugins e descomentar as linhas, abra um terminal novo e digite um comando antigo: o texto cinza deve aparecer. Digite um comando inexistente: a cor deve mudar para vermelho.

Se der errado

• Completion nao aparece: compinit nao foi chamado ou o cache esta velho. Rode rm -f ~/.zcompdump && compinit e reabra o terminal.
• Syntax highlighting desliga apos autosuggestion: a ordem esta invertida. syntax-highlighting precisa ser o ultimo a ser carregado.
• Clone falha com permissao: o diretorio de plugins nao existe. O script cria com mkdir -p, mas se ZSH_CUSTOM aponta para outro lugar, ajuste a variavel.

FAQ

Preciso do oh-my-zsh para isso? Nao. Os plugins funcionam sozinhos com source no .zshrc. oh-my-zsh e um gerenciador de plugins e temas; util, mas nao obrigatorio.

compinit e lento na abertura do terminal. E normal em disco lento. Rode compinit -C para pular a verificacao de seguranca, ou use zsh-defer para carregar em segundo plano.

Autosuggestion nao aparece para comando novo. Ele so sugere o que esta no historico. Rode o comando uma vez e ele passa a aparecer.

Qual a diferenca entre zsh-autosuggestions e zsh-autocomplete? zsh-autosuggestions mostra uma sugestao cinza do historico. zsh-autocomplete abre um menu de completion enquanto voce digita. Sao complementares.

Posso usar isso no bash? Nao diretamente. O bash tem ble.sh e bash-completion, mas a API e diferente. Veja fzf no terminal para uma opcao que funciona nos dois.

Como aceitar apenas parte da sugestao? Qualquer widget que move o cursor para a direita aceita parte do texto sugerido. Alt+F aceita uma palavra; Ctrl+F aceita caractere por caractere. Veja a documentacao do plugin.

Figura

Fontes: zsh-autosuggestions (MIT), zsh-syntax-highlighting (BSD-3), zsh-completions, completion system. Veja tambem terminal que parece limpo.