# RepoSync - Manuale Utente ## Indice dei Contenuti 1. [Introduzione](#1-introduzione-1) 2. [Primi Passi](#2-primi-passi) - [Installazione](#installazione-1) - [Configurazione Iniziale](#configurazione-iniziale) 3. [La Finestra Principale](#3-la-finestra-principale) 4. [Gestione dei Profili](#4-gestione-dei-profili) 5. [Il Flusso di Esportazione](#5-il-flusso-di-esportazione) 6. [Il Flusso di Importazione](#6-il-flusso-di-importazione) 7. [Comprendere gli Stati di Sincronizzazione](#7-comprendere-gli-stati-di-sincronizzazione) 8. [Domande Frequenti (FAQ)](#8-domande-frequenti-faq) --- ### 1. Introduzione RepoSync è un'applicazione desktop che permette di sincronizzare repository Git tra due server senza un collegamento di rete diretto. Utilizza la funzione `.bundle` di Git per creare una copia completa e portatile di un repository, che può poi essere trasferita e "spacchettata" su un altro server. Questo manuale ti guiderà attraverso tutte le funzionalità dell'applicazione. ### 2. Primi Passi #### Installazione 1. Clona il repository dalla sua origine. 2. Naviga nella directory del progetto. 3. Installa i pacchetti Python richiesti: `pip install -r requirements.txt`. #### Configurazione Iniziale Prima di poter usare RepoSync, devono essere configurate due cose: 1. **Cartella Bundle**: Al primo avvio, ti verrà chiesto di selezionare una cartella. Questa cartella è cruciale, poiché conterrà tutti i bundle dei repository esportati e il file `manifest.json`. Puoi cambiare questo percorso in seguito usando il pulsante "Sfoglia...". 2. **Profili Server**: Devi indicare a RepoSync come connettersi ai tuoi server Git. Vai nel menu `File -> Configura Profili...` per impostare almeno un profilo per il tuo server di origine e uno per quello di destinazione. ### 3. La Finestra Principale L'interfaccia utente è divisa in quattro aree principali: - **Percorso Cartella Bundle**: In alto, mostra la cartella bundle attualmente selezionata. Puoi cambiarla con "Sfoglia..." o svuotarne il contenuto con "Reset". - **Schede (Esporta/Importa)**: L'area principale è divisa in due schede, una per ogni fase della sincronizzazione. - **Log**: Il pannello inferiore mostra i log dettagliati di tutte le operazioni, utile per il debug. - **Barra di Stato**: In fondo, una barra di stato mostra l'operazione corrente, una barra di avanzamento e la dimensione totale di un'esportazione/importazione. ### 4. Gestione dei Profili Il Gestore Profili (`File -> Configura Profili...`) è dove salvi le impostazioni di connessione per i tuoi server Gitea. - **Nome Profilo**: Un nome amichevole a tua scelta (es. "Gitea Casa", "Server Lavoro"). - **URL Server**: L'URL di base della tua istanza Gitea (es. `http://192.168.1.100:3000`). - **Token di Accesso**: Un token di accesso personale generato dalle impostazioni del tuo account Gitea. È necessario per l'accesso all'API e per le operazioni Git. - **Tipo di Servizio**: Attualmente supporta `gitea`. Da questa finestra puoi creare un profilo (`Nuovo`), salvarlo (`Salva`) o eliminarlo (`Elimina`). ### 5. Il Flusso di Esportazione Questo processo copia i repository da un server di origine alla tua cartella bundle. 1. Vai alla scheda **Esporta da Server**. 2. Seleziona il profilo server corretto dal menu a tendina "Esporta da Server:". 3. Clicca sul pulsante **Recupera Elementi**. RepoSync si connetterà al server e confronterà i suoi repository con il contenuto del tuo file `manifest.json`. 4. La lista verrà popolata, mostrando lo stato di sincronizzazione di ogni elemento. 5. Seleziona i repository e le wiki che desideri esportare. Puoi usare il pulsante "Seleziona Modificati" per selezionare rapidamente tutti gli elementi nuovi o modificati sul server. 6. Clicca sul pulsante **Esporta Selezionati**. RepoSync clonerà ogni elemento selezionato e creerà un file `.bundle` per esso nella tua cartella bundle. 7. Una volta completato, puoi spostare fisicamente l'intera cartella bundle sulla tua altra macchina. ### 6. Il Flusso di Importazione Questo processo copia i repository dalla tua cartella bundle a un server di destinazione. 1. Assicurati che la tua cartella bundle sia accessibile dalla macchina corrente. 2. In RepoSync, imposta il "Percorso Cartella Bundle" sulla posizione corretta. 3. Vai alla scheda **Importa su Server**. 4. Seleziona il profilo del server di destinazione corretto dal menu a tendina "Importa su Server:". 5. Clicca sul pulsante **Controlla Stato Bundle**. RepoSync leggerà il `manifest.json` e confronterà il suo contenuto con i repository sul server di destinazione. 6. La lista verrà popolata. Presta molta attenzione allo stato: - Puoi importare solo elementi con stato `NEW_REPO` (non esiste sul server) o `BEHIND` (il bundle ha modifiche più recenti del server). 7. Seleziona gli elementi che desideri importare. 8. Clicca sul pulsante **Importa Selezionati**. RepoSync creerà o aggiornerà i repository sul server di destinazione. ### 7. Comprendere gli Stati di Sincronizzazione Lo stato indica la relazione tra il server e il tuo bundle/manifest locale. **Nella Scheda Esporta:** - **NEW_REPO**: Questo repository esiste sul server ma non nella tua cartella bundle. Deve essere esportato. - **AHEAD**: Il repository sul server ha nuovi commit che non sono nel tuo bundle. Deve essere esportato. - **IDENTICAL**: Il server e il bundle sono perfettamente sincronizzati. Nessuna azione richiesta. - **ORPHANED_BUNDLE**: Esiste un bundle per questo elemento, ma il repository è stato cancellato dal server. **Nella Scheda Importa:** - **NEW_REPO**: Esiste un bundle per questo elemento, ma il repository non esiste sul server di destinazione. È pronto per essere importato. - **BEHIND**: Il bundle contiene commit più recenti rispetto al repository sul server di destinazione. È pronto per essere importato. - **AHEAD**: Il repository sul server di destinazione ha commit più recenti del bundle. **Non puoi importarlo**, poiché sovrascriverebbe le modifiche. Devi prima esportare da questo server. - **DIVERGED**: Sia il bundle che il repository sul server hanno nuovi commit unici. Richiede un intervento manuale. - **IDENTICAL**: Il bundle e il server sono sincronizzati. Nessuna azione richiesta. ### 8. Domande Frequenti (FAQ) **D: L'importazione della mia wiki è fallita e mi ha chiesto di fare un'azione manuale. Perché?** R: A causa di una limitazione o di un bug in alcune versioni di Gitea, un repository wiki non può essere creato tramite un `git push` se è completamente vuoto. RepoSync ti istruirà a visitare l'interfaccia web di Gitea, andare alla scheda "Wiki" del repository e cliccare su "Crea la prima pagina". Questo inizializza la wiki sul server. Dopodiché, puoi eseguire nuovamente l'importazione in RepoSync, che questa volta avrà successo. **D: Cos'è un file `.bundle`?** R: È una funzionalità standard di Git. Un singolo file che contiene l'intera cronologia di un repository Git, inclusi tutti i branch e i tag. È un backup completo e portatile. **D: Cos'è `manifest.json`?** R: È il "cervello" di RepoSync. Memorizza i metadati di ogni repository esportato, incluso l'hash del commit di ogni branch. Questo file permette a RepoSync di determinare lo stato di sincronizzazione senza dover ispezionare ogni file bundle a ogni controllo. **D: Come ottengo un Token di Accesso per Gitea?** R: Accedi al tuo account Gitea, vai su `Impostazioni -> Applicazioni` e, sotto "Gestisci Token di Accesso", genera un nuovo token. Assicurati che abbia i permessi di lettura e scrittura per i `repository`. **D: Posso usare questo programma con GitHub o GitLab?** R: Attualmente, il client API è scritto specificamente per Gitea. La logica di base potrebbe essere adattata per supportare altri servizi creando un nuovo client che implementi l'interfaccia `BaseVCSClient`.