SXXXXXXX_GitUtility/doc/Manuale.md

(Italiano)

Manuale Utente: Git Sync Tool

1. Introduzione

Benvenuto in Git Sync Tool! Questa applicazione è progettata per semplificare la gestione dei tuoi repository Git, con un focus particolare sulla sincronizzazione tramite file bundle (ideale per ambienti offline o con restrizioni di rete) e sull'interazione con repository remoti (come Gitea, GitHub, GitLab, ecc.). Permette inoltre di gestire operazioni Git comuni come commit, branch, tag e visualizzare la cronologia e le modifiche.

Questo manuale ti guiderà attraverso le funzionalità principali e alcuni scenari di utilizzo tipici.

2. Primi Passi: I Profili

L'applicazione utilizza Profili per memorizzare le impostazioni specifiche per ciascun repository che gestisci (percorsi, nomi dei bundle, configurazioni remote, ecc.).

• Selezione: All'avvio, l'applicazione carica il profilo default o il primo profilo disponibile. Usa il menu a tendina in alto per selezionare un profilo esistente. Il caricamento delle impostazioni è automatico.
• Aggiunta: Usa il pulsante Add New per creare un nuovo profilo. Ti verrà chiesto un nome. Le impostazioni di default verranno popolate, dovrai poi configurare almeno il "Working Directory Path".
• Clonazione: Usa il pulsante Clone from Remote per clonare un repository esistente da un URL remoto in una nuova directory locale e creare automaticamente un profilo associato.
• Salvataggio: Dopo aver modificato i percorsi o le impostazioni di un profilo, clicca Save Profile per memorizzare le modifiche nel file di configurazione (git_svn_sync.ini).
• Rimozione: Seleziona un profilo (diverso da default) e clicca Remove per eliminarlo (ti verrà chiesta conferma).

3. Panoramica dell'Interfaccia

L'interfaccia è organizzata in diverse sezioni:

1. Barra Profilo (In Alto): Seleziona, salva, aggiungi, clona o rimuovi profili di configurazione.
2. Schede Principali (Notebook): Contengono le funzionalità raggruppate per argomento (Repository, Remote, Backup, Commit, Tags, Branches, History).
3. Area Log (In Basso): Mostra messaggi dettagliati sulle operazioni eseguite, errori e avvisi. Utile per il debug e per capire cosa sta succedendo.
4. Barra di Stato (In Fondo): Mostra brevi messaggi sullo stato corrente dell'applicazione (Ready, Processing, Error, Successo, ecc.).

4. Funzionalità per Scheda (Tab)

4.1. Tab "Repository / Bundle"

Questa scheda gestisce i percorsi fondamentali e le operazioni di creazione/utilizzo dei file bundle.

• Working Directory Path: Il percorso assoluto alla cartella principale del tuo repository Git locale (quella che contiene la sottocartella .git).
  • Indicatore Stato (Pallino): Verde indica che il percorso è valido e contiene un repository Git inizializzato. Rosso indica che non lo è.
  • Browse...: Apre una finestra per selezionare la cartella.
• Bundle Target Directory: La cartella dove verranno creati o da dove verranno letti i file bundle (es. una chiavetta USB o una cartella di rete condivisa).
  • Browse...: Apre una finestra per selezionare la cartella.
