git stash: un solo file senza perdere il resto

Arriva una code review mentre tre file sono a metà modifica e solo uno di loro può muoversi. Fare stash di tutto e ritrivare gli altri due è il rituale che nessuno rimpiange.

TL;DR: git stash push -m "perché" -- <percorso> fa stash esattamente dei percorsi indicati e lascia in pace il resto dell’albero sporco. Riprendi le modifiche con git stash pop (o tira fuori un singolo file da qualsiasi stash con git restore --source stash@{0} -- <percorso>). La forma con pathspec è arrivata con git 2.13, uscito a maggio 2017 — qualsiasi toolchain degli ultimi otto anni ce l’ha.

git stash push -m "app.conf prod tweak" -- app.conf
git stash list
# stash@{0}: On main: app.conf prod tweak
git stash pop

Stash del file, non dell’albero.

Come faccio stash di un solo file in git?

Un git stash semplice spazza tutto l’albero di lavoro — ogni modifica tracciata finisce nello stash e tutto torna a HEAD. È la forma sbagliata quando l’albero sporco è misto: un file è pronto da consegnare, il resto è onestamente incompleto. La soluzione è il verbo push con un pathspec, secondo la documentazione di git-stash:

# prima: tre file sporchi
$ git status --short
 M app.conf
 M notes.md
 M main.py

# stash di solo app.conf
$ git stash push -m "app.conf prod tweak" -- app.conf
Saved working directory and index state On main: app.conf prod tweak

$ git status --short
 M notes.md
 M main.py

app.conf torna allo stato committato e finisce in stash@{0}; notes.md e main.py non si sono mai mossi. Il messaggio -m è opzionale ma vale i tre secondi che costa nel momento in cui git stash list mostra più di una voce — gli stash battezzati «WIP» invecchiano male.

Due dettagli che contano:

• Il pathspec viene dopo --. Tutto ciò che segue il doppio trattino è un percorso, non una flag. È la stessa convenzione di git checkout -- <percorso> e non è decorativa: git stash push -- main.py e git stash push main.py differiscono nelle versioni più vecchie, dove un percorso nudo poteva essere frainteso.
• I file non tracciati vogliono -u. Un file appena creato non ha storico tracciato da stashare, quindi un push semplice lo salta. git stash push -u -- newfile.py lo include; -a va oltre e spazza anche gli ignorati.

Come faccio stash di parte di un solo file?

Quando il file stesso è a metà — tre hunk buoni, uno imbarazzante — il flusso interattivo lo affetta:

git stash -p            # oppure: git stash push -p

Git scorre ogni hunk e chiede Stash this hunk [y,n,q,a,d,j,g,/,e,p,?]?. Rispondi y per gli hunk che vanno nello stash, n per quelli che restano. Il risultato è uno stash con solo l’approvato, e il resto del file resta sporco nell’albero. La stessa meccanica hunk per hunk muove git add -p, quindi il riflesso si trasferisce.

	git stash push -- <percorso>	git stash -p
Granularità	file interi	hunk singoli
Velocità	un comando, scriptabile	interattivo, hunk per hunk
Ripetibile in CI	sì (percorsi come argomenti)	no — serve un umano al prompt
Ideale per	«questo file, non il resto»	«questa modifica, non quell’altra»
Dal	git 2.13 (maggio 2017)	disponibile da sempre

Regola pratica dal modello stesso della documentazione: pathspec quando il confine è il file, -p quando sta dentro.

Come recupero un file in stash?

git stash pop ripristina stash@{0} ed elimina la voce. È la strada normale — ma il pop è tutto-o-niente per stash, e un conflitto lo interrompe lasciando la voce al suo posto. Due opzioni più fini:

# 1. applicare senza eliminare (rilanciabile senza rischi)
git stash apply stash@{0}

# 2. tirare fuori UN file da uno stash, voce intatta
git restore --source stash@{0} -- app.conf
# grafia precedente alla 2.23 della stessa operazione:
git checkout stash@{0} -- app.conf

La forma restore/checkout risponde al caso «stashati tre cambi insieme, ora mi serve solo uno» — copia il contenuto stashato di quel percorso nell’albero e lascia stash@{0} in piedi. Attenzione: sovrascrive la copia nell’albero di lavoro; se le modifiche attuali su quel percorso contano, prima confronta:

git diff stash@{0} -- app.conf

Gli stash sono conservati come commit veri su una pila simile al reflog, per questo stash@{0} accetta qualsiasi sintassi commit-ish — e per questo uno stash cancellato per errore è recuperabile dal reflog finché il garbage collector non lo mangia.

Quando lo stash è lo strumento sbagliato?

Uno stash è una scrittura, non un branch: nessun nome in git branch, nessuna review, nessun diff mostrato di default, e voci che si impilano in silenzio fino all’oblio. Se il lavoro in corso deve sopravvivere a cambi di contesto tra macchine o giorni, committalo su un branch — lo storico allegato vale più di una pila senza nome. Quando quei commit parcheggiati dovranno atterrare altrove, il git cherry-pick li trasporta. E quando l’obiettivo è annullare più che parcheggiare, vale l’albero decisionale di git undo last commit.

Il registro onesto delle modalità di guasto, tutte dal comportamento documentato:

Sintomo	Causa	Rimedio
File assente dopo lo stash	percorsi non tracciati saltati	git stash push -u -- <percorso>
error: Your local changes ... would be overwritten sul pop	il percorso è cambiato dopo lo stash	commit o stash del nuovo stato, poi pop
Modifiche recuperate sparite	il pop ha incontrato un conflitto e si è interrotto	risolvi, poi git stash apply
«Quale stash era?»	pila di stash senza nome	messaggi con -m, sempre

La nota di rilascio di maggio 2017 che ha aggiunto il pathspec a git stash push compie otto anni, e gran parte della memoria muscolare di git stash è anteriore. Merita un riapprendimento: la spazzata dell’intero albero oggi è il caso speciale, non il default.