#howto - Navi: cheatsheet per il terminale

Chi lavora molto spesso sul terminale è conscio del fatto che alcuni comandi hanno un’importanza e un’utilità maggiore di altri.

Navi consente di memorizzare (e addirittura parametrizzare) questi comandi in file speciali, chiamati cheatsheets, che in un secondo momento possono essere cercati ed eseguiti.

Navi ingloba le principali funzioni di tldr e cheat.sh.

Requisiti

Per utilizzare Navi, è necessario installare uno strumento di “fuzzy finding”, come fzf o skim.

Sono entrambi tool che consentono di filtrare l’output di altri comandi in modalità “fuzzy”, in modo da trovare tutte le righe corrispondenti ad un determinato pattern, anche omettendo alcuni caratteri nel mezzo.

Nel caso di fzf, l’installazione per le principali piattaforme è la seguente:

Installare Fzf su Ubuntu

apt install fzf

Installare Fzf su Fedora

dnf install fzf

Installare Fzf su Arch Linux

pacman -S fzf

Installare Fzf su Mac OS

brew install fzf

Installazione Navi

Installare navi su Ubuntu

Nel caso di Ubuntu, non è disponibile alcun pacchetto pronto per l’installazione (tutt’al più esistono i binari precompilati ufficiali per le piattaforme più utilizzate).

In alternativa, per compilare il codice da sorgente, le istruzioni ufficiali sono le seguenti:

git clone https://github.com/denisidoro/navi ~/.navi
cd ~/.navi
make install

Al termine dell’installazione (o del download del software precompilato), è possibile spostare manualmente l’eseguibile in una delle cartelle del proprio $PATH (affinché si possa eseguire navi globalmente, a prescindere dalla cartella in cui ci si trovi).

In alternativa al semplice make install, è consigliato specificare anzitempo la cartella di installazione dell’eseguibile impostando la variabile BIN_DIR:

make BIN_DIR=/usr/local/bin install

Installare navi su Fedora

dnf install navi

Installare navi su Arch Linux

pacman -S navi

Installare navi su via Cargo

cargo install --locked navi

Installare navi su Mac OS

brew install navi

Cheatsheets

Consultare i cheatsheet

Una volta installato navi, è possibile consultare cheatsheet semplicemente avviando l’eseguibile (senza alcun altro parametro) e digitando del testo.

Si aprirà un’interfaccia testuale (fornita da uno tra fzf o skim), in cui si può navigare usando le frecce direzionali e si può filtrare l’elenco a schermo digitando dei caratteri.

La ricerca segue le regole del fuzzy finding, identica sia nel caso di fzf che di skim.

Premendo Enter, viene confermata la selezione attuale.

Tuttavia, all’inizio non c’è un’ampia gamma di suggerimenti da consultare: è necessario scaricarne di nuovi.

Avviare navi usando l’argomento –print consente una consultazione in modalità di “sola lettura”, prevenendo eventuali esecuzioni accidentali.

Scaricare cheatsheet già pronti

Per scaricare una prima selezione di cheatsheet, quella principale, basterà usare lo stesso navi (o navi fn welcome) e scegliere la voce corrispondente al comando navi repo add denisidoro/cheats.

Ci sono molti altri repository di cheatsheet installabili interattivamente da navi, selezionando la voce relativa al comando navi repo browse.

Per installare nuovi cheatsheet, che non sono in elenco ma che sono caricati su una repository git, è sufficiente usare navi repo add <URL>, dove URL può anche essere nel formato utente/repository nel caso specifico di una repository GitHub.

Nota bene:

i cheatsheet non vengono aggiornati automaticamente da Navi.

Creare un proprio cheatsheet

Anziché salvare nuovi comandi, nuove funzioni e nuovi alias nel proprio .bashrc, .zshrc e simili, è possibile memorizzarli in file di configurazione per Navi (da posizionare in ~/.local/share/navi/cheats sotto l’estensione .cheat).

Si consideri, ad esempio, la pipeline mostrata all’inizio:

ps aux | awk '{print $3, $11}' | sort -nr -k 2 | tail -n +2 | head -5  # I 5 processi che stanno usando più CPU.

Questo comando può essere trasportato in Navi (ad esempio in ~/.local/share/navi/cheats/processi.cheat), parametrizzandolo così che il numero di processi selezionati non sia 5, ma liberamente selezionabile (uno dei vantaggi di Navi rispetto a strumenti simili):

; Le righe che iniziano per punto e virgola (;) sono ignorate da Navi e corrispondono a dei commenti.

; Le righe che iniziano per percentuale (%) indicano le categorie (separate da virgola) del cheatsheet (Navi le mostra sulla sinistra).
% ps, cpu

; Le righe che cominciano per cancelletto (#) sono la descrizione del comando che segue.
# Elenca gli N processi che stanno usando più CPU.
; I parametri racchiusi tra i segni di minore e maggiore (< >) sono variabili, che se non specificate (vedi righe successive) sono chieste in input all'utente.
ps aux | awk '{print $3, $11}' | sort -nr -k 2 | tail -n +2 | head -<N>

; Le righe che iniziano con il segno di dollaro ($) indicano la definizione di variabili (inclusa una selezione di valori multipli da selezionare).
$ N: tr ' ' '\n' <<< '3 5 10'
; La riga precedente è completamente opzionale in questo caso: quando rimossa, l'utente è libero di inserire un qualsiasi valore in input.

Su GitHub è disponibile la pagina di riferimento per conoscere la sintassi completa, comprese le funzionalità più avanzate come i comandi multilinea e l’aliasing.

Come widget della shell

Anziché digitare ogni volta navi, potrebbe essere più utile assegnare l’esecuzione del comando a una scorciatoia da tastiera.

Navi fornisce nativamente l’integrazione per tutte le principali shell.

Bash

eval "$(navi widget bash)"

Zsh

eval "$(navi widget zsh)"

Fish

navi widget fish | source

I comandi sopra elencati possono essere sia invocati manualmente dopo aver aperto il terminale (con lo svantaggio che i cambiamenti non restano alla chiusura), sia possono essere salvati nei file di configurazione della propria shell (come .bashrc, .zshrc e simili).

La scorciatoia assegnata di default è CTRL+G e non può essere cambiata (se non modificando manualmente lo script che va poi invocato da eval).

Come alternativa a TLDR e Cheat.sh

Come precedentemente accennato, Navi può essere utilizzato anche come frontend per tldr e cheat.sh, a cui abbiamo dedicato degli articoli in passato.

Sia tldr che cheat.sh sono valide alternative e si completano a vincenda, con delle piccole ma importanti differenze:

• tldr, che va installato, fa affidamento a un database locale che bisogna aggiornare periodicamente.
• cheat.sh è consultabile online su cheat.sh, con lo svantaggio di non poter essere consultato senza internet.

Per usare tldr su git in Navi:

navi --tldr git

Attenzione:

non tutti i client di tldr supportano il parametro –markdown (che in alcuni casi è stato sostituito da –raw). Per questo motivo, Navi potrebbe non funzionare anche nel caso in cui tldr sia installato correttamente.

Per usare cheat.sh su git in Navi:

navi --cheatsh git

Ulteriori informazioni

Il codice sorgente di Navi è disponibile sulla pagina GitHub ufficiale.