From f90d84934c509b54827658e501c6f9de70e18bbc Mon Sep 17 00:00:00 2001 From: VALLONGOL Date: Mon, 28 Apr 2025 13:06:25 +0200 Subject: [PATCH] update manual in english and italian --- Manuale.md | 290 ++++++++++++++++++++++++++++ manual.md | 548 +++++++++++++++++++++++++---------------------------- 2 files changed, 551 insertions(+), 287 deletions(-) create mode 100644 Manuale.md diff --git a/Manuale.md b/Manuale.md new file mode 100644 index 0000000..f0409ff --- /dev/null +++ b/Manuale.md @@ -0,0 +1,290 @@ +**(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. \ No newline at end of file diff --git a/manual.md b/manual.md index d8d340c..30916cf 100644 --- a/manual.md +++ b/manual.md @@ -1,318 +1,292 @@ -**Manuale Utente: Git SVN Sync Tool** - -**Indice** - -1. [Introduzione](#introduzione) - * [Scopo del Tool](#scopo-del-tool) - * [Funzionalità Principali](#funzionalità-principali) -2. [Prerequisiti](#prerequisiti) -3. [Installazione e Avvio](#installazione-e-avvio) -4. [Concetti Fondamentali](#concetti-fondamentali) - * [Profili di Configurazione](#profili-di-configurazione) - * [Git Bundles](#git-bundles) -5. [Interfaccia Utente (GUI)](#interfaccia-utente-gui) - * [Gestione Profili (Area Superiore)](#gestione-profili-area-superiore) - * [Schede Principali (Notebook)](#schede-principali-notebook) - * [Scheda: Repository / Bundle](#scheda-repository--bundle) - * [Scheda: Backup Settings](#scheda-backup-settings) - * [Scheda: Commit](#scheda-commit) - * [Scheda: Tags](#scheda-tags) - * [Scheda: Branches](#scheda-branches) - * [Scheda: History](#scheda-history) - * [Area Log Applicazione (Inferiore)](#area-log-applicazione-inferiore) -6. [Funzionalità Dettagliate e Flussi di Lavoro](#funzionalità-dettagliate-e-flussi-di-lavoro) - * [Gestione dei Profili](#gestione-dei-profili) - * [Workflow Principale: Sincronizzazione Online/Offline](#workflow-principale-sincronizzazione-onlineoffline) - * [Fase 1: Configurazione Iniziale dei Profili](#fase-1-configurazione-iniziale-dei-profili) - * [Fase 2: Creare il Bundle Iniziale (Macchina Origine)](#fase-2-creare-il-bundle-iniziale-macchina-origine) - * [Fase 3: Clonare dal Bundle (Macchina Destinazione)](#fase-3-clonare-dal-bundle-macchina-destinazione) - * [Fase 4: Lavorare Offline (Macchina Destinazione)](#fase-4-lavorare-offline-macchina-destinazione) - * [Fase 5: Creare Bundle di Aggiornamento (Macchina Destinazione)](#fase-5-creare-bundle-di-aggiornamento-macchina-destinazione) - * [Fase 6: Importare Aggiornamenti (Macchina Origine)](#fase-6-importare-aggiornamenti-macchina-origine) - * [Fase 7: Continuare il Ciclo](#fase-7-continuare-il-ciclo) - * [Backup Manuale](#backup-manuale) - * [Commit Manuale](#commit-manuale) - * [Gestione Tag e Branch](#gestione-tag-e-branch) - * [Modifica di `.gitignore`](#modifica-di-gitignore) -7. [File di Configurazione (`git_svn_sync.ini`)](#file-di-configurazione-git_svn_syncini) -8. [Logging](#logging) -9. [Risoluzione Problemi Comuni](#risoluzione-problemi-comuni) - ---- - -## 1. Introduzione - -### Scopo del Tool - -Il **Git SVN Sync Tool** (nonostante il nome, focalizzato su Git) è un'applicazione desktop progettata per semplificare la gestione e la sincronizzazione di repository Git locali, con un'attenzione particolare agli scenari in cui è necessario trasferire progetti tra computer con e senza accesso a una rete comune (ad esempio, tra una macchina di sviluppo "online" e una macchina "offline"). - -Lo strumento utilizza la funzionalità **Git Bundle** per impacchettare l'intera storia e i file di un repository Git in un singolo file, facilitandone il trasferimento tramite supporti esterni (come chiavette USB). Permette inoltre di eseguire le operazioni inverse, aggiornando un repository locale a partire da un file bundle. +**(English)** -### Funzionalità Principali - -* **Gestione Profili:** Salva e carica configurazioni diverse (percorsi, nomi file, opzioni) per repository o scenari di sincronizzazione distinti. -* **Creazione Bundle Git:** Genera file bundle (`.bundle`) contenenti tutti i riferimenti (branch, tag) e gli oggetti necessari di un repository Git. -* **Fetch da Bundle Git:** Aggiorna un repository Git locale recuperando le modifiche da un file bundle e tentando un merge automatico. -* **Preparazione Repository:** Inizializza un repository Git in una directory (se non già presente) e configura il file `.gitignore` per ignorare le directory `.svn` (retaggio del nome originale del tool). -* **Backup Automatico/Manuale:** Crea automaticamente (se abilitato) o manualmente backup compressi (ZIP) del repository prima di operazioni critiche come la creazione o il fetch di bundle. Include opzioni per escludere file per estensione e intere directory per nome. -* **Commit Automatico/Manuale:** Esegue automaticamente (se abilitato) o manualmente commit delle modifiche locali prima della creazione di un bundle. -* **Gestione Tag/Branch:** Interfaccia grafica per visualizzare, creare ed effettuare il checkout di tag e branch locali. -* **Visualizzazione Cronologia:** Mostra la cronologia dei commit del repository, con possibilità di filtrarla per branch o tag specifici. -* **Editor `.gitignore`:** Permette di modificare facilmente il file `.gitignore` del repository selezionato. -* **Logging Dettagliato:** Registra tutte le operazioni, output dei comandi Git ed eventuali errori sia su un file (`git_svn_sync.log`) sia in un'area dedicata dell'interfaccia grafica. +# User Manual: Git Sync Tool -## 2. Prerequisiti +## 1. Introduction -Prima di utilizzare il tool, assicurati di avere: +Welcome to **Git Sync Tool**! This application is designed to simplify the management of your Git repositories, with a particular focus on synchronization via *bundle* files (ideal for offline environments or those with network restrictions) and interaction with remote repositories (such as Gitea, GitHub, GitLab, etc.). It also allows you to manage common Git operations like commits, branches, tags, and view history and changes. -1. **Python:** Versione 3.x installata sul tuo sistema. -2. **Git:** Git deve essere installato e il suo eseguibile deve essere accessibile dalla riga di comando (ovvero, deve essere presente nella variabile d'ambiente `PATH` del sistema). Il tool invoca comandi `git` esternamente. +This manual will guide you through the main features and some typical usage scenarios. -## 3. Installazione e Avvio +## 2. Getting Started: Profiles -Il tool è uno script Python e non richiede un'installazione complessa. +The application uses **Profiles** to store specific settings for each repository you manage (paths, bundle names, remote configurations, etc.). -1. Assicurati che tutti i file sorgente (`.py`) siano nella stessa directory. -2. Apri un terminale o prompt dei comandi. -3. Naviga fino alla directory contenente gli script. -4. Esegui il comando: - ```bash - python GitUtility.py - ``` -5. L'interfaccia grafica dell'applicazione dovrebbe apparire. +* **Selection:** On startup, the application loads the `default` profile or the first available profile. Use the dropdown menu at the top to select an existing profile. Settings are loaded automatically upon selection. +* **Adding:** Use the **Add New** button to create a new profile. You will be prompted for a name. Default settings will be populated; you will then need to configure at least the "Working Directory Path". +* **Cloning:** Use the **Clone from Remote** button to clone an existing repository from a remote URL into a new local directory and automatically create an associated profile. +* **Saving:** After modifying paths or settings for a profile, click **Save Profile** to store the changes in the configuration file (`git_svn_sync.ini`). +* **Removing:** Select a profile (other than `default`) and click **Remove** to delete it (you will be asked for confirmation). -## 4. Concetti Fondamentali +## 3. Interface Overview -### Profili di Configurazione +The interface is organized into several sections: -Un **Profilo** rappresenta un insieme salvato di impostazioni specifiche per un determinato repository o flusso di lavoro. Ogni profilo contiene: +1. **Profile Bar (Top):** Select, save, add, clone, or remove configuration profiles. +2. **Main Tabs (Notebook):** Contain features grouped by topic (Repository, Remote, Backup, Commit, Tags, Branches, History). +3. **Log Area (Bottom):** Displays detailed messages about operations performed, errors, and warnings. Useful for debugging and understanding what's happening. +4. **Status Bar (Very Bottom):** Shows brief messages about the application's current state (Ready, Processing, Error, Success, etc.). -* Percorsi delle directory (repository locale, directory di destinazione dei bundle). -* Nomi dei file bundle (per la creazione e per il fetch). -* Opzioni (backup automatico, commit automatico, esclusioni backup). -* Messaggio di commit predefinito. +## 4. Features by Tab -L'uso dei profili ti permette di passare rapidamente tra diverse configurazioni senza dover reinserire manualmente tutti i percorsi e le opzioni ogni volta. Esiste un profilo predefinito chiamato `default`. +### 4.1. "Repository / Bundle" Tab -### Git Bundles +This tab manages essential paths and operations for creating/using bundle files. -Un **Git Bundle** è un singolo file (`.bundle`) che contiene oggetti Git (commit, alberi, blob) e riferimenti (nomi di branch e tag). È un modo per trasferire la storia e i dati di un repository Git senza richiedere una connessione di rete diretta tra due repository. +* **Working Directory Path:** The **absolute** path to the main folder of your local Git repository (the one containing the hidden `.git` subfolder). + * **Status Indicator (Dot):** Green indicates the path is valid and contains an initialized Git repository. Red indicates it is not. + * **Browse...:** Opens a dialog to select the folder. +* **Bundle Target Directory:** The folder where bundle files will be created or read from (e.g., a USB drive or a shared network folder). + * **Browse...:** Opens a dialog to select the folder. +* **Create Bundle Filename:** Name of the bundle file to create (e.g., `my_repo.bundle`). +* **Fetch Bundle Filename:** Name of the bundle file to read changes from (e.g., `remote_update.bundle`). +* **Prepare Repository:** (Enabled only if the Working Directory is valid but *not* yet a Git repo). Initializes a new Git repository (`git init`) and ensures the `.svn` folder (if present) is added to the `.gitignore` file. +* **Create Bundle:** Creates a bundle file (`.bundle`) containing the entire history and all references (branches, tags) of the local repository. Saves the file to the "Bundle Target Directory" with the name specified in "Create Bundle Filename". Useful for transferring the entire repo state. Includes options for backup and autocommit before creation (see Backup and Commit tabs). +* **Fetch from Bundle:** Reads a bundle file (specified in "Fetch Bundle Filename" and located in the "Bundle Target Directory") and applies the contained changes to the local repository. + * If the "Working Directory Path" does not exist or is an empty folder, it clones the bundle content into that directory. + * If the "Working Directory Path" is already a Git repository, it performs a `git fetch` from the bundle and then attempts a `git merge` to integrate the changes. Merge conflicts may occur. Includes an option for backup before fetching (see Backup tab). +* **Edit .gitignore:** Opens a modal text editor to directly modify the repository's `.gitignore` file. Saving changes will automatically trigger a check to unstage files that should now be ignored. -* **Creare un Bundle:** Il tool impacchetta il repository corrente (o le sue novità) in un file `.bundle`. Questo file può essere copiato su un supporto esterno. -* **Fetch da Bundle:** Il tool legge un file `.bundle`, importa i suoi contenuti nel repository locale e tenta di integrare (merge) le modifiche nel branch corrente. +### 4.2. "Remote Repository" Tab -## 5. Interfaccia Utente (GUI) +This tab manages interaction with remote Git repositories (e.g., Gitea, GitHub). -L'interfaccia è organizzata con un'area superiore per la gestione dei profili, un'area centrale a schede (Notebook) per le diverse funzionalità e un'area inferiore per i log. +* **Remote URL:** The HTTPS or SSH address of the remote repository. +* **Local Name:** The local alias for this remote (standard: `origin`). +* **Apply Config:** Adds or updates the remote configuration in the local `.git/config` file with the specified URL and name. +* **Check Connection:** Verifies if the remote is reachable and if authentication (if needed) is valid, without transferring data. Updates the status indicator. + * **Auth/Conn Status Indicator:** Shows the connection/authentication status (Unknown, Checking, Connected, Auth Required, Failed, Error). +* **Sync Status Label:** Displays the synchronization status of the current local branch relative to its remote *upstream* (e.g., "Up to date", "X commits ahead", "Y commits behind", "Upstream not set", "Detached HEAD"). +* **Refresh Sync Status:** Recalculates and updates the Ahead/Behind status. +* **Fetch:** Downloads objects and references (commits, branches, tags) from the remote repository without integrating changes into your local branch. Updates *remote-tracking branches* (e.g., `origin/master`). +* **Pull:** Performs a `fetch` and then attempts to integrate (`merge`) changes from the tracked remote branch into your current local branch. May cause merge conflicts. +* **Push:** Uploads commits from your current local branch to the corresponding branch on the remote repository. The first time, it automatically sets up tracking (`--set-upstream`). +* **Push Tags:** Uploads all local tags to the remote repository. +* **Branch Lists (Side-by-Side):** + * **Remote Branches:** Shows branches present on the remote (as seen from the last `fetch`). Right-click for actions (Compare, Checkout as local). + * **Local Branches:** Shows local branches. Right-click for actions (Checkout, Merge into current, Delete, Force Delete, Compare). + * **Refresh Remote/Local List:** Buttons to update the respective lists. -### Gestione Profili (Area Superiore) +### 4.3. "Backup Settings" Tab -* **Select Profile:** Menù a tendina per scegliere il profilo di configurazione attivo. La selezione di un profilo carica automaticamente le impostazioni associate. -* **Save Profile:** Salva le impostazioni correnti visualizzate nella GUI nel profilo attualmente selezionato. **Ricorda di salvare dopo aver modificato i percorsi o le opzioni!** -* **Add New:** Apre una finestra di dialogo per creare un nuovo profilo. Verrà creato con impostazioni predefinite che potrai poi modificare e salvare. -* **Remove:** Rimuove il profilo attualmente selezionato. Non è possibile rimuovere il profilo `default`. +Configures options for automatic and manual backups. -### Schede Principali (Notebook) +* **Enable Auto Backup:** If checked, automatically creates a ZIP backup of the "Working Directory" before performing "Create Bundle" and "Fetch from Bundle" actions. +* **Backup Directory:** The folder where backup ZIP files (automatic or manual) will be saved. + * **Browse...:** Selects the folder. +* **Exclude File Exts:** Comma-separated list of file extensions to exclude from the backup (e.g., `.log,.tmp,.obj`). +* **Exclude Dirs (Name):** Comma-separated list of directory names to exclude from the backup (e.g., `__pycache__,build,node_modules`). `.git` and `.svn` are always excluded. +* **Backup Now (ZIP):** Immediately creates a ZIP backup of the "Working Directory" in the specified "Backup Directory", using the defined exclusions. -#### Scheda: Repository / Bundle +### 4.4. "Commit / Changes" Tab -Questa scheda gestisce i percorsi fondamentali e le azioni principali legate ai bundle. +Manages staging and execution of local commits. -* **SVN Working Copy Path:** **(Nome Storico)** Inserisci qui il percorso completo della directory principale del tuo **repository Git locale**. - * **Browse...:** Pulsante per cercare la cartella. - * **Indicatore di Stato (quadratino colorato):** - * **Rosso:** La directory specificata non è un repository Git valido o preparato. - * **Green:** La directory è un repository Git valido e pronto per le operazioni. -* **Bundle Target Directory:** Inserisci il percorso della directory dove verranno creati o da cui verranno letti i file bundle (es. la root di una chiavetta USB: `E:\`). - * **Browse...:** Pulsante per cercare la cartella. -* **Create Bundle Filename:** Nome del file bundle che verrà creato quando clicchi "Create Bundle" (es. `mio_repo.bundle`). -* **Fetch Bundle Filename:** Nome del file bundle da cui verranno lette le modifiche quando clicchi "Fetch from Bundle" (es. `aggiornamento_repo.bundle`). -* **Prepare Repository:** Pulsante per inizializzare Git nella directory specificata (se non già fatto con `git init`) e assicurarsi che `.svn` sia nel `.gitignore`. Abilitato solo se l'indicatore è rosso. -* **Create Bundle:** Pulsante per creare il file bundle specificato in `Create Bundle Filename` nella `Bundle Target Directory`. Potrebbe eseguire backup e/o autocommit prima, se abilitati. Abilitato solo se l'indicatore è verde. -* **Fetch from Bundle:** Pulsante per leggere il file bundle specificato in `Fetch Bundle Filename` dalla `Bundle Target Directory`, importare le modifiche nel repository locale e tentare un merge. Potrebbe eseguire un backup prima, se abilitato. Abilitato solo se l'indicatore è verde. -* **Edit .gitignore:** Pulsante per aprire una finestra separata dove puoi modificare il file `.gitignore` del repository locale. Abilitato se il percorso del repository è valido. +* **Enable Autocommit:** If checked, automatically attempts to commit all changes in the Working Directory *before* the "Create Bundle" action. Uses the message in the field below. +* **Commit Message:** Multi-line text area for writing the commit message for manual or autocommits. +* **Working Directory Changes:** + * **File List:** Shows files that have been modified, added (untracked `??`), or deleted compared to the last commit (`git status`). + * **Right-Click:** + * **Add to Staging Area:** (Enabled only for untracked `??` files) Executes `git add` on the selected file. + * **View Changes (Diff):** Opens a window showing the differences between the Working Directory version and the last commit (HEAD). Not available for `??`, `!!`, `D` files. + * **Refresh List:** Updates the list of changed files. +* **Commit Staged Changes:** Executes `git add .` (to stage all current changes, including new files if not untracked) and then `git commit` using the provided message. -#### Scheda: Backup Settings +### 4.5. "Tags" Tab -Configura le opzioni di backup automatico e manuale. +Manages Git tags (labels for specific commits). -* **Enable Auto Backup...:** Spunta questa casella per creare automaticamente un backup ZIP del repository prima delle operazioni "Create Bundle" e "Fetch from Bundle". -* **Backup Directory:** Percorso della directory dove verranno salvati i backup ZIP. Abilitato solo se "Enable Auto Backup" è spuntato. - * **Browse...:** Pulsante per cercare la cartella. -* **Exclude File Extensions:** Elenco separato da virgole di estensioni di file da escludere dal backup (es. `.log,.tmp,.bak`). Case-insensitive. -* **Exclude Directories:** Elenco separato da virgole di nomi di directory da escludere dal backup (es. `__pycache__,.venv,node_modules,build`). Verranno escluse le directory con questi nomi a qualsiasi livello. Case-insensitive. `.git` e `.svn` sono sempre esclusi implicitamente. -* **Create Manual Backup Now (ZIP):** Pulsante per eseguire immediatamente un backup ZIP del repository usando le impostazioni di esclusione correnti. Abilitato solo se il percorso del repository è valido. +* **Existing Tags:** List of tags present in the repository, sorted by creation date (newest first). Shows name and message (if annotated). +* **Refresh Tags:** Updates the tag list. +* **Create New Tag...:** Opens a dialog to enter a name and message for a new *annotated tag*. Creates the tag pointing to the current commit. +* **Checkout Selected Tag:** Switches to the "Detached HEAD" state, positioning you at the commit associated with the selected tag. Useful for inspecting an old version, but be aware: new commits made here won't belong to any branch. -#### Scheda: Commit +### 4.6. "Branches (Local Ops)" Tab -Gestisce il commit automatico e manuale. +Manages the repository's local branches. -* **Enable Autocommit...:** Spunta questa casella per tentare un commit automatico di tutte le modifiche locali *prima* dell'operazione "Create Bundle". Utilizzerà il messaggio inserito sotto. Abilitato solo se il repository è pronto (indicatore verde). -* **Commit Message:** Area di testo multilinea dove inserire il messaggio di commit. Usato sia per l'autocommit (se abilitato) sia per il commit manuale. -* **Commit All Changes Manually:** Pulsante per eseguire `git add .` seguito da `git commit -m "messaggio"` usando il messaggio inserito sopra. Abilitato solo se il repository è pronto. - -#### Scheda: Tags - -Visualizza e gestisce i tag Git. - -* **Lista Tag:** Mostra i tag esistenti nel repository (nome e messaggio/subject), ordinati dal più recente al più vecchio. -* **Refresh Tags:** Ricarica l'elenco dei tag dal repository. -* **Create New Tag...:** Apre una finestra di dialogo per inserire nome e messaggio per un nuovo tag annotato. Eseguirà un commit prima, se ci sono modifiche e se è fornito un messaggio nella scheda "Commit". -* **Checkout Selected Tag:** Effettua il checkout del tag selezionato nella lista. **Attenzione:** Questo mette il repository in stato "detached HEAD". Utile per ispezionare lo stato del progetto a un certo tag, ma non per fare nuovi commit direttamente. - -#### Scheda: Branches - -Visualizza e gestisce i branch Git locali. - -* **Lista Branch:** Mostra i branch locali. Il branch corrente è indicato da un asterisco (`*`). -* **Refresh Branches:** Ricarica l'elenco dei branch. -* **Create New Branch...:** Apre una finestra di dialogo per inserire il nome di un nuovo branch da creare a partire dalla posizione corrente (HEAD). -* **Checkout Selected Branch:** Effettua il checkout del branch selezionato nella lista, rendendolo il branch attivo. - -#### Scheda: History - -Visualizza la cronologia dei commit. - -* **Filter History by Branch/Tag:** Menù a tendina per visualizzare la cronologia di tutti i branch/tag (`-- All History --`) o solo quella raggiungibile da un branch o tag specifico. -* **Refresh History:** Ricarica la cronologia dei commit in base al filtro selezionato. -* **Area Testo Cronologia:** Mostra i commit formattati (hash abbreviato, data, autore, riferimenti, messaggio). I commit più recenti sono in alto. - -### Area Log Applicazione (Inferiore) - -Questa area di testo mostra messaggi dettagliati sulle operazioni eseguite dal tool, l'output dei comandi Git, avvisi ed errori. È fondamentale controllarla per capire cosa sta succedendo e per diagnosticare eventuali problemi. - -## 6. Funzionalità Dettagliate e Flussi di Lavoro - -### Gestione dei Profili - -1. **Aggiungere:** Clicca "Add New", inserisci un nome univoco, clicca OK. Il nuovo profilo verrà selezionato. -2. **Configurare:** Compila i percorsi e le opzioni desiderate nelle varie schede. -3. **Salvare:** Clicca "Save Profile" per memorizzare le impostazioni. -4. **Selezionare:** Usa il dropdown "Select Profile" per passare da una configurazione all'altra. -5. **Rimuovere:** Seleziona il profilo da eliminare (non `default`) e clicca "Remove". Conferma l'operazione. - -### Workflow Principale: Sincronizzazione Online/Offline - -Questo è lo scenario d'uso primario del tool. Assumiamo: -* **Macchina ORIGINE:** PC con il repository Git principale. -* **Macchina DESTINAZIONE:** PC offline dove vuoi lavorare. -* **Supporto Esterno:** Chiavetta USB (o simile) per trasferire i file bundle. - -#### Fase 1: Configurazione Iniziale dei Profili - -* **Su Entrambe le Macchine:** Avvia il tool. -* **Crea/Seleziona Profilo:** Crea un profilo con lo stesso nome su entrambe le macchine (es. "MioProgettoOffline"). -* **Configura (ORIGINE):** - * `SVN Working Copy Path`: Percorso repo Git su ORIGINE. - * `Bundle Target Directory`: Lettera/Percorso della chiavetta USB. - * `Create Bundle Filename`: Nome bundle da ORIGINE a DESTINAZIONE (es. `MioProgetto_O2D.bundle`). - * `Fetch Bundle Filename`: Nome bundle da DESTINAZIONE a ORIGINE (es. `MioProgetto_D2O.bundle`). - * Configura Backup/Commit a piacere. - * Clicca **Save Profile**. -* **Configura (DESTINAZIONE):** - * `SVN Working Copy Path`: Percorso della cartella (inizialmente vuota) su DESTINAZIONE dove andrà il repo. - * `Bundle Target Directory`: Lettera/Percorso della chiavetta USB. - * `Create Bundle Filename`: **Deve corrispondere** al `Fetch Bundle Filename` dell'ORIGINE (es. `MioProgetto_D2O.bundle`). - * `Fetch Bundle Filename`: **Deve corrispondere** al `Create Bundle Filename` dell'ORIGINE (es. `MioProgetto_O2D.bundle`). - * Configura Backup/Commit a piacere. - * Clicca **Save Profile**. - -#### Fase 2: Creare il Bundle Iniziale (Macchina ORIGINE) - -1. Assicurati che tutte le modifiche nel repository su ORIGINE siano committate. -2. Inserisci la chiavetta USB. -3. Avvia il tool, seleziona il profilo "MioProgettoOffline". -4. Vai alla scheda "Repository / Bundle". -5. Se l'indicatore di stato è rosso, clicca "Prepare Repository". -6. Clicca **"Create Bundle"**. Verrà creato il file `MioProgetto_O2D.bundle` sulla USB. Controlla il log. - -#### Fase 3: Clonare dal Bundle (Macchina DESTINAZIONE) - -1. Sposta la chiavetta USB sulla Macchina DESTINAZIONE. -2. Crea la cartella vuota specificata nel profilo (se non esiste già). -3. Avvia il tool, seleziona il profilo "MioProgettoOffline". -4. Vai alla scheda "Repository / Bundle". -5. Clicca "Prepare Repository" (inizializza la cartella vuota come repo Git). -6. Clicca **"Fetch from Bundle"**. Il tool leggerà `MioProgetto_O2D.bundle` dalla USB e popolerà il repository locale. Controlla il log. -7. Ora hai una copia funzionante del repository sulla Macchina DESTINAZIONE. - -#### Fase 4: Lavorare Offline (Macchina DESTINAZIONE) - -1. Modifica i file del progetto nella directory del repository su DESTINAZIONE. -2. Fai commit delle tue modifiche: - * Usa la scheda "Commit" del tool (inserisci messaggio, clicca "Commit All Changes Manually"). - * Oppure usa i comandi `git add` e `git commit` da terminale nella directory del repository. - -#### Fase 5: Creare Bundle di Aggiornamento (Macchina DESTINAZIONE) - -1. Inserisci la chiavetta USB. -2. Avvia il tool, seleziona il profilo "MioProgettoOffline". -3. Vai alla scheda "Repository / Bundle". -4. Clicca **"Create Bundle"**. Verrà creato il file `MioProgetto_D2O.bundle` sulla USB, contenente le modifiche fatte offline. Controlla il log. - -#### Fase 6: Importare Aggiornamenti (Macchina ORIGINE) - -1. Sposta la chiavetta USB sulla Macchina ORIGINE. -2. Avvia il tool, seleziona il profilo "MioProgettoOffline". -3. Vai alla scheda "Repository / Bundle". -4. Clicca **"Fetch from Bundle"**. Il tool leggerà `MioProgetto_D2O.bundle` dalla USB, importerà i commit e tenterà di fare il merge nel branch corrente del repository su ORIGINE. Controlla il log per successo o eventuali conflitti. -5. Se ci sono conflitti, risolvili manualmente usando strumenti Git standard e fai commit della risoluzione. - -#### Fase 7: Continuare il Ciclo - -Ripeti i passaggi da Fase 4 a Fase 6 per continuare a sincronizzare le modifiche tra le due macchine. Puoi anche invertire il flusso se fai modifiche sull'ORIGINE che vuoi portare sulla DESTINAZIONE (creando il bundle `_O2D` e facendo fetch sulla DESTINAZIONE). - -### Backup Manuale - -1. Seleziona il profilo desiderato. -2. Vai alla scheda "Backup Settings". -3. Assicurati che le opzioni "Exclude..." siano configurate come vuoi. -4. Assicurati che il percorso in "Backup Directory" sia valido (anche se "Enable Auto Backup" non è spuntato, il percorso viene usato per il backup manuale). -5. Clicca **"Create Manual Backup Now (ZIP)"**. Verrà creato un file ZIP con timestamp nella directory di backup specificata. - -### Commit Manuale - -1. Seleziona il profilo del repository su cui vuoi fare commit. -2. Vai alla scheda "Commit". -3. Scrivi un messaggio di commit significativo nell'area di testo. -4. Clicca **"Commit All Changes Manually"**. - -### Gestione Tag e Branch - -* **Visualizzare:** Vai alle schede "Tags" o "Branches" e clicca "Refresh..." per caricare l'elenco aggiornato. -* **Creare:** Clicca "Create New Tag..." o "Create New Branch...", inserisci il nome (e messaggio per i tag) nella finestra di dialogo. -* **Checkout:** Seleziona un tag o branch dalla lista e clicca "Checkout Selected Tag" o "Checkout Selected Branch". Ricorda le implicazioni (Detached HEAD per i tag). - -### Modifica di `.gitignore` - -1. Seleziona il profilo del repository desiderato. -2. Vai alla scheda "Repository / Bundle". -3. Clicca **"Edit .gitignore"**. Si aprirà una finestra di editor. -4. Modifica il file come necessario. -5. Clicca "Save and Close" per salvare le modifiche o "Cancel" per annullare. - -## 7. File di Configurazione (`git_svn_sync.ini`) - -Le impostazioni dei profili vengono salvate in un file chiamato `git_svn_sync.ini` nella stessa directory dello script. Il formato è standard INI. - -**Si sconsiglia di modificare manualmente questo file**, a meno che non si sappia esattamente cosa si sta facendo. Il tool gestisce la creazione, la lettura e la scrittura di questo file in modo sicuro. - -## 8. Logging - -Il tool produce log dettagliati per aiutarti a capire le operazioni e diagnosticare problemi: - -* **Area Log GUI:** Mostra i log in tempo reale nella parte inferiore della finestra principale. Utile per un feedback immediato. -* **File di Log:** Un file chiamato `git_svn_sync.log` viene creato (o aggiunto) nella directory dello script. Contiene una cronologia più persistente delle operazioni, utile per analisi post-mortem. - -I livelli di log (INFO, DEBUG, WARNING, ERROR, CRITICAL) aiutano a distinguere la gravità dei messaggi. - -## 9. Risoluzione Problemi Comuni - -* **Errore "git command not found" o simile:** Git non è installato correttamente o non è nel PATH di sistema. Verifica l'installazione di Git. -* **Errore "Permission denied":** Lo script non ha i permessi per leggere/scrivere nelle directory specificate (repository, bundle target, backup). Controlla i permessi delle cartelle. -* **Conflitti durante "Fetch from Bundle":** Significa che ci sono state modifiche divergenti sullo stesso branch in entrambi i repository (ORIGINE e DESTINAZIONE) tra le sincronizzazioni. Devi risolvere i conflitti manualmente nel repository dove hai eseguito il fetch, usando i comandi Git standard (`git status`, modifica i file con i marcatori di conflitto `<<<<<`, `>>>>>`, `=====`, poi `git add `, `git commit`). -* **Bundle vuoto creato ("refusing to create empty bundle"):** Il repository di origine non aveva commit o riferimenti (branch/tag) da includere nel bundle. Questo è normale per un repository appena inizializzato. -* **Impostazioni non salvate:** Ricorda sempre di cliccare "Save Profile" dopo aver modificato percorsi, nomi file o opzioni in un profilo. -* **L'indicatore di stato non diventa verde:** Assicurati che il percorso in "SVN Working Copy Path" sia corretto e punti a una directory esistente. Se è corretto ma rimane rosso, prova a cliccare "Prepare Repository". Se fallisce, controlla i log per errori specifici. +* **Local Branches:** List of local branches. The current branch is marked with `*`. + * **Right-Click:** + * **Checkout Branch:** Switches to the selected branch. + * **Merge '{branch}' into current '{current}'**: Integrates changes from the selected branch into the currently active branch. May cause conflicts. (Enabled only if selecting a different branch than the current one). + * **Delete Branch:** Deletes the selected local branch (asks for confirmation). Fails if the branch has changes not yet merged into other branches. + * **Force Delete Branch:** Deletes the selected local branch even if it has unmerged changes (use with caution: potential data loss). + * **Compare '{branch}' with current '{current}'**: Opens a view showing files that differ between the selected branch and the current one. +* **Refresh Branches:** Updates the local branch list. +* **Create New Branch...:** Opens a dialog to enter the name for a new local branch, which will be created based on the current commit. +* **Checkout Selected Branch:** Switches to the branch selected in the list. + +### 4.7. "History" Tab + +Displays the repository's commit history. + +* **Filter History by Branch/Tag:** Dropdown menu to show history only for a specific branch or tag, or for all (`-- All History --`). +* **Refresh History:** Reloads the history based on the selected filter. +* **History List (Treeview):** Shows commits (short hash, date/time, author, message/references). Most recent commits are at the top. + * **Double-Click:** Opens a detail window for the selected commit, showing full metadata and the list of files changed in that commit. From there, you can view the diff for each individual file compared to its parent commit. + +### 4.8. Log Area & Status Bar + +* **Application Log:** Scrollable text area showing detailed messages about all operations, errors, warnings, and debug information. Messages are also written to the `git_svn_sync.log` file. +* **Status Bar:** Line at the bottom of the window showing concise messages about the current state ("Ready.", "Processing...", "Error...", "Success"). May change color to highlight states (yellow for processing, green for success, red for error). + +## 5. Common Use Cases (Workflows) + +### 5.1. Scenario: Starting with an Existing Project (Not Yet Git) + +**Goal:** Put an existing project (e.g., from SVN or just files) under Git control and set up a profile in the application. + +**Steps:** + +1. Open **Git Sync Tool**. +2. Click **Add New** in the profile bar. Enter a profile name (e.g., `MyProject`) and click OK. +3. The new profile is selected. +4. In the **Repository / Bundle** tab, click **Browse...** next to "Working Directory Path" and select your project's main folder. +5. Click **Save Profile**. +6. If the folder isn't a Git repository, the indicator dot will be **red**. Click **Prepare Repository**. The indicator should turn **green**. +7. (Optional) Click **Edit .gitignore** to add project-specific rules (e.g., temporary files, build output). Save and close the editor. The application will check if any tracked files need to be untracked. +8. Go to the **Commit / Changes** tab. Click **Refresh List**. You should see all project files listed as "Untracked" (`??`). +9. Write an initial commit message (e.g., "Initial project import") in the "Commit Message" field. +10. Click **Commit Staged Changes**. This will add all files and create the first commit. +11. Your local repository is ready. + +### 5.2. Scenario: Standard Local Workflow + +**Goal:** Make changes, view them, and create a commit. + +**Steps:** + +1. Select the correct profile. Ensure the Working Directory indicator is **green**. +2. Modify your project files using your external editors. +3. Go to the **Commit / Changes** tab. +4. Click **Refresh List**. The "Working Directory Changes" list will show modified (`M`), added (`A` if you used `git add` externally or via context menu), deleted (`D`), or untracked (`??`) files. +5. (Optional) If you have untracked files (`??`) you want to include, select them and use **Right-Click -> Add to Staging Area**. Then click **Refresh List** again. +6. (Optional) To see specific changes in a file, **double-click** the file in the list to open the **Diff Viewer**. Close the viewer when done. +7. Write a descriptive commit message in the "Commit Message" area. +8. Click **Commit Staged Changes**. +9. Your changes are now recorded in the local Git history. You can see this by refreshing the **History** tab. + +### 5.3. Scenario: Offline Synchronization via Bundle + +**Goal:** Transfer changes between two computers (PC-A and PC-B) without a direct network connection, using removable media (e.g., USB drive). + +**Steps (on PC-A):** + +1. Work on the project on PC-A (see Scenario 5.2). Ensure all desired changes are committed. +2. Select the project's profile. +3. Go to the **Repository / Bundle** tab. +4. Set the "Bundle Target Directory" to the path of your USB drive (or other shared folder). +5. Set a meaningful name in "Create Bundle Filename" (e.g., `project_update_20250428.bundle`). +6. (Optional but recommended) Go to the **Backup Settings** tab, enable "Enable Auto Backup", and configure the "Backup Directory" (on PC-A) for safety. +7. Click **Save Profile**. +8. Return to the **Repository / Bundle** tab and click **Create Bundle**. Wait for completion. +9. Physically transfer the USB drive (or access the shared folder) from PC-B. + +**Steps (on PC-B):** + +1. Launch **Git Sync Tool** and select (or create/configure) the profile for the same project on PC-B. The "Working Directory Path" must point to the local copy of the project on PC-B. +2. Go to the **Repository / Bundle** tab. +3. Set the "Bundle Target Directory" to the path of the USB drive (or shared folder). +4. Set the filename received from PC-A in "Fetch Bundle Filename". +5. (Optional but recommended) Configure backup in the **Backup Settings** tab for PC-B. +6. Click **Save Profile**. +7. Return to the **Repository / Bundle** tab and click **Fetch from Bundle**. + * If the repository didn't exist on PC-B, it will be cloned from the bundle. + * If it existed, changes will be integrated (conflicts may occur if unsynchronized changes were also made on PC-B). +8. PC-B now has the changes from PC-A. You can resume the cycle by transferring a bundle from B to A. + +### 5.4. Scenario: First Push to a Remote Repository (e.g., Gitea) + +**Goal:** Upload an existing local repository to a remote server (e.g., Gitea) where an empty project has just been created. + +**Steps:** + +1. Ensure you have a ready local repository (see Scenario 5.1). +2. Create an **empty** project on your Gitea (or GitHub/GitLab) server. Copy the provided URL (HTTPS or SSH). +3. Open **Git Sync Tool** and select the profile for your local repository. +4. Go to the **Remote Repository** tab. +5. Paste the URL copied from Gitea into the **Remote URL** field. +6. Leave or enter `origin` in the **Local Name** field. +7. Click **Apply Config**. Check logs or status bar for confirmation. +8. (Recommended) Click **Check Connection**. Verify the status indicator and resolve any authentication issues if prompted. +9. Go to the **Branches (Local Ops)** tab and ensure you have **checked out** the main branch (e.g., `master` or `main`) containing the history you want to upload. The asterisk `*` must be next to that branch. +10. Return to the **Remote Repository** tab. +11. Click **Push**. The application should detect it's the first push and use the `--set-upstream` option. You might be prompted for credentials. +12. Wait for completion. Check your Gitea repository in the browser. + +### 5.5. Scenario: Standard Workflow with a Remote Repository + +**Goal:** Keep local work synchronized with a remote repository. + +**Steps:** + +1. Select the correct profile. Ensure the remote is configured. +2. **Before starting work:** Go to the **Remote Repository** tab and click **Pull** (or first **Fetch**, then resolve any differences before merging/pulling). This downloads changes made by others (or yourself on another machine) and integrates them locally. Resolve any merge conflicts if they occur. +3. **Work locally:** Modify files, make commits (see Scenario 5.2). +4. **When ready to share:** Go to the **Remote Repository** tab. +5. (Optional) Click **Fetch** and then **Refresh Sync Status** to see if there are new remote changes before pushing. If there are remote changes (`behind > 0`), use **Pull** and integrate them first. +6. Click **Push** to upload your local commits to the remote. + +### 5.6. Scenario: Branch Management + +**Goal:** Create a branch for a new feature, work on it, and then merge it back into the main branch. + +**Steps:** + +1. Select the profile and ensure you are on the main branch (e.g., `master`). +2. Go to the **Branches (Local Ops)** tab. +3. Click **Create New Branch...**. Enter a name (e.g., `feature/new-idea`) and click OK. +4. The new branch is created, but you haven't switched to it yet. Select the new branch in the list. +5. Click **Checkout Selected Branch**. You are now working on the new branch. +6. Work on the feature: modify files, make commits (Scenario 5.2) *on the `feature/new-idea` branch*. +7. **When the feature is complete:** + * Ensure all changes on the `feature/new-idea` branch are committed. + * Select the main branch (e.g., `master`) in the list. + * Click **Checkout Selected Branch** to return to main. + * (Optional but recommended) Do a **Pull** on the main branch to ensure you have the latest remote changes. + * Select the `feature/new-idea` branch in the list. + * **Right-Click** on `feature/new-idea` and choose **Merge 'feature/new-idea' into current 'master'**. Confirm. + * Resolve any merge conflicts, then make a commit from the "Commit / Changes" tab. +8. The feature is now integrated into the main branch. +9. (Optional) If you no longer need the `feature/new-idea` branch: select it, **Right-Click**, and choose **Delete Branch 'feature/new-idea'**. Confirm. +10. (Optional) **Push** the main branch to upload the merged changes to the remote. + +### 5.7. Scenario: Creating and Using a Tag + +**Goal:** Mark a specific version of the software (e.g., a release). + +**Steps:** + +1. Ensure the commit you want to tag is the current one (checkout the appropriate branch/commit). +2. Ensure there are no uncommitted local changes. +3. Go to the **Tags** tab. +4. Click **Create New Tag...**. +5. Enter a tag name (common standard: `vX.Y.Z`, e.g., `v1.0.0`) and a descriptive message (e.g., "Release version 1.0.0"). Click OK. +6. The tag is created locally. +7. (Optional) To share the tag, go to the **Remote Repository** tab and click **Push Tags**. +8. (Optional) To view the code state at the time of the tag, select it in the **Tags** tab list and click **Checkout Selected Tag** (remember you'll enter "Detached HEAD"). + +### 5.8. Scenario: Viewing Changes + +**Goal:** Understand what has changed between different versions or within a specific commit. + +**Steps:** + +* **Local Changes (vs Last Commit):** + 1. Go to the **Commit / Changes** tab. + 2. Click **Refresh List**. + 3. **Double-click** a modified file (`M`) to open the **Diff Viewer**. +* **Changes in a Specific Commit (vs Parent):** + 1. Go to the **History** tab. + 2. **Double-click** the desired commit. + 3. The **Commit Details** window opens. + 4. **Double-click** a file in the "Changed Files" list to open the **Diff Viewer**, showing the changes introduced *by that commit* for that file. +* **Changes Between Different Branches/Tags/Commits:** + 1. Ensure you are on the branch you want to use as the comparison base (e.g., `master`). + 2. Go to the **Branches (Local Ops)** or **Remote Repository** tab. + 3. **Right-Click** on the branch/tag (local or remote) you want to compare against. + 4. Choose **Compare '{other_ref}' with current '{your_branch}'**. + 5. The **Differences Summary** window opens, listing the differing files. + 6. **Double-click** a file in that window to open the **Diff Viewer** showing the comparison between the two chosen references. --- \ No newline at end of file