SXXXXXXX_RepoSync/doc/Italian-manual.md

RepoSync - Manuale Utente

Indice dei Contenuti

1. Introduzione
2. Primi Passi
   • Installazione
   • Configurazione Iniziale
3. La Finestra Principale
4. Gestione dei Profili
5. Il Flusso di Esportazione
6. Il Flusso di Importazione
7. Comprendere gli Stati di Sincronizzazione
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.