Zoxide

Comando cd mais inteligente que aprende seus hábitos usando um algoritmo de frecência para navegação rápida entre diretórios em diferentes shells.

Instalação

Gerenciadores de Pacotes

Comando	Descrição
`brew install zoxide`	Instalar no macOS com Homebrew
`cargo install zoxide --locked`	Instalar a partir do crates.io
`apt install zoxide`	Instalar no Debian/Ubuntu
`pacman -S zoxide`	Instalar no Arch Linux
`dnf install zoxide`	Instalar no Fedora
`scoop install zoxide`	Instalar no Windows com Scoop
`winget install ajeetdsouza.zoxide`	Instalar no Windows com winget
`nix-env -i zoxide`	Instalar no NixOS
`conda install -c conda-forge zoxide`	Instalar com Conda
`curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh \| sh`	Instalar via script shell

Inicialização do Shell

Comando	Descrição
`eval "$(zoxide init bash)"`	Inicializar para Bash (adicionar ao .bashrc)
`eval "$(zoxide init zsh)"`	Inicializar para Zsh (adicionar ao .zshrc)
`zoxide init fish \| source`	Inicializar para Fish (adicionar ao config.fish)
`Invoke-Expression (& { (zoxide init powershell) })`	Inicializar para PowerShell
`zoxide init nushell \| save -f ~/.zoxide.nu`	Inicializar para Nushell
`eval "$(zoxide init elvish)"`	Inicializar para Elvish
`eval (zoxide init xonsh)`	Inicializar para Xonsh

Exemplos de Configuração do Shell

# Bash — adicionar ao ~/.bashrc
eval "$(zoxide init bash)"

# Zsh — adicionar ao ~/.zshrc
eval "$(zoxide init zsh)"

# Fish — adicionar ao ~/.config/fish/config.fish
zoxide init fish | source

# PowerShell — adicionar ao $PROFILE
Invoke-Expression (& { (zoxide init powershell | Out-String) })

# Nushell — adicionar ao env.nu
zoxide init nushell | save -f ~/.zoxide.nu
source ~/.zoxide.nu

Uso Básico

Navegação

Comando	Descrição
`z foo`	Saltar para o diretório com melhor classificação correspondente a “foo”
`z foo bar`	Saltar para o diretório correspondente a “foo” e “bar”
`z ~/projects`	Saltar para o caminho exato (como cd)
`z ..`	Ir para o diretório pai
`z -`	Ir para o diretório anterior
`z`	Ir para o diretório home (sem argumentos)
`zi`	Seleção interativa com fzf
`zi foo`	Seleção interativa pré-filtrada por “foo”
`z foo/`	Saltar para subdiretório (barra final)

Exemplos de Uso

# Após visitar diretórios, o zoxide os aprende
cd ~/projects/myapp          # Ensinar ao zoxide sobre este caminho
cd ~/documents/reports       # Ensinar ao zoxide sobre este caminho
cd /var/log/nginx            # Ensinar ao zoxide sobre este caminho

# Depois, saltar com correspondências parciais
z myapp                      # Salta para ~/projects/myapp
z reports                    # Salta para ~/documents/reports
z nginx                      # Salta para /var/log/nginx

# Múltiplas palavras-chave refinam a correspondência
z proj myapp                 # Corresponde especificamente a ~/projects/myapp
z doc rep                    # Corresponde a ~/documents/reports

Sintaxe de Consulta

Regras de Correspondência

Comando	Descrição
`z proj`	Corresponder qualquer diretório contendo “proj”
`z proj rust`	Corresponder diretório contendo “proj” e “rust”
`z /home/user/docs`	Usar caminho absoluto diretamente
`z docs/`	Corresponder e preferir subdiretório chamado “docs”
Palavras-chave correspondem a componentes do caminho	”proj” corresponde a `/home/user/projects`
Última palavra-chave pode corresponder prefixo	`z pr` corresponde a `projects`
Múltiplas palavras-chave usam correspondência AND	Todas devem aparecer no caminho
Correspondência não diferencia maiúsculas	`z PROJ` corresponde a `projects`

Algoritmo de Frecência

