Zoxide

Comando cd más inteligente que aprende tus hábitos usando un algoritmo de frecuencia para una navegación rápida de directorios en múltiples shells.

Instalación

Gestores de Paquetes

Comando	Descripción
`brew install zoxide`	Instalar en macOS con Homebrew
`cargo install zoxide --locked`	Instalar desde crates.io
`apt install zoxide`	Instalar en Debian/Ubuntu
`pacman -S zoxide`	Instalar en Arch Linux
`dnf install zoxide`	Instalar en Fedora
`scoop install zoxide`	Instalar en Windows con Scoop
`winget install ajeetdsouza.zoxide`	Instalar en Windows con winget
`nix-env -i zoxide`	Instalar en NixOS
`conda install -c conda-forge zoxide`	Instalar con Conda
`curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh \| sh`	Instalar mediante script de shell

Inicialización del Shell

Comando	Descripción
`eval "$(zoxide init bash)"`	Inicializar para Bash (agregar a .bashrc)
`eval "$(zoxide init zsh)"`	Inicializar para Zsh (agregar a .zshrc)
`zoxide init fish \| source`	Inicializar para Fish (agregar a 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

Ejemplos de Configuración del Shell

# Bash — agregar a ~/.bashrc
eval "$(zoxide init bash)"

# Zsh — agregar a ~/.zshrc
eval "$(zoxide init zsh)"

# Fish — agregar a ~/.config/fish/config.fish
zoxide init fish | source

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

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

Uso Básico

Navegación

Comando	Descripción
`z foo`	Saltar al directorio mejor clasificado que coincida con “foo”
`z foo bar`	Saltar al directorio que coincida con “foo” y “bar”
`z ~/projects`	Saltar a una ruta exacta (como cd)
`z ..`	Ir al directorio padre
`z -`	Ir al directorio anterior
`z`	Ir al directorio home (sin argumentos)
`zi`	Selección interactiva con fzf
`zi foo`	Selección interactiva prefiltrada por “foo”
`z foo/`	Saltar a subdirectorio (barra final)

Ejemplos de Uso

# Después de visitar directorios, zoxide los aprende
cd ~/projects/myapp          # Enseñar a zoxide esta ruta
cd ~/documents/reports       # Enseñar a zoxide esta ruta
cd /var/log/nginx            # Enseñar a zoxide esta ruta

# Más tarde, saltar con coincidencias parciales
z myapp                      # Salta a ~/projects/myapp
z reports                    # Salta a ~/documents/reports
z nginx                      # Salta a /var/log/nginx

# Múltiples palabras clave afinan la coincidencia
z proj myapp                 # Coincide con ~/projects/myapp específicamente
z doc rep                    # Coincide con ~/documents/reports

Sintaxis de Consulta

Reglas de Coincidencia

Comando	Descripción
`z proj`	Coincidir con cualquier directorio que contenga “proj”
`z proj rust`	Coincidir con directorio que contenga “proj” y “rust”
`z /home/user/docs`	Usar ruta absoluta directamente
`z docs/`	Coincidir y preferir subdirectorio llamado “docs”
Las palabras clave coinciden con componentes de ruta	”proj” coincide con `/home/user/projects`
La última palabra clave puede coincidir con prefijo	`z pr` coincide con `projects`
Múltiples palabras clave se combinan con AND	Todas deben aparecer en la ruta
La coincidencia no distingue mayúsculas	`z PROJ` coincide con `projects`

Algoritmo de Frecuencia

Concepto	Descripción
Frecuencia = Frecuencia + Recencia	Puntuación basada en cuán frecuente y recientemente se visitó
Las visitas recientes puntúan más alto	Directorios visitados hoy puntúan más que los de la semana pasada
Los directorios frecuentemente visitados se clasifican más alto	El uso regular aumenta la puntuación con el tiempo
Las puntuaciones decaen con el tiempo	Los directorios sin usar pierden clasificación gradualmente
La base de datos auto-elimina puntuaciones bajas	Las entradas antiguas sin usar se eliminan automáticamente
Máximo de entradas controlado por `_ZO_MAXAGE`	Por defecto: 10,000 entradas

Selección Interactiva

Comando	Descripción
`zi`	Abrir fzf con todos los directorios rastreados
`zi query`	Abrir fzf prefiltrado por consulta
`↑ / ↓` en fzf	Navegar resultados
`Enter` en fzf	Seleccionar y saltar al directorio
`Escape` en fzf	Cancelar selección
Escribir en fzf para filtrar	Refinar resultados adicionales
Requiere `fzf` instalado	Instalar fzf para el modo interactivo
`Tab` en fzf	Alternar selección (modo multi-selección)

Ejemplo Interactivo

# Abrir el buscador difuso interactivo con todos los directorios rastreados
zi

# Prefiltrar a directorios que contengan "project"
zi project

# El formato de salida en fzf muestra puntuaciones:
#   3.50   /home/user/projects/myapp
#   2.10   /home/user/projects/api
#   1.20   /var/www/project-site

Integración con el Shell

Reemplazar cd

Comando	Descripción
`eval "$(zoxide init bash --cmd cd)"`	Reemplazar cd con zoxide en Bash
`eval "$(zoxide init zsh --cmd cd)"`	Reemplazar cd con zoxide en Zsh
`--cmd cd` reemplaza el comando `cd`	Hace que cd use zoxide (cd, cdi)
`--cmd j` crea `j` y `ji`	Usar nombres de comando personalizados
Por defecto crea `z` y `zi`	Comandos estándar de zoxide

Configuración de Hook

Comando	Descripción
`--hook pwd`	Actualizar base de datos al cambiar de directorio (por defecto)
`--hook prompt`	Actualizar base de datos en cada prompt
`--hook none`	Desactivar rastreo automático

Integración con Otras Herramientas

# Reemplazar cd en Bash con zoxide
eval "$(zoxide init bash --cmd cd)"
# Ahora 'cd' usa zoxide, 'cdi' abre el modo interactivo

# Usar nombre de comando personalizado
eval "$(zoxide init zsh --cmd j)"
# Ahora 'j foo' salta, 'ji' abre el modo interactivo

# Combinar con fzf para una experiencia mejorada
export _ZO_FZF_OPTS="--height 40% --reverse --border"

Gestión de la Base de Datos

Consultar Base de Datos

Comando	Descripción
`zoxide query foo`	Mostrar mejor coincidencia sin saltar
`zoxide query foo --list`	Listar todas las coincidencias con puntuaciones
`zoxide query foo --score`	Mostrar coincidencias con puntuaciones de frecuencia
`zoxide query --all`	Listar toda la base de datos
`zoxide query --all --score`	Listar base de datos con puntuaciones
`zoxide query --exclude /path`	Excluir ruta específica de los resultados
`zoxide query --list \| head -20`	Top 20 directorios

Gestionar Entradas

Comando	Descripción
`zoxide add /path/to/dir`	Agregar directorio manualmente a la base de datos
`zoxide remove /path/to/dir`	Eliminar directorio de la base de datos
`zoxide edit`	Abrir base de datos en $EDITOR (interactivo)
Base de datos almacenada en `$_ZO_DATA_DIR/db.zo`	Ubicación por defecto de la base de datos

Ejemplos de Base de Datos

# Verificar qué coincidiría zoxide
zoxide query project --list --score
# Salida:
#    12.00  /home/user/projects/webapp
#     8.50  /home/user/projects/api
#     3.20  /home/user/old-project

# Alimentar manualmente la base de datos para máquinas nuevas
zoxide add ~/projects/webapp
zoxide add ~/projects/api
zoxide add ~/.config/nvim

# Eliminar entradas obsoletas (directorios eliminados)
zoxide query --all | while read -r dir; do
  [ -d "$dir" ] || zoxide remove "$dir"
done

# Exportar base de datos para respaldo
zoxide query --all --score > zoxide-backup.txt

Importar Desde Otras Herramientas

Comando	Descripción
`zoxide import --from z path/to/.z`	Importar desde base de datos de z.sh
`zoxide import --from autojump path/to/autojump.txt`	Importar desde base de datos de autojump
`zoxide import --merge --from z path/to/.z`	Importar fusionando (mantener entradas existentes)
`zoxide import --from z --merge ~/.z`	Importación común de z.sh

Ejemplos de Migración

# Migrar desde z.sh (más común)
zoxide import --from z ~/.z

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

# Fusionar con base de datos existente (no sobrescribir)
zoxide import --merge --from z ~/.z

# Después de importar, verificar
zoxide query --all --score | head -20

Variables de Entorno

Comando	Descripción
`export _ZO_DATA_DIR="$HOME/.local/share/zoxide"`	Establecer directorio de la base de datos
`export _ZO_ECHO=1`	Imprimir directorio coincidente antes de saltar
`export _ZO_EXCLUDE_DIRS="/tmp/:/private/"`	Excluir directorios del rastreo
`export _ZO_FZF_OPTS="--height 40%"`	Opciones personalizadas de fzf para zi
`export _ZO_MAXAGE=10000`	Establecer máximo de entradas en la base de datos
`export _ZO_RESOLVE_SYMLINKS=1`	Resolver enlaces simbólicos antes de almacenar

Ejemplo de Configuración

# ~/.bashrc o ~/.zshrc — configuración completa de zoxide

# Establecer directorio de datos personalizado
export _ZO_DATA_DIR="$HOME/.local/share/zoxide"

# Imprimir el directorio coincidente antes de saltar
export _ZO_ECHO=1

# Excluir directorios temporales y del sistema
export _ZO_EXCLUDE_DIRS="$HOME:$HOME/Downloads:/tmp/*:/private/*"

# Personalizar apariencia de fzf para el modo interactivo
export _ZO_FZF_OPTS="
  --height 40%
  --layout reverse
  --border rounded
  --preview 'ls -la {2..}'
  --preview-window right:40%
"

# Máximo de entradas antes de podar (por defecto: 10000)
export _ZO_MAXAGE=10000

# Resolver enlaces simbólicos a rutas canónicas
export _ZO_RESOLVE_SYMLINKS=1

# Inicializar zoxide (debe ser DESPUÉS de los exports)
eval "$(zoxide init zsh)"

Completado y Soporte de Tab

Comando	Descripción
`z <Tab>`	Autocompletar desde directorios rastreados
`z foo<Tab>`	Completar directorios coincidentes
Completado de Bash mediante `zoxide init`	Automático con la inicialización del shell
Completado de Zsh mediante `zoxide init`	Automático con la inicialización del shell
Completado de Fish mediante `zoxide init`	Automático con la inicialización del shell

Mejores Prácticas

Deja que zoxide aprenda naturalmente — Usa tu shell normalmente y zoxide construirá su base de datos a partir de tus hábitos. No intentes alimentar manualmente cada directorio.
Usa dos palabras clave para precisión — Cuando múltiples directorios coinciden, agrega una segunda palabra clave: z proj api es más preciso que z api solo.
Usa barra final para subdirectorios — z foo/ prefiere subdirectorios del directorio actual llamados “foo”, mientras que z foo busca en toda la base de datos.
Reemplaza cd para máximo aprendizaje — Usa --cmd cd en la inicialización de tu shell para que cada cambio de directorio alimente a zoxide, no solo cuando recuerdes usar z.
Configura exclusiones temprano — Establece _ZO_EXCLUDE_DIRS para omitir directorios temporales, carpetas de compilación y rutas de node_modules que contaminan los resultados.
Usa zi para saltos ambiguos — Cuando no estés seguro de qué directorio coincidirá, usa zi (interactivo) para previsualizar y seleccionar entre candidatos.
Migra datos existentes — Si cambias desde z.sh, autojump o fasd, importa tu base de datos con zoxide import para comenzar con una caché precargada.
Limpia entradas obsoletas — Periódicamente elimina entradas de directorios borrados usando zoxide edit o un script de limpieza para mantener los resultados relevantes.
Respalda tu base de datos — Exporta con zoxide query --all --score antes de reinstalaciones del SO o migraciones de máquina.
Personaliza la apariencia de fzf — Establece _ZO_FZF_OPTS con --preview 'ls {2..}' para mostrar el contenido del directorio en el selector interactivo.