Config locali dell'IDE. BACKLOG.md. Appunti di lavoro. Una cartella scratch/ con esperimenti e test che non vuoi perdere. .claude/ con i prompt dell'assistente AI. docker-compose.override.yml per il tuo ambiente di sviluppo locale.

Tutti li hanno. Non tutti li vogliono/possono versionare.

E quando li perdi (un rm -rf di troppo, un cambio di macchina, un collega che clona il progetto e non trova più nulla) ti accorgi che quei file erano più importanti di quanto pensavi.

Le soluzioni artigianali non mancano:

• Cartella Dropbox a fianco del repo. Funziona finché ti ricordi di usarla.
• Gist sparsi. Impossibili da tenere sincronizzati.
• Branch dedicato. Inquina la storia del progetto.
• Repo separato gestito a mano. Funziona per un progetto. Non per venti.

Il problema è sempre lo stesso: quei file vivono accanto al tuo codice, ma Git non li vuole. E le alternative non hanno il rigore che Git ti dà gratuitamente: storia, diff, remote, branch.

L'esigenza

Solexma aveva bisogno di uno strumento per gestire file di contesto (appunti, backlog, configurazioni locali, scratch) su decine di repository, senza inquinare i repo dei clienti e senza dipendere da soluzioni artigianali.

Il requisito era chiaro: versionamento reale, Git-native, ma completamente invisibile al repository principale. Niente submodule, niente branch orfani, niente file di configurazione nel repo del cliente.

Ho sviluppato git-side per risolvere esattamente questo problema.

Come funziona

Un bare repository separato, invisibile al repo principale, dedicato esclusivamente ai file "a lato" del progetto. Zero inquinamento: il repo principale non sa nemmeno che git-side esiste.

Il side repo vive fuori dalla directory del progetto, in una posizione standard di sistema (che è ovviamente differente tra MacOS e Linux).

Ogni progetto ha il suo, identificato in modo univoco dallo SHA del primo commit: un'identità immutabile, stabile tra clone, indipendente dal path del filesystem o dal remote URL.

Nella pratica:

# Traccia un file
git side add BACKLOG.md

# Traccia un'intera directory (tutto il contenuto, ricorsivamente)
git side add scratch/

# Commit manuale
git side commit -m "Aggiunto backlog e appunti"

# Oppure: auto-sync che usa il messaggio dell'ultimo commit
git side auto

# Installa un hook post-commit per sincronizzare automaticamente
git side hook install

Il workflow più comune dopo il setup iniziale: non devi fare nulla. L'hook post-commit si occupa di tutto. Ogni volta che fai commit nel repo principale, il side repo si sincronizza in automatico.

Per condividere i file "a lato" tra macchine o con colleghi:

git side remote add origin [email protected]:user/project-side.git
git side push    # force push: il locale vince sempre
git side pull    # fetch + reset: il remoto vince sempre

Scelte di design

Ogni decisione in git-side è stata deliberata. Alcune sono opinionate.

Force push/pull senza merge. Non c'è risoluzione di conflitti. Push = il locale vince, sempre. Pull = il remoto vince, sempre. Per file "a lato" (appunti, config locali, scratch) la complessità del merge non ha senso. La semplicità qui è una feature, non una limitazione.

Bypass delle ignore rules. git side add usa internamente git add -f. Non è un workaround: i file tracciati da git-side sono per definizione in .gitignore. "Ignorato dal repo principale" non significa "non versionabile". Sono due concetti distinti.

Shell-out a git binary. Niente libgit2, niente binding nativi. git-side chiama direttamente il git installato sulla macchina. Questo garantisce comportamento identico a quello che l'utente conosce, zero dipendenze native, build più semplice.

Self-versioning della lista tracciata. Il file .side-tracked, la lista di cosa è tracciato, vive dentro il side repo stesso, versionato tramite git plumbing (hash-object + update-index). Quando fai push, la lista viaggia con i file. Chi fa pull sa esattamente cosa tracciare.

Non è per i segreti. File come .env, API key, token, credenziali non vanno committati da nessuna parte. Per quelli serve un secrets manager.

Ogni decisione è documentata in dettaglio nei relativi Architecture Decision Record.

Primi risultati

git-side è stato testato su oltre 150 repository nelle prime 48 ore dal rilascio, da utenti interni Solexma, da me direttamente e da utenti esterni.

Il tool è scritto in Rust, distribuito come singolo binario, e rilasciato open-source.

Codice sorgente: github.com/Solexma/git-side

Se anche tu hai file che vivono ai margini del tuo progetto (appunti, config, esperimenti) e ogni volta che li perdi pensi "avrei dovuto versionarli"... prova git-side.

È esattamente per quello che l'ho costruito.