Zoxide

Comando cd piu intelligente che impara le tue abitudini usando un algoritmo di frequenza per una navigazione rapida delle directory tra le shell.

Installazione

Gestori di Pacchetti

Comando	Descrizione
`brew install zoxide`	Installa su macOS con Homebrew
`cargo install zoxide --locked`	Installa da crates.io
`apt install zoxide`	Installa su Debian/Ubuntu
`pacman -S zoxide`	Installa su Arch Linux
`dnf install zoxide`	Installa su Fedora
`scoop install zoxide`	Installa su Windows con Scoop
`winget install ajeetdsouza.zoxide`	Installa su Windows con winget
`nix-env -i zoxide`	Installa su NixOS
`conda install -c conda-forge zoxide`	Installa con Conda
`curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh \| sh`	Installa tramite script shell

Inizializzazione della Shell

Comando	Descrizione
`eval "$(zoxide init bash)"`	Inizializza per Bash (aggiungi a .bashrc)
`eval "$(zoxide init zsh)"`	Inizializza per Zsh (aggiungi a .zshrc)
`zoxide init fish \| source`	Inizializza per Fish (aggiungi a config.fish)
`Invoke-Expression (& { (zoxide init powershell) })`	Inizializza per PowerShell
`zoxide init nushell \| save -f ~/.zoxide.nu`	Inizializza per Nushell
`eval "$(zoxide init elvish)"`	Inizializza per Elvish
`eval (zoxide init xonsh)`	Inizializza per Xonsh

Esempi di Configurazione Shell

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

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

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

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

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

Uso Base

Navigazione

Comando	Descrizione
`z foo`	Vai alla directory con il punteggio piu alto che corrisponde a “foo”
`z foo bar`	Vai alla directory che corrisponde sia a “foo” che a “bar”
`z ~/projects`	Vai al percorso esatto (come cd)
`z ..`	Vai alla directory padre
`z -`	Vai alla directory precedente
`z`	Vai alla directory home (senza argomenti)
`zi`	Selezione interattiva con fzf
`zi foo`	Selezione interattiva pre-filtrata per “foo”
`z foo/`	Vai alla sottodirectory (barra finale)

Esempi di Utilizzo

# Dopo aver visitato le directory, zoxide le impara
cd ~/projects/myapp          # Insegna a zoxide questo percorso
cd ~/documents/reports       # Insegna a zoxide questo percorso
cd /var/log/nginx            # Insegna a zoxide questo percorso

# Successivamente, salta con corrispondenze parziali
z myapp                      # Salta a ~/projects/myapp
z reports                    # Salta a ~/documents/reports
z nginx                      # Salta a /var/log/nginx

# Parole chiave multiple restringono la corrispondenza
z proj myapp                 # Corrisponde a ~/projects/myapp specificamente
z doc rep                    # Corrisponde a ~/documents/reports

Sintassi delle Query

Regole di Corrispondenza

Comando	Descrizione
`z proj`	Corrisponde a qualsiasi directory contenente “proj”
`z proj rust`	Corrisponde a directory contenente sia “proj” che “rust”
`z /home/user/docs`	Usa percorso assoluto direttamente
`z docs/`	Corrisponde e preferisce sottodirectory chiamata “docs”
Le parole chiave corrispondono ai componenti del percorso	”proj” corrisponde a `/home/user/projects`
L’ultima parola chiave puo corrispondere al prefisso	`z pr` corrisponde a `projects`
Le parole chiave multiple sono in AND	Tutte devono apparire nel percorso
La corrispondenza ignora maiuscole/minuscole	`z PROJ` corrisponde a `projects`

Algoritmo di Frequenza

Concetto	Descrizione
Frequenza = Frequenza + Recenza	Punteggio basato su quanto spesso e di recente visitato
Le visite recenti hanno punteggio piu alto	Directory visitate oggi hanno punteggio maggiore di quelle della scorsa settimana
Le directory visitate frequentemente hanno ranking piu alto	L’uso regolare aumenta il punteggio nel tempo
I punteggi decadono nel tempo	Le directory inutilizzate perdono gradualmente ranking
Il database rimuove automaticamente i punteggi bassi	Le voci vecchie e inutilizzate vengono rimosse automaticamente
Voci massime controllate da `_ZO_MAXAGE`	Predefinito: 10.000 voci

