Comandos Serpl

Comandos abrangentes da interface de terminal Serpl para operações de busca e substituição em todo o projeto.

Instalação

Comando	Descrição
cargo install serpl	Instalar via Cargo (Rust)
brew install serpl	Instalar via Homebrew (macOS)
nix-env -i serpl	Instalar via Nix
pacman -S serpl	Instalar no Arch Linux
Download do GitHub Releases	Binários pré-compilados disponíveis
serpl --version	Mostrar versão do Serpl

Uso Básico

Comando	Descrição
serpl	Iniciar Serpl no diretório atual
serpl --search-text "oldFunc"	Iniciar com termo de busca pré-preenchido
serpl --replace-text "newFunc"	Iniciar com substituição pré-preenchida
serpl --search-path ./src	Pesquisar em diretório específico
serpl --hidden	Incluir arquivos ocultos na busca
serpl --ignore-case	Busca insensível a maiúsculas/minúsculas

Teclas de Navegação

Atalho	Descrição
j	Mover para baixo na lista de resultados
k	Mover para cima na lista de resultados
g	Saltar para primeiro resultado
G	Saltar para último resultado
/	Pesquisar dentro da lista de resultados
Enter	Selecionar/confirmar ação
Escape	Cancelar/voltar
q	Sair do Serpl

Alternância de Modo

Atalho	Descrição
Tab	Alternar entre campos de busca e substituição
Ctrl + N	Alternar entre modos de busca e substituição
Ctrl + B	Abrir diálogo de ajuda
Ctrl + C	Sair da aplicação

Operações de Busca

Atalho	Descrição
Digite no campo de busca	Busca em tempo real em todos os arquivos
Ctrl + N	Alternar modo de busca
Modo sensível a maiúsculas	Corresponder caso exato
Modo insensível a maiúsculas	Ignorar diferenças de caso
Modo Regex	Usar expressões regulares
Modo AST Grep	Busca de código estrutural

Operações de Substituição

Atalho	Descrição
Ctrl + O	Processar substituição para TODOS os arquivos
d	Deletar arquivo selecionado ou linha de resultados
Substituição simples	Substituir todas as ocorrências diretamente
Substituição preservando caso	Manter padrão de caso do original
Substituição AST Grep	Substituição de código estrutural

Modos de Substituição

Modo	Descrição
Simple	Substituição de texto direto
Preserve Case	Corresponder padrão de caso do texto original
AST Grep	Substituição ciente de árvore de sintaxe

Modos de Busca

Modo	Descrição
Fixed String	Correspondência de texto literal
Regex	Correspondência de expressão regular
AST Grep	Correspondência de padrão de código estrutural

Operações com Arquivos

Atalho	Descrição
d	Remover arquivo/linha de resultados (pular)
Ctrl + O	Aplicar substituições a todos os arquivos restantes
Revisar mudanças por arquivo	Ver preview antes de aplicar
Undo não está disponível	Mudanças são permanentes—usar Git

Configuração

Configuração	Descrição
~/.config/serpl/config.json	Local do arquivo de configuração
Keybindings customizados	Sobrescrever atalhos padrão
Padrão de modo de busca	Definir modo de busca preferido
Padrão de modo de substituição	Definir modo de substituição preferido
Filtros de padrão de arquivo	Configurar quais arquivos incluir
Padrões de ignorar	Configurar quais arquivos excluir

Exemplo de Configuração

{
  "key_bindings": {
    "quit": "q",
    "navigate_up": "k",
    "navigate_down": "j",
    "go_to_top": "g",
    "go_to_bottom": "G",
    "delete": "d",
    "process_replace": "Ctrl+o",
    "toggle_help": "Ctrl+b",
    "search_in_list": "/"
  },
  "search_mode": "fixed_string",
  "replace_mode": "simple"
}

Workflows Comuns

Workflow	Descrição
Renomear variável	Buscar nome antigo → Substituir por nome novo
Atualizar caminhos de import	Buscar caminho antigo → Substituir por caminho novo
Migrar chamadas de API	Buscar deprecated → Substituir por nova API
Corrigir typos em projeto	Buscar digitação errada → Substituir com correta
Atualizar valores de config	Buscar valor antigo → Substituir por valor novo

Integração com Git

Workflow	Descrição
git diff após serpl	Revisar todas as mudanças feitas
git stash antes de serpl	Salvar trabalho atual primeiro
git checkout -- . para desfazer	Reverter todas as mudanças se necessário
Trabalhar em uma branch	Isolar mudanças de busca-substituição
git add -p após serpl	Fazer stage seletivo de mudanças

Comparação com Alternativas

Recurso	Serpl	sed	VS Code
Preview interativo	Sim	Não	Sim
Interface TUI	Sim	Não	GUI
Preservar caso	Sim	Manual	Sim
AST Grep	Sim	Não	Extensão
Funciona via SSH	Sim	Sim	Não
Suporte a Regex	Sim	Sim	Sim

Dicas e Boas Práticas

Dica	Descrição
Sempre usar Git	Fazer commit antes de executar substituições
Preview antes de aplicar	Revisar cada mudança na TUI
Usar AST Grep para código	Correspondência estrutural evita falsos positivos
Usar preservar caso	Mantém camelCase, PascalCase, etc.
Remover falsos positivos	Usar d para pular correspondências indesejadas
Pesquisar caminhos específicos	Usar --search-path para estreitar escopo
Verificar arquivos ocultos	Usar flag --hidden quando necessário