• Create Bundle Filename: Nome del file bundle da creare (es. mio_repo.bundle).
• Fetch Bundle Filename: Nome del file bundle da cui leggere le modifiche (es. aggiornamento_remoto.bundle).
• Prepare Repository: (Abilitato solo se il Working Directory è valido ma non è ancora un repo Git). Inizializza un nuovo repository Git (git init) e si assicura che la cartella .svn (se presente) sia aggiunta al file .gitignore.
• Create Bundle: Crea un file bundle (.bundle) contenente l'intera cronologia e tutti i riferimenti (branch, tag) del repository locale. Salva il file nella "Bundle Target Directory" con il nome specificato in "Create Bundle Filename". Utile per trasferire l'intero stato del repo. Include opzioni per backup e autocommit prima della creazione (vedi tab Backup e Commit).
• Fetch from Bundle: Legge un file bundle (specificato in "Fetch Bundle Filename" e cercato nella "Bundle Target Directory") e applica le modifiche contenute al repository locale.
  • Se il "Working Directory Path" non esiste o è una cartella vuota, clona il contenuto del bundle in quella directory.
  • Se il "Working Directory Path" è già un repository Git, esegue un git fetch dal bundle e poi tenta un git merge per integrare le modifiche. Potrebbero verificarsi conflitti di merge. Include opzione per backup prima del fetch (vedi tab Backup).
• Edit .gitignore: Apre un editor di testo modale per modificare direttamente il file .gitignore del repository. Salvando le modifiche, verrà automaticamente avviato un controllo per rimuovere dall'indice i file che ora dovrebbero essere ignorati.

4.2. Tab "Remote Repository"

Questa scheda gestisce l'interazione con repository Git remoti (es. Gitea, GitHub).

• Remote URL: L'indirizzo HTTPS o SSH del repository remoto.
• Local Name: L'alias locale per questo remoto (standard: origin).
• Apply Config: Aggiunge o aggiorna la configurazione del remoto nel file .git/config locale con l'URL e il nome specificati.
• Check Connection: Verifica se il remoto è raggiungibile e se l'autenticazione (se necessaria) è valida, senza trasferire dati. Aggiorna l'indicatore di stato.
  • Indicatore Stato Auth/Conn: Mostra lo stato della connessione/autenticazione (Unknown, Checking, Connected, Auth Required, Failed, Error).
