SXXXXXXX_RepoSync/doc/Italian-manual.md

# 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`.