Selezione Interattiva

Comando	Descrizione
`zi`	Apri fzf con tutte le directory tracciate
`zi query`	Apri fzf pre-filtrato per query
`↑ / ↓` in fzf	Naviga i risultati
`Enter` in fzf	Seleziona e vai alla directory
`Escape` in fzf	Annulla selezione
Digita in fzf per filtrare	Restringi ulteriormente i risultati
Richiede `fzf` installato	Installa fzf per la modalita interattiva
`Tab` in fzf	Attiva/disattiva selezione (modalita multi-selezione)

Esempio Interattivo

# Apri il finder fuzzy interattivo con tutte le directory tracciate
zi

# Pre-filtra alle directory contenenti "project"
zi project

# Il formato di output in fzf mostra i punteggi:
#   3.50   /home/user/projects/myapp
#   2.10   /home/user/projects/api
#   1.20   /var/www/project-site

Integrazione con la Shell

Sostituire cd

Comando	Descrizione
`eval "$(zoxide init bash --cmd cd)"`	Sostituisci cd con zoxide in Bash
`eval "$(zoxide init zsh --cmd cd)"`	Sostituisci cd con zoxide in Zsh
`--cmd cd` sostituisce il comando `cd`	Fa usare zoxide a cd (cd, cdi)
`--cmd j` crea `j` e `ji`	Usa nomi di comandi personalizzati
Predefinito crea `z` e `zi`	Comandi standard di zoxide

Configurazione Hook

Comando	Descrizione
`--hook pwd`	Aggiorna database al cambio di directory (predefinito)
`--hook prompt`	Aggiorna database ad ogni prompt
`--hook none`	Disabilita il tracciamento automatico

Integrazione con Altri Strumenti

# Sostituisci cd in Bash con zoxide
eval "$(zoxide init bash --cmd cd)"
# Ora 'cd' usa zoxide, 'cdi' apre la modalita interattiva

# Usa nome comando personalizzato
eval "$(zoxide init zsh --cmd j)"
# Ora 'j foo' salta, 'ji' apre la modalita interattiva

# Combina con fzf per un'esperienza migliorata
export _ZO_FZF_OPTS="--height 40% --reverse --border"

Gestione Database

Interrogare il Database

Comando	Descrizione
`zoxide query foo`	Mostra la migliore corrispondenza senza saltare
`zoxide query foo --list`	Elenca tutte le corrispondenze con punteggi
`zoxide query foo --score`	Mostra corrispondenze con punteggi di frequenza
`zoxide query --all`	Elenca l’intero database
`zoxide query --all --score`	Elenca il database con punteggi
`zoxide query --exclude /path`	Escludi percorso specifico dai risultati
`zoxide query --list \| head -20`	Le 20 directory principali

Gestire le Voci

Comando	Descrizione
`zoxide add /path/to/dir`	Aggiungi manualmente una directory al database
`zoxide remove /path/to/dir`	Rimuovi una directory dal database
`zoxide edit`	Apri il database in $EDITOR (interattivo)
Database salvato in `$_ZO_DATA_DIR/db.zo`	Posizione predefinita del database

Esempi Database

# Controlla cosa corrisponderebbe zoxide
zoxide query project --list --score
# Output:
#    12.00  /home/user/projects/webapp
#     8.50  /home/user/projects/api
#     3.20  /home/user/old-project

# Popola manualmente il database per nuove macchine
zoxide add ~/projects/webapp
zoxide add ~/projects/api
zoxide add ~/.config/nvim

# Rimuovi voci obsolete (directory eliminate)
zoxide query --all | while read -r dir; do
  [ -d "$dir" ] || zoxide remove "$dir"
done

# Esporta il database per backup
zoxide query --all --score > zoxide-backup.txt

Importa da Altri Strumenti

Comando	Descrizione
`zoxide import --from z path/to/.z`	Importa dal database di z.sh
`zoxide import --from autojump path/to/autojump.txt`	Importa dal database di autojump
`zoxide import --merge --from z path/to/.z`	Importa con merge (mantieni voci esistenti)
`zoxide import --from z --merge ~/.z`	Importazione comune da z.sh