• Sync Status Label: Mostra lo stato di sincronizzazione del branch locale corrente rispetto al suo upstream remoto (es. "Up to date", "X commits ahead", "Y commits behind", "Upstream not set", "Detached HEAD").
• Refresh Sync Status: Ricalcola e aggiorna lo stato Ahead/Behind.
• Fetch: Scarica gli oggetti e i riferimenti (commit, branch, tag) dal repository remoto senza integrare le modifiche nel tuo branch locale. Aggiorna i remote-tracking branches (es. origin/master).
• Pull: Esegue un fetch e poi tenta di integrare (merge) le modifiche del branch remoto tracciato nel tuo branch locale corrente. Può causare conflitti di merge.
• Push: Carica i commit del tuo branch locale corrente sul branch corrispondente nel repository remoto. La prima volta, imposta automaticamente il tracking (--set-upstream).
• Push Tags: Carica tutti i tag locali sul repository remoto.
• Liste Branch (Affiancate):
  • Remote Branches: Mostra i branch presenti sul remoto (come visti dall'ultimo fetch). Click destro per azioni (Compare, Checkout as local).
  • Local Branches: Mostra i branch locali. Click destro per azioni (Checkout, Merge into current, Delete, Force Delete, Compare).
  • Refresh Remote/Local List: Pulsanti per aggiornare le rispettive liste.

4.3. Tab "Backup Settings"

Configura le opzioni per i backup automatici e manuali.

• Enable Auto Backup: Se spuntato, crea automaticamente un backup ZIP del "Working Directory" prima di eseguire le azioni "Create Bundle" e "Fetch from Bundle".
• Backup Directory: La cartella dove verranno salvati i file ZIP di backup (automatici o manuali).
  • Browse...: Seleziona la cartella.
• Exclude File Exts: Elenco separato da virgole di estensioni file da escludere dal backup (es. .log,.tmp,.obj).
• Exclude Dirs (Name): Elenco separato da virgole di nomi di cartelle da escludere dal backup (es. __pycache__,build,node_modules). .git e .svn sono sempre esclusi.
• Backup Now (ZIP): Crea immediatamente un backup ZIP del "Working Directory" nella "Backup Directory" specificata, usando le esclusioni definite.

4.4. Tab "Commit / Changes"

Gestisce la preparazione (staging) e l'esecuzione dei commit locali.

• Enable Autocommit: Se spuntato, tenta automaticamente un commit di tutte le modifiche presenti nel Working Directory prima dell'azione "Create Bundle". Usa il messaggio nel campo sottostante.
• Commit Message: Area di testo multilinea per scrivere il messaggio del commit manuale o dell'autocommit.
• Working Directory Changes:
  • Lista File: Mostra i file che sono stati modificati, aggiunti (untracked ??) o cancellati rispetto all'ultimo commit (git status).
  • Click Destro:
    • Add to Staging Area: (Abilitato solo per file untracked ??) Esegue git add sul file selezionato.
    • View Changes (Diff): Apre una finestra che mostra le differenze tra la versione nel Working Directory e quella nell'ultimo commit (HEAD). Non disponibile per file ??, !!, D.
  • Refresh List: Aggiorna la lista dei file modificati.
• Commit Staged Changes: Esegue git add . (per aggiungere tutte le modifiche attuali, inclusi i file nuovi se non untracked) e poi git commit usando il messaggio fornito.

4.5. Tab "Tags"

Gestisce i tag Git (etichette per commit specifici).

• Existing Tags: Lista dei tag presenti nel repository, ordinati per data di creazione (più recenti prima). Mostra nome e messaggio (se annotato).
• Refresh Tags: Aggiorna la lista dei tag.
• Create New Tag...: Apre una finestra di dialogo per inserire nome e messaggio per un nuovo tag annotato. Crea il tag puntando al commit corrente.
• Checkout Selected Tag: Passa allo stato "Detached HEAD" posizionandosi sul commit associato al tag selezionato. Utile per ispezionare una vecchia versione, ma attenzione: i nuovi commit fatti qui non apparterranno a nessun branch.

4.6. Tab "Branches (Local Ops)"

Gestisce i branch locali del repository.

• Local Branches: Lista dei branch locali. Il branch corrente è marcato con *.
  • Click Destro:
    • Checkout Branch: Passa al branch selezionato.
    • Merge '{branch}' into current '{current}': Integra le modifiche dal branch selezionato nel branch attualmente attivo. Può causare conflitti. (Abilitato solo se si seleziona un branch diverso da quello corrente).
    • Delete Branch: Cancella il branch locale selezionato (chiede conferma). Fallisce se il branch ha modifiche non ancora unite (merged) in altri branch.
    • Force Delete Branch: Cancella il branch locale selezionato anche se ha modifiche non unite (attenzione: potenzialmente pericoloso).
    • Compare '{branch}' with current '{current}': Apre una vista che mostra i file differenti tra il branch selezionato e quello corrente.
• Refresh Branches: Aggiorna la lista dei branch locali.
• Create New Branch...: Apre una finestra di dialogo per inserire il nome di un nuovo branch locale, che verrà creato a partire dal commit corrente.
• Checkout Selected Branch: Passa al branch selezionato nella lista.

4.7. Tab "History"

Visualizza la cronologia dei commit del repository.

• Filter History by Branch/Tag: Menu a tendina per mostrare la cronologia solo per un branch o tag specifico, o per tutti (-- All History --).
• Refresh History: Ricarica la cronologia in base al filtro selezionato.
• Lista History (Treeview): Mostra i commit (hash breve, data/ora, autore, messaggio/riferimenti). I commit più recenti sono in cima.
  • Doppio Click: Apre una finestra di dettaglio per il commit selezionato, mostrando metadati completi e la lista dei file modificati in quel commit. Da lì è possibile visualizzare il diff di ogni singolo file rispetto al commit genitore.

4.8. Area Log & Barra di Stato

• Application Log: Area di testo scorrevole che mostra messaggi dettagliati su tutte le operazioni, errori, avvisi e informazioni di debug. I messaggi sono scritti anche sul file git_svn_sync.log.
• Status Bar: Riga in fondo alla finestra che mostra messaggi concisi sullo stato corrente ("Ready.", "Processing...", "Error...", "Successo"). Può cambiare colore per evidenziare stati (giallo per processing, verde per successo, rosso per errore).

5. Casi d'Uso Comuni (Workflow)

5.1. Scenario: Iniziare a Usare un Progetto Esistente (Non ancora Git)

Obiettivo: Mettere un progetto esistente (es. da SVN o solo file) sotto controllo Git e configurare un profilo nell'applicazione.

Passaggi:

1. Apri Git Sync Tool.
2. Clicca Add New nella barra profilo. Inserisci un nome per il profilo (es. MioProgetto) e clicca OK.
3. Il nuovo profilo viene selezionato.
4. Nella tab Repository / Bundle, clicca Browse... accanto a "Working Directory Path" e seleziona la cartella principale del tuo progetto.
5. Clicca Save Profile.
6. Se la cartella non è un repository Git, l'indicatore sarà rosso. Clicca Prepare Repository. L'indicatore dovrebbe diventare verde.
7. (Opzionale) Clicca Edit .gitignore per aggiungere regole specifiche del tuo progetto (es. file temporanei, build output). Salva e chiudi l'editor. L'applicazione controllerà se ci sono file da rimuovere dal tracciamento.
8. Vai alla tab Commit / Changes. Clicca Refresh List. Dovresti vedere tutti i file del progetto come "Untracked" (??).
9. Scrivi un messaggio di commit iniziale (es. "Initial project import") nel campo "Commit Message".
10. Clicca Commit Staged Changes. Questo aggiungerà tutti i file e creerà il primo commit.
11. Il tuo repository locale è pronto.

5.2. Scenario: Flusso di Lavoro Locale Standard

Obiettivo: Apportare modifiche, visualizzarle e creare un commit.

Passaggi:

1. Seleziona il profilo corretto. Assicurati che l'indicatore del Working Directory sia verde.
2. Modifica i file del tuo progetto usando i tuoi editor esterni.
3. Vai alla tab Commit / Changes.
4. Clicca Refresh List. La lista "Working Directory Changes" mostrerà i file modificati (M), aggiunti (A se hai usato git add da fuori o dal menu contestuale), cancellati (D), o untracked (??).
5. (Opzionale) Se hai file untracked (??) che vuoi includere nel commit, selezionali e usa Click Destro -> Add to Staging Area. Poi clicca di nuovo Refresh List.
6. (Opzionale) Se vuoi vedere le modifiche specifiche a un file, fai doppio click sul file nella lista per aprire il Diff Viewer. Chiudi il viewer al termine.
7. Scrivi un messaggio di commit descrittivo nell'area "Commit Message".
8. Clicca Commit Staged Changes.
9. Le modifiche sono ora registrate nella cronologia Git locale. Puoi vederlo aggiornando la tab History.

5.3. Scenario: Sincronizzazione Offline Tramite Bundle

Obiettivo: Trasferire le modifiche tra due computer (PC-A e PC-B) senza una connessione di rete diretta, usando un supporto rimovibile (es. USB).

Passaggi (su PC-A):

1. Lavora sul progetto su PC-A (vedi Scenario 5.2). Assicurati che tutte le modifiche desiderate siano state committate.
2. Seleziona il profilo del progetto.
3. Vai alla tab Repository / Bundle.
4. Imposta il "Bundle Target Directory" sul percorso della tua chiavetta USB (o altra cartella condivisa).
5. Imposta un nome significativo in "Create Bundle Filename" (es. progetto_update_20250428.bundle).
6. (Opzionale ma consigliato) Vai alla tab Backup Settings, abilita "Enable Auto Backup" e configura la "Backup Directory" (su PC-A) per sicurezza.
7. Clicca Save Profile.
8. Torna alla tab Repository / Bundle e clicca Create Bundle. Attendi il completamento.
9. Trasferisci fisicamente la chiavetta USB (o accedi alla cartella condivisa) da PC-B.

Passaggi (su PC-B):

1. Avvia Git Sync Tool e seleziona (o crea/configura) il profilo per lo stesso progetto su PC-B. Il "Working Directory Path" deve puntare alla copia locale del progetto su PC-B.
2. Vai alla tab Repository / Bundle.
3. Imposta il "Bundle Target Directory" sul percorso della chiavetta USB (o cartella condivisa).
4. Imposta il nome del file ricevuto da PC-A in "Fetch Bundle Filename".
5. (Opzionale ma consigliato) Configura il backup nella tab Backup Settings per PC-B.
6. Clicca Save Profile.
7. Torna alla tab Repository / Bundle e clicca Fetch from Bundle.
   • Se il repository non esisteva su PC-B, verrà clonato dal bundle.
   • Se esisteva, le modifiche verranno integrate (potrebbero esserci conflitti se anche su PC-B sono state fatte modifiche non sincronizzate).
8. Ora PC-B ha ricevuto le modifiche da PC-A. Puoi riprendere il ciclo trasferendo un bundle da B ad A.

5.4. Scenario: Primo Push su un Repository Remoto (es. Gitea)

Obiettivo: Caricare per la prima volta un repository locale esistente su un server remoto (es. Gitea) dove è stato creato un progetto vuoto.

Passaggi:

1. Assicurati di avere un repository locale pronto (vedi Scenario 5.1).
2. Crea un progetto vuoto sul tuo server Gitea (o GitHub/GitLab). Copia l'URL (HTTPS o SSH) fornito.
3. Apri Git Sync Tool e seleziona il profilo del tuo repository locale.
4. Vai alla tab Remote Repository.
5. Incolla l'URL copiato da Gitea nel campo Remote URL.
6. Lascia o inserisci origin nel campo Local Name.
7. Clicca Apply Config. Verifica i log o la status bar per conferma.
8. (Consigliato) Clicca Check Connection. Verifica l'indicatore di stato e risolvi eventuali problemi di autenticazione se richiesto.
9. Vai alla tab Branches (Local Ops) e assicurati di aver fatto checkout del branch principale (es. master o main) che contiene la cronologia che vuoi caricare. L'asterisco * deve essere accanto a quel branch.
10. Torna alla tab Remote Repository.
11. Clicca Push. L'applicazione dovrebbe rilevare che è il primo push e usare l'opzione --set-upstream. Potrebbe chiederti le credenziali.
12. Attendi il completamento. Verifica il repository su Gitea nel browser.

5.5. Scenario: Flusso di Lavoro Standard con Repository Remoto

Obiettivo: Mantenere sincronizzato il lavoro locale con un repository remoto.

Passaggi:

1. Seleziona il profilo corretto. Assicurati che il remoto sia configurato.
2. Prima di iniziare a lavorare: Vai alla tab Remote Repository e clicca Pull (o prima Fetch e poi risolvi eventuali differenze prima del merge/pull). Questo scarica le modifiche fatte da altri (o da te su un altro PC) e le integra localmente. Risolvi eventuali conflitti di merge se si presentano.
3. Lavora localmente: Modifica file, esegui commit (vedi Scenario 5.2).
4. Quando pronto per condividere: Vai alla tab Remote Repository.
5. (Opzionale) Clicca Fetch e poi Refresh Sync Status per vedere se ci sono nuove modifiche remote prima di pushare. Se ci sono modifiche remote (behind > 0), fai Pull e integra prima di procedere.
6. Clicca Push per caricare i tuoi commit locali sul remoto.

5.6. Scenario: Gestione Branch

Obiettivo: Creare un branch per una nuova funzionalità, lavorarci, e poi unirlo al branch principale.

Passaggi:

1. Seleziona il profilo e assicurati di essere sul branch principale (es. master).
2. Vai alla tab Branches (Local Ops).
3. Clicca Create New Branch.... Inserisci un nome (es. feature/nuova-idea) e clicca OK.
4. Il nuovo branch viene creato ma non sei ancora passato ad esso. Seleziona il nuovo branch nella lista.
5. Clicca Checkout Selected Branch. Ora stai lavorando sul nuovo branch.
6. Lavora sulla funzionalità: modifica file, esegui commit (Scenario 5.2) sul branch feature/nuova-idea.
7. Quando la funzionalità è completa:
   • Assicurati che tutte le modifiche sul branch feature/nuova-idea siano committate.
   • Seleziona il branch principale (es. master) nella lista.
   • Clicca Checkout Selected Branch per tornare al principale.
   • (Opzionale ma consigliato) Fai Pull sul branch principale per assicurarti di avere le ultime modifiche remote.
   • Seleziona il branch feature/nuova-idea nella lista.
   • Fai Click Destro su feature/nuova-idea e scegli Merge 'feature/nuova-idea' into current 'master'. Conferma.
   • Risolvi eventuali conflitti di merge, poi esegui un commit dalla tab "Commit / Changes".
8. La funzionalità è ora integrata nel branch principale.
9. (Opzionale) Se non ti serve più il branch feature/nuova-idea: selezionalo, fai Click Destro e scegli Delete Branch 'feature/nuova-idea'. Conferma.
10. (Opzionale) Fai Push del branch principale per caricare le modifiche unite sul remoto.

5.7. Scenario: Creare e Usare un Tag

Obiettivo: Marcare una versione specifica del software (es. un rilascio).

Passaggi:

1. Assicurati che il commit che vuoi taggare sia quello corrente (fai checkout del branch/commit appropriato).
2. Assicurati che non ci siano modifiche locali non committate.
3. Vai alla tab Tags.
4. Clicca Create New Tag....
5. Inserisci un nome per il tag (standard comune: vX.Y.Z, es. v1.0.0) e un messaggio descrittivo (es. "Rilascio versione 1.0.0"). Clicca OK.
6. Il tag è creato localmente.
7. (Opzionale) Per condividere il tag, vai alla tab Remote Repository e clicca Push Tags.
8. (Opzionale) Per tornare a vedere lo stato del codice al momento del tag, selezionalo nella lista della tab Tags e clicca Checkout Selected Tag (ricorda che entrerai in "Detached HEAD").

5.8. Scenario: Visualizzare Modifiche

Obiettivo: Capire cosa è cambiato tra versioni diverse o in un commit specifico.

Passaggi:

• Modifiche Locali (vs Ultimo Commit):
  1. Vai alla tab Commit / Changes.
  2. Clicca Refresh List.
  3. Fai doppio click su un file modificato (M) per aprire il Diff Viewer.
• Modifiche in un Commit Specifico (vs Genitore):
  1. Vai alla tab History.
  2. Fai doppio click sul commit desiderato.
  3. Si apre la finestra Commit Details.
  4. Fai doppio click su un file nella lista "Changed Files" per aprire il Diff Viewer che mostra le modifiche introdotte da quel commit per quel file.
• Modifiche tra Branch/Tag/Commit Diversi:
  1. Assicurati di essere sul branch che vuoi usare come base di confronto (es. master).
  2. Vai alla tab Branches (Local Ops) o Remote Repository.
  3. Fai Click Destro sul branch/tag (locale o remoto) con cui vuoi confrontare.
  4. Scegli Compare '{altro_ref}' with current '{tuo_branch}'.
  5. Si apre la finestra Differences Summary che elenca i file diversi.
  6. Fai doppio click su un file in quella finestra per aprire il Diff Viewer con il confronto tra i due riferimenti scelti.