Conceito	Descrição
Frecência = Frequência + Recência	Pontuação baseada em frequência e recência de visitas
Visitas recentes pontuam mais	Diretórios visitados hoje pontuam mais que na semana passada
Diretórios visitados frequentemente classificam melhor	Uso regular aumenta a pontuação ao longo do tempo
Pontuações decaem com o tempo	Diretórios não utilizados perdem classificação gradualmente
Banco de dados auto-limpa pontuações baixas	Entradas antigas e não utilizadas são removidas automaticamente
Máximo de entradas controlado por `_ZO_MAXAGE`	Padrão: 10.000 entradas

Seleção Interativa

Comando	Descrição
`zi`	Abrir fzf com todos os diretórios rastreados
`zi query`	Abrir fzf pré-filtrado por consulta
`↑ / ↓` no fzf	Navegar nos resultados
`Enter` no fzf	Selecionar e saltar para o diretório
`Escape` no fzf	Cancelar seleção
Digitar no fzf para filtrar	Refinar resultados ainda mais
Requer `fzf` instalado	Instalar fzf para modo interativo
`Tab` no fzf	Alternar seleção (modo multi-seleção)

Exemplo Interativo

# Abrir buscador fuzzy interativo com todos os diretórios rastreados
zi

# Pré-filtrar para diretórios contendo "project"
zi project

# Formato de saída no fzf mostra pontuações:
#   3.50   /home/user/projects/myapp
#   2.10   /home/user/projects/api
#   1.20   /var/www/project-site

Integração com Shell

Substituir cd

Comando	Descrição
`eval "$(zoxide init bash --cmd cd)"`	Substituir cd pelo zoxide no Bash
`eval "$(zoxide init zsh --cmd cd)"`	Substituir cd pelo zoxide no Zsh
`--cmd cd` substitui o comando `cd`	Faz o cd usar zoxide (cd, cdi)
`--cmd j` cria `j` e `ji`	Usar nomes de comandos personalizados
Padrão cria `z` e `zi`	Comandos padrão do zoxide

Configuração de Hook

Comando	Descrição
`--hook pwd`	Atualizar banco de dados ao mudar de diretório (padrão)
`--hook prompt`	Atualizar banco de dados a cada prompt
`--hook none`	Desativar rastreamento automático

Integração com Outras Ferramentas

# Substituir cd no Bash pelo zoxide
eval "$(zoxide init bash --cmd cd)"
# Agora 'cd' usa zoxide, 'cdi' abre interativo

# Usar nome de comando personalizado
eval "$(zoxide init zsh --cmd j)"
# Agora 'j foo' salta, 'ji' abre interativo

# Combinar com fzf para experiência aprimorada
export _ZO_FZF_OPTS="--height 40% --reverse --border"

Gerenciamento do Banco de Dados

Consultar Banco de Dados

Comando	Descrição
`zoxide query foo`	Mostrar melhor correspondência sem saltar
`zoxide query foo --list`	Listar todas as correspondências com pontuações
`zoxide query foo --score`	Mostrar correspondências com pontuações de frecência
`zoxide query --all`	Listar todo o banco de dados
`zoxide query --all --score`	Listar banco de dados com pontuações
`zoxide query --exclude /path`	Excluir caminho específico dos resultados
`zoxide query --list \| head -20`	Top 20 diretórios

Gerenciar Entradas

Comando	Descrição
`zoxide add /path/to/dir`	Adicionar diretório manualmente ao banco de dados
`zoxide remove /path/to/dir`	Remover diretório do banco de dados
`zoxide edit`	Abrir banco de dados no $EDITOR (interativo)
Banco de dados armazenado em `$_ZO_DATA_DIR/db.zo`	Localização padrão do banco de dados

Exemplos de Banco de Dados

# Verificar o que o zoxide corresponderia
zoxide query project --list --score
# Saída:
#    12.00  /home/user/projects/webapp
#     8.50  /home/user/projects/api
#     3.20  /home/user/old-project

# Alimentar manualmente o banco de dados para novas máquinas
zoxide add ~/projects/webapp
zoxide add ~/projects/api
zoxide add ~/.config/nvim

# Remover entradas obsoletas (diretórios deletados)
zoxide query --all | while read -r dir; do
  [ -d "$dir" ] || zoxide remove "$dir"
done

# Exportar banco de dados para backup
zoxide query --all --score > zoxide-backup.txt

Importar de Outras Ferramentas

