Versionamento (Git semplificato)

Git, GitHub e il cloud

Git è locale. È un programma gratuito che gira sul tuo computer e conserva la cronologia delle versioni nella cartella stessa, nella cartella nascosta .git. Attivare il versionamento non invia nulla su internet e non richiede alcun account: le versioni restano solo su questa macchina — e se il disco si guasta o il computer va perso, se ne vanno con lui.

GitHub è un'altra cosa: un servizio nel cloud che conserva una copia del repository. È a GitHub, o a un servizio simile, che LightNote invia le versioni quando sincronizzi. Con quella copia altrove ottieni un backup e puoi usare le stesse note su un altro computer: da uno invii, sull'altro ricevi. GitHub è gratuito per uso personale, con repository privati illimitati che vedi solo tu.

In breve: Git sono le versioni, sul tuo computer; il remoto ne è una copia altrove — GitHub, un altro servizio, una cartella di OneDrive o di Google Drive, o un server tuo. Finché la cartella non ha un remoto, il pannello di versionamento mostra Versioni solo su questo computer. e offre il link Esegui backup e sincronizza…, spiegato sotto.

Clonare un repository

Per lavorare su un repository che esiste già, usa File → Clona repository Git...: la voce è anche nella schermata iniziale e nel pannello di versionamento di una cartella che non è ancora un repository. Incolla l'indirizzo HTTPS o SSH che la pagina del repository mostra; va bene anche l'URL della pagina stessa, e pure un git clone ... copiato per intero. Scegli la cartella base e il nome della cartella: l'assistente mostra dove nascerà e avvisa quando lì c'è già qualcosa. In Opzioni avanzate ci sono il branch, il clone superficiale (solo l'ultimo commit) e i sottomoduli.

Quando il server chiede l'accesso, LightNote lo chiede in una finestra: utente e token, la passphrase della chiave SSH, oppure la conferma della chiave di un server che questo computer non ha mai visto — in quel caso la finestra mostra l'impronta digitale e il link all'elenco che il servizio pubblica, e l'impostazione predefinita è non fidarsi. La risposta va direttamente a Git e LightNote non la conserva; a conservarla è il gestore delle credenziali di Git, quando è installato (Git for Windows include il Git Credential Manager). Fidarsi della chiave la scrive in ~/.ssh/known_hosts, come farebbe ssh stesso.

Se la clonazione non riesce, la schermata dice che cosa è successo e offre la via d'uscita: provare con HTTPS quando la chiave SSH è stata rifiutata, usare i certificati di Windows quando il proxy aziendale ispeziona HTTPS, scaricare solo l'ultimo commit quando la connessione cade a metà, oppure usare i percorsi lunghi quando Windows non lascia creare il file. I Dettagli tecnici riportano il messaggio di Git, e ciò che non viene riconosciuto può andare all'IA. Alla fine l'assistente apre la cartella clonata in questa finestra o in una nuova.

Versionare la cartella aperta

Il versionamento è opt-in per ogni spazio di lavoro. Abilitalo in Strumenti → Spazio di lavoro → Configurazione dello spazio di lavoro...: LightNote crea il repository Git (se non ne esiste ancora uno) e mostra la barra laterale di versionamento (Ctrl+Shift+G).

In modalità automatica, LightNote salva le versioni (commit) da solo nei momenti scelti nelle Impostazioni generali (al salvataggio, alla chiusura della scheda o alla chiusura della finestra). Durante la sessione, nel commit entra solo ciò che LightNote ha scritto — ciò che una CLI di IA o un altro programma ha cambiato resta in sospeso, perché chi l'ha cambiato faccia il proprio commit; Ctrl+S salva subito la versione, e ciò che scrive il salvataggio automatico entra in un commit ogni 10 minuti. Alla chiusura della finestra (attivo per impostazione predefinita), il commit prende tutto ciò che è cambiato nella cartella, anche fuori da LightNote: è la rete di sicurezza di fine sessione. In modalità manuale, scrivi il messaggio e salvi la versione nel pannello. L'indicatore della barra di stato mostra lo stato (nessuna modifica, X modificati…) e, se cliccato, apre il menu Git (vedi sotto); in una cartella non ancora versionata apre le impostazioni dello spazio di lavoro su Integrazioni. Puoi visualizzare il diff di ogni file e ripristinare (scartare) le modifiche non salvate.

L'automazione ha 3 livelli per cartella (in Configurazione dello spazio di lavoro): Manuale (nulla di automatico), Commit automatico (salva le versioni da solo, ma non sincronizza) e Completamente automatico (fa commit e sincronizza — push dopo il commit + pull periodico; richiede credenziali Git senza richiesta di password). Il pannello mostra una riga di stato con ↑ da inviare / ↓ da ricevere rispetto al remoto, e il pulsante principale passa da commit a Sincronizza quando ci sono versioni da inviare — rendendo chiaro che, dopo aver salvato, devi ancora sincronizzare.

Il pannello Git e il menu Git dell'albero offrono Aggiungi (git add) e Ripristina (git restore) per file, e un unico Vedi cosa è cambiato, che apre la schermata di confronto. L'elenco del pannello segue l'ordine naturale dei percorsi, e il menu contestuale di un file offre anche Copia... e Mostra in Esplora file (disattivato per un file eliminato).

La schermata di confronto mostra le due versioni affiancate e allineate: i passaggi uguali stanno sempre uno di fronte all'altro e ogni lato mostra il numero di riga del proprio file. Una riga cambiata appare in ambra, con la parte modificata evidenziata al suo interno. Il pulsante Modalità unificata passa al formato patch, Inverti i lati cambia la base del confronto e F8 / Shift+F8 saltano da una modifica all'altra.

Il menu Git nella barra di stato. In una cartella versionata, l'indicatore mostra il ramo e, accanto, ciò che resta da sincronizzare (↓ da ricevere, ↑ da inviare); il pallino è verde con tutto salvato in una versione, ambra con modifiche in sospeso e rosso con file in conflitto. Il clic apre un menu che inizia con lo stato completo e offre Salva una versione di tutto (commit)… — prende tutte le modifiche della cartella, anche quelle di altri programmi; con il messaggio vuoto, è automatico —, Apri il pannello Git e, con un repository remoto, Sincronizza (ricevi e invia), Ricevi (pull con merge), Invia (push) e Controlla il remoto (fetch). Ricevi unisce sempre (merge) e non fa mai rebase, qualunque sia la configurazione di Git della macchina; se il merge ha conflitti, l'invio non avviene e il menu offre Annulla il merge con conflitti…. In Azioni automatiche cambi il livello di automazione della cartella senza aprire le impostazioni. In Avanzato, Esegui comando git… esegue qualunque comando nella cartella del repository e ne mostra l'output — senza terminale: un comando che chiede di digitare (editor del messaggio, password nella console) rinuncia invece di aspettare; per quelli, usa il terminale. Se Git non è installato, il clic apre la guida all'installazione.

Spostare e rinominare. Quando sposti o rinomini un file o una cartella in LightNote (trascinando nell’albero, tagliando e incollando, rinominando), la versione porta insieme le due metà e Git registra una rinomina. Entra solo ciò che era già versionato; un file nuovo dentro la cartella spostata aspetta, come gli altri. Vale la stessa regola di Ctrl+S: con il commit al salvataggio disattivato, lo spostamento aspetta il commit successivo. I file grandi restano fuori — vedi File grandi e i limiti dei servizi.

Cronologia e striscia di modifiche

La barra dell'editor di codice e della nota ha due pulsanti per le versioni del file. Salva versione scrive il file e ne conserva questa versione: in una cartella versionata con Git fa un commit solo di questo file — ciò che un altro programma o una sessione di IA ha cambiato negli altri file resta fuori —, e fuori da un repository conserva un punto nella cronologia locale. Diventa grigio, con il motivo nel suggerimento, quando nulla è cambiato dall'ultima versione.

Versioni apre l'elenco delle versioni del file aperto (la stessa sezione della barra laterale), e la sua freccia offre Salva versione con messaggio…, Vedi cosa è cambiato dall'ultima versione e Scarta le modifiche dall'ultima versione…, che riporta il file all'ultima versione, con o senza Git — il testo scartato resta nella cronologia locale, e anche Ctrl+Z lo riporta indietro. L'elenco riunisce i commit e i salvataggi locali: LightNote ne registra uno a ogni Ctrl+S e, con il salvataggio automatico, al massimo uno ogni 10 minuti per file, oltre al file com'era prima della prima scrittura — quindi funziona anche in una cartella che non è un repository. Ogni riga porta l'oggetto, l'autore, quando è avvenuto e quante righe sono entrate e uscite; il pallino distingue un tuo commit, un salvataggio di LightNote stesso e un commit venuto da una sessione di IA. Se ci sono modifiche non ancora nel commit, sono la prima riga. Fare clic su una versione mostra cosa è cambiato in essa; aprire l'intera versione, confrontare con l'attuale e confrontare due versioni selezionate sono nel menu contestuale.

Una striscia colorata nel margine segna le righe cambiate dall'ultima versione — nell'editor di codice e nella nota, e segue ciò che digiti: sparisce quando annulli fino all'originale, senza aspettare un salvataggio. L'ultima versione è l'ultimo commit nel momento in cui hai aperto il file — senza Git, il file com'era all'apertura. Il salvataggio e il commit automatico non la spostano: i segni restano finché non fai clic su Salva versione o chiudi la scheda. Per disattivarla usa Visualizza → Striscia di modifiche; disattivata non è solo nascosta: non viene calcolato nulla. Fare clic sulla striscia mostra com'era il blocco, con Ripristina questo blocco (Ctrl+Z annulla), Copia originale e Vedi nel diff, che apre il confronto completo già posizionato su quella riga. Quando il file aperto cambia fuori da LightNote — una CLI di IA che ci scrive, per esempio —, la scheda senza modifiche in sospeso viene ricaricata in silenzio e la striscia mostra cosa è cambiato; con tue modifiche in altri punti, le due vengono unite (Ctrl+Z annulla); e se entrambe hanno toccato le stesse righe, una barra gialla in cima alla scheda offre Confronta, Tieni quella sul disco e Tieni la mia — finché non scegli, il salvataggio automatico non scrive quel file, e la versione scartata resta nella cronologia locale. Un'avvertenza sulla cronologia locale: è conservata per percorso, quindi rinominare il file perde i suoi salvataggi locali — i commit di Git no.

Autore della riga e cambio di branch

Chi ha scritto questa riga. Nel menu Git della barra di stato, Autore della riga (blame) mette, alla fine della riga del cursore, chi l'ha scritta, quando e il riepilogo della versione — per esempio Ana · 3 giorni fa · corregge il totale. Viene annotata solo la riga del cursore, e l'annotazione segue il cursore. Una riga che non è ancora entrata in nessuna versione dice Non versionato; con modifiche non salvate, l'annotazione chiede Salva per vedere l'autore, perché le righe del file su disco non corrispondono più a quelle sullo schermo.

Cambiare branch. Lo stesso menu ha il sottomenu Branch: main (con il nome del branch attuale), che elenca i branch locali: quello attuale è segnato, e il clic su un altro fa il cambio (git checkout). Crea branch… chiede il nome, lo controlla prima di chiamare Git (niente spazi, niente .., non iniziare con -) e crea il branch a partire da quello attuale, già lavorandoci sopra. Il cambio è disattivato finché c'è un file in conflitto o una sincronizzazione in corso.

Backup e sincronizzazione: GitHub passo per passo

Il link Esegui backup e sincronizza… del pannello — lo stesso di Aggiungi repository remoto…, nel menu ⋯ del pannello e nel menu Git della barra di stato — apre la schermata Backup e sincronizzazione, con tre strade: GitHub, quella consigliata; Altro servizio; e una Cartella sincronizzata (OneDrive, Google Drive, Dropbox, una chiavetta USB o una cartella di rete). Funzionano tutte; GitHub è il modo più semplice per usare le note su più computer e il backup più sicuro. Per GitHub:

1. Crea l'account su github.com/signup: e-mail, password e un nome utente; GitHub invia un codice per confermare l'e-mail. Il piano Free basta.
2. Crea un repository su github.com/new: dagli un nome (per esempio note), scegli Private e non spuntare Add a README, .gitignore né una licenza. Deve nascere vuoto: con un README il primo invio viene rifiutato, perché GitHub avrebbe già una cronologia che non è la tua.
3. Copia l'indirizzo HTTPS mostrato dalla pagina (qualcosa come https://github.com/tu/note.git) e incollalo in Indirizzo del repository, nella schermata di LightNote. Lascia spuntato Invia subito le versioni e fai clic su Connetti.
4. Accedi: al primo invio, Git apre una finestra di GitHub per autorizzare dal browser. Dopo, Windows conserva l'accesso — a conservarlo è il Git Credential Manager, incluso in Git per Windows — e non devi più accedere.
5. Sull'altro computer, installa Git e LightNote e usa File → Clona repository Git... con lo stesso indirizzo. Da lì in poi, Sincronizza riceve ciò che l'altro computer ha inviato e invia ciò che hai fatto qui.

Per non doverti ricordare di sincronizzare, scegli Completamente automatico nelle impostazioni della cartella: LightNote invia dopo ogni commit e riceve di tanto in tanto. Due limiti da conoscere: GitHub rifiuta i file oltre i 100 MB e consiglia repository fino a circa 1 GB — tieni video e file grandi fuori dalla cartella versionata. E privato significa che solo tu (e chi inviti) vedi il repository, ma il contenuto sta sui server di GitHub: per ciò che è riservato, usa il Markdown sicuro, che viene cifrato prima di lasciare il computer.

Sul telefono. Con il remoto collegato, Apri sul telefono… (nel menu ⋯ del pannello e nel menu Git della barra di stato) mostra un codice QR. In LightNote sul telefono, tocca il nome dello spazio di lavoro e scegli Scansiona il codice QR dal computer: il repository diventa un nuovo spazio di lavoro sul telefono. Il QR contiene solo l’indirizzo, mai la password: se il repository è privato, il telefono usa l’account Git che ha per quel server, oppure chiede un token di accesso. Il telefono clona via HTTPS: un remoto che è una cartella di questo computer (OneDrive, sotto) non gli è raggiungibile.

File grandi e i limiti dei servizi

I limiti. GitHub avvisa a partire da 50 MB per file e rifiuta i file oltre 100 MB; anche GitLab, Bitbucket e Azure Repos rifiutano i file oltre 100 MB. Per l’intero repository, GitHub consiglia fino a circa 1 GB (5 GB al massimo), e il piano gratuito di Bitbucket offre 1 GB. Una cartella sincronizzata (OneDrive, Google Drive) non ha questo tetto.

Perché l’attenzione va al commit. Il limite vale per ogni versione della cronologia, non solo per i file di oggi: se un file da 120 MB entra in una versione, l’invio viene rifiutato — e resta rifiutato anche dopo che hai eliminato il file, perché la versione vecchia lo contiene ancora.

Cosa fa LightNote. Un file oltre 100 MB resta fuori da ogni versione che l’app salva — il commit automatico, Ctrl+S, Salva versione, il commit alla chiusura della finestra, lo snapshot e la sincronizzazione del telefono. Resta nella cartella, e un avviso offre Ignora in Git (.gitignore). Oltre 50 MB il file entra, con un avviso nella barra di stato. Un file segnato per Git LFS (che nel repository tiene solo un puntatore) non viene trattenuto.

Se l’invio è già stato rifiutato (la versione è stata salvata fuori da LightNote, in un terminale), il pannello Git lo dice. Eliminare il file non risolve. Se la versione non è ancora stata inviata, esegui reset @{u} in Avanzato → Esegui comando git… del menu Git della barra di stato: le versioni non inviate vengono annullate e i file restano come sono; metti il file grande in .gitignore e salva di nuovo la versione. Per tenere il file nel repository, usa Git LFS (git-lfs.com).

Altri servizi, OneDrive/Google Drive e server personale

Altri servizi. Git funziona allo stesso modo con qualunque servizio; cambia solo il posto in cui crei il repository. I più noti: GitLab (gitlab.com, gratuito, con repository privati fino a 10 GB ciascuno), Bitbucket (bitbucket.org, gratuito fino a 5 utenti, con 1 GB in totale), Azure DevOps (dev.azure.com, di Microsoft, gratuito fino a 5 utenti e con repository privati illimitati) e Codeberg (codeberg.org, senza scopo di lucro, ma solo per progetti open source — non adatto a note private). Crea lì un repository vuoto e privato, copia l'indirizzo e scegli Altro servizio nella schermata Backup e sincronizzazione. I limiti dei piani cambiano nel tempo: verificali sul sito di ciascuno.

OneDrive, Google Drive o Dropbox, senza un nuovo account. Scegli Cartella sincronizzata e indica la cartella del servizio su questo computer (per esempio C:\Users\tu\OneDrive o G:\Il mio Drive). LightNote crea al suo interno un repository bare — una cartella Note.git che contiene solo le versioni, senza i file di lavoro — e lo usa come remoto; il servizio cloud si occupa di copiare quella cartella. Sull'altro computer, aspetta che la cartella risulti sincronizzata e usa File → Clona repository Git..., incollandone il percorso. La stessa opzione va bene per una chiavetta USB o una cartella di rete, come backup.

• Perché un repository bare e non l'intera cartella delle note dentro OneDrive? La cartella .git cambia di continuo mentre lavori, e due computer che la sincronizzano tramite il cloud possono danneggiarla. Nel bare scrive solo l'invio, e ciò che scrive non cambia più dopo.
• Un computer alla volta. Prima di lavorare sull'altro computer, aspetta che OneDrive o Drive abbiano finito di sincronizzare; inviare da entrambi i lati prima di allora può creare copie in conflitto. Se succede spesso, GitHub è la strada più tranquilla.
• Se la cartella di lavoro è già nel cloud — Windows mette spesso la cartella Documenti in OneDrive —, la schermata lo segnala. Su un solo computer OneDrive fa da backup; per usare le note su più computer, preferisci GitHub oppure togli la cartella delle note dal cloud e lasciaci solo il bare.
• Si può anche senza Git: sincronizza l'intera cartella delle note con il servizio cloud e lascia spento il versionamento — la cronologia locale continua a salvare le versioni di ogni file. È la strada di Le tue note sul telefono.

Un server tuo. Per non dipendere da nessuna azienda, puoi ospitare il tuo server Git. Gitea e Forgejo sono leggeri, hanno un'interfaccia web simile a quella di GitHub e girano in Docker — su un computer di casa, un Raspberry Pi, un NAS o un VPS a noleggio. La cosa più semplice di tutte è un server con SSH e un repository creato con git init --bare. Il prezzo è curare il server: installarlo, aggiornarlo e farne il backup; le guide di installazione sono sul sito di ciascun progetto. Con il server pronto, l'indirizzo del repository va in Altro servizio, come qualsiasi altro.