SXXXXXXX_GitUtility/manual.md at e3bf97eeb54fe59d2fc7334ec10e9d9d70ad3830

VALLONGOL/SXXXXXXX_GitUtility

Fork 0

VALLONGOL f6f3586171 fix problem with fetch with empty folder

2025-04-18 12:15:42 +02:00

22 KiB

Raw Blame History

Manuale Utente: Git SVN Sync Tool

Indice

Introduzione
- Scopo del Tool
- Funzionalità Principali
Prerequisiti
Installazione e Avvio
Concetti Fondamentali
- Profili di Configurazione
- Git Bundles
Interfaccia Utente (GUI)
Funzionalità Dettagliate e Flussi di Lavoro
File di Configurazione (git_svn_sync.ini)
Logging
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.

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.

2. Prerequisiti

Prima di utilizzare il tool, assicurati di avere:

Python: Versione 3.x installata sul tuo sistema.
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.

3. Installazione e Avvio

Il tool è uno script Python e non richiede un'installazione complessa.

Assicurati che tutti i file sorgente (.py) siano nella stessa directory.
Apri un terminale o prompt dei comandi.
Naviga fino alla directory contenente gli script.
Esegui il comando:
```
python GitUtility.py
```
L'interfaccia grafica dell'applicazione dovrebbe apparire.

4. Concetti Fondamentali

Profili di Configurazione

Un Profilo rappresenta un insieme salvato di impostazioni specifiche per un determinato repository o flusso di lavoro. Ogni profilo contiene:

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.

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.

Git Bundles

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.

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.

5. Interfaccia Utente (GUI)

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.

Gestione Profili (Area Superiore)

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.

Schede Principali (Notebook)

Scheda: Repository / Bundle

Questa scheda gestisce i percorsi fondamentali e le azioni principali legate ai bundle.

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.

Scheda: Backup Settings

Configura le opzioni di backup automatico e manuale.

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.

Scheda: Commit

Gestisce il commit automatico e manuale.

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

Aggiungere: Clicca "Add New", inserisci un nome univoco, clicca OK. Il nuovo profilo verrà selezionato.
Configurare: Compila i percorsi e le opzioni desiderate nelle varie schede.
Salvare: Clicca "Save Profile" per memorizzare le impostazioni.
Selezionare: Usa il dropdown "Select Profile" per passare da una configurazione all'altra.
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)

Assicurati che tutte le modifiche nel repository su ORIGINE siano committate.
Inserisci la chiavetta USB.
Avvia il tool, seleziona il profilo "MioProgettoOffline".
Vai alla scheda "Repository / Bundle".
Se l'indicatore di stato è rosso, clicca "Prepare Repository".
Clicca "Create Bundle". Verrà creato il file MioProgetto_O2D.bundle sulla USB. Controlla il log.

Fase 3: Clonare dal Bundle (Macchina DESTINAZIONE)

Sposta la chiavetta USB sulla Macchina DESTINAZIONE.
Crea la cartella vuota specificata nel profilo (se non esiste già).
Avvia il tool, seleziona il profilo "MioProgettoOffline".
Vai alla scheda "Repository / Bundle".
Clicca "Prepare Repository" (inizializza la cartella vuota come repo Git).
Clicca "Fetch from Bundle". Il tool leggerà MioProgetto_O2D.bundle dalla USB e popolerà il repository locale. Controlla il log.
Ora hai una copia funzionante del repository sulla Macchina DESTINAZIONE.

Fase 4: Lavorare Offline (Macchina DESTINAZIONE)

Modifica i file del progetto nella directory del repository su DESTINAZIONE.
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)

Inserisci la chiavetta USB.
Avvia il tool, seleziona il profilo "MioProgettoOffline".
Vai alla scheda "Repository / Bundle".
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)

Sposta la chiavetta USB sulla Macchina ORIGINE.
Avvia il tool, seleziona il profilo "MioProgettoOffline".
Vai alla scheda "Repository / Bundle".
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.
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

Seleziona il profilo desiderato.
Vai alla scheda "Backup Settings".
Assicurati che le opzioni "Exclude..." siano configurate come vuoi.
Assicurati che il percorso in "Backup Directory" sia valido (anche se "Enable Auto Backup" non è spuntato, il percorso viene usato per il backup manuale).
Clicca "Create Manual Backup Now (ZIP)". Verrà creato un file ZIP con timestamp nella directory di backup specificata.

Commit Manuale

Seleziona il profilo del repository su cui vuoi fare commit.
Vai alla scheda "Commit".
Scrivi un messaggio di commit significativo nell'area di testo.
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`

Seleziona il profilo del repository desiderato.
Vai alla scheda "Repository / Bundle".
Clicca "Edit .gitignore". Si aprirà una finestra di editor.
Modifica il file come necessario.
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 <file_risolti>, 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.

22 KiB Raw Blame History