Esempi di Migrazione

# Migra da z.sh (piu comune)
zoxide import --from z ~/.z

# Migra da autojump
zoxide import --from autojump ~/.local/share/autojump/autojump.txt

# Unisci con database esistente (non sovrascrivere)
zoxide import --merge --from z ~/.z

# Dopo l'importazione, verifica
zoxide query --all --score | head -20

Variabili d’Ambiente

Comando	Descrizione
`export _ZO_DATA_DIR="$HOME/.local/share/zoxide"`	Imposta la directory del database
`export _ZO_ECHO=1`	Stampa la directory corrispondente prima di saltare
`export _ZO_EXCLUDE_DIRS="/tmp/:/private/"`	Escludi directory dal tracciamento
`export _ZO_FZF_OPTS="--height 40%"`	Opzioni fzf personalizzate per zi
`export _ZO_MAXAGE=10000`	Imposta il massimo di voci nel database
`export _ZO_RESOLVE_SYMLINKS=1`	Risolvi i symlink prima di salvare

Esempio di Configurazione

# ~/.bashrc o ~/.zshrc — configurazione completa di zoxide

# Imposta directory dati personalizzata
export _ZO_DATA_DIR="$HOME/.local/share/zoxide"

# Stampa la directory corrispondente prima di saltare
export _ZO_ECHO=1

# Escludi directory temporanee e di sistema
export _ZO_EXCLUDE_DIRS="$HOME:$HOME/Downloads:/tmp/*:/private/*"

# Personalizza l'aspetto di fzf per la modalita interattiva
export _ZO_FZF_OPTS="
  --height 40%
  --layout reverse
  --border rounded
  --preview 'ls -la {2..}'
  --preview-window right:40%
"

# Voci massime prima della pulizia (predefinito: 10000)
export _ZO_MAXAGE=10000

# Risolvi symlink in percorsi canonici
export _ZO_RESOLVE_SYMLINKS=1

# Inizializza zoxide (deve essere DOPO le export)
eval "$(zoxide init zsh)"

Completamenti e Supporto Tab

Comando	Descrizione
`z <Tab>`	Autocompletamento dalle directory tracciate
`z foo<Tab>`	Completa directory corrispondenti
Completamento Bash tramite `zoxide init`	Automatico con init della shell
Completamento Zsh tramite `zoxide init`	Automatico con init della shell
Completamento Fish tramite `zoxide init`	Automatico con init della shell

Buone Pratiche

Lascia che zoxide impari naturalmente — Usa la tua shell normalmente e zoxide costruira il suo database dalle tue abitudini. Non cercare di popolare manualmente ogni directory.
Usa due parole chiave per precisione — Quando piu directory corrispondono, aggiungi una seconda parola chiave: z proj api e piu preciso di z api da solo.
Usa la barra finale per le sottodirectory — z foo/ preferisce le sottodirectory della directory corrente chiamate “foo”, mentre z foo cerca nell’intero database.
Sostituisci cd per il massimo apprendimento — Usa --cmd cd nell’init della shell cosi ogni cambio di directory alimenta zoxide, non solo quando ti ricordi di usare z.
Configura le esclusioni in anticipo — Imposta _ZO_EXCLUDE_DIRS per saltare directory temporanee, cartelle di build e percorsi node_modules che inquinano i risultati.
Usa zi per salti ambigui — Quando non sei sicuro quale directory corrispondera, usa zi (interattivo) per visualizzare in anteprima e selezionare tra i candidati.
Migra i dati esistenti — Se passi da z.sh, autojump o fasd, importa il database con zoxide import per iniziare con una cache gia popolata.
Pulisci le voci obsolete — Rimuovi periodicamente le voci per directory eliminate usando zoxide edit o uno script di pulizia per mantenere i risultati rilevanti.
Fai backup del tuo database — Esporta con zoxide query --all --score prima di reinstallazioni del sistema operativo o migrazioni di macchine.
Personalizza l’aspetto di fzf — Imposta _ZO_FZF_OPTS con --preview 'ls {2..}' per mostrare il contenuto della directory nel selettore interattivo.