Comando	Descrição
`zoxide import --from z path/to/.z`	Importar do banco de dados z.sh
`zoxide import --from autojump path/to/autojump.txt`	Importar do banco de dados autojump
`zoxide import --merge --from z path/to/.z`	Importar com mesclagem (manter entradas existentes)
`zoxide import --from z --merge ~/.z`	Importação comum do z.sh

Exemplos de Migração

# Migrar do z.sh (mais comum)
zoxide import --from z ~/.z

# Migrar do autojump
zoxide import --from autojump ~/.local/share/autojump/autojump.txt

# Mesclar com banco de dados existente (não sobrescrever)
zoxide import --merge --from z ~/.z

# Após importar, verificar
zoxide query --all --score | head -20

Variáveis de Ambiente

Comando	Descrição
`export _ZO_DATA_DIR="$HOME/.local/share/zoxide"`	Definir diretório do banco de dados
`export _ZO_ECHO=1`	Imprimir diretório correspondido antes de saltar
`export _ZO_EXCLUDE_DIRS="/tmp/:/private/"`	Excluir diretórios do rastreamento
`export _ZO_FZF_OPTS="--height 40%"`	Opções personalizadas do fzf para zi
`export _ZO_MAXAGE=10000`	Definir máximo de entradas no banco de dados
`export _ZO_RESOLVE_SYMLINKS=1`	Resolver symlinks antes de armazenar

Exemplo de Configuração

# ~/.bashrc ou ~/.zshrc — configuração completa do zoxide

# Definir diretório personalizado de dados
export _ZO_DATA_DIR="$HOME/.local/share/zoxide"

# Imprimir o diretório correspondido antes de saltar
export _ZO_ECHO=1

# Excluir diretórios temporários e do sistema
export _ZO_EXCLUDE_DIRS="$HOME:$HOME/Downloads:/tmp/*:/private/*"

# Personalizar aparência do fzf para modo interativo
export _ZO_FZF_OPTS="
  --height 40%
  --layout reverse
  --border rounded
  --preview 'ls -la {2..}'
  --preview-window right:40%
"

# Máximo de entradas antes da limpeza (padrão: 10000)
export _ZO_MAXAGE=10000

# Resolver symlinks para caminhos canônicos
export _ZO_RESOLVE_SYMLINKS=1

# Inicializar zoxide (deve ser APÓS as exportações)
eval "$(zoxide init zsh)"

Completações e Suporte a Tab

Comando	Descrição
`z <Tab>`	Autocompletar a partir de diretórios rastreados
`z foo<Tab>`	Completar diretórios correspondentes
Completação Bash via `zoxide init`	Automática com inicialização do shell
Completação Zsh via `zoxide init`	Automática com inicialização do shell
Completação Fish via `zoxide init`	Automática com inicialização do shell

Boas Práticas

Deixe o zoxide aprender naturalmente — Use seu shell normalmente e o zoxide construirá seu banco de dados a partir dos seus hábitos. Não tente alimentar manualmente cada diretório.
Use duas palavras-chave para precisão — Quando múltiplos diretórios correspondem, adicione uma segunda palavra-chave: z proj api é mais preciso que apenas z api.
Use barra final para subdiretórios — z foo/ prefere subdiretórios do diretório atual chamados “foo”, enquanto z foo busca em todo o banco de dados.
Substitua cd para aprendizado máximo — Use --cmd cd na inicialização do shell para que cada mudança de diretório alimente o zoxide, não apenas quando você lembrar de usar z.
Configure exclusões cedo — Defina _ZO_EXCLUDE_DIRS para pular diretórios temporários, pastas de build e caminhos de node_modules que poluem os resultados.
Use zi para saltos ambíguos — Quando não tem certeza qual diretório vai corresponder, use zi (interativo) para visualizar e selecionar entre os candidatos.
Migre dados existentes — Se estiver mudando do z.sh, autojump ou fasd, importe seu banco de dados com zoxide import para começar com um cache quente.
Limpe entradas obsoletas — Periodicamente remova entradas de diretórios deletados usando zoxide edit ou um script de limpeza para manter os resultados relevantes.
Faça backup do seu banco de dados — Exporte com zoxide query --all --score antes de reinstalar o SO ou migrar máquinas.
Personalize a aparência do fzf — Defina _ZO_FZF_OPTS com --preview 'ls {2..}' para mostrar o conteúdo do diretório no seletor interativo.