Guida a Forgejo

1. Cos’è il versioning e perché usarlo

Il controllo di versione registra ogni modifica attuata a uno o più file nel tempo. Piuttosto di avere cartelle con nomi come:

progetto_finale/
progetto_finale_v2/

Si ha un’unica cartella e uno strumento che tiene traccia delle modifiche. Puoi vedere cosa è cambiato, quando e chi lo ha fatto. Puoi lavorare in parallelo con i colleghi senza sovrascriverne il lavoro.

Forgejo è il software che ospita i progetti e offre un’interfaccia web per navigarli e collaborare. Git è lo strumento che gira sul proprio computer e con cui sincronizzare le modifiche con il server.

2. Concetti fondamentali

Prima di iniziare è utile avere chiari determinati termini.

Repository (o repo): la cartella del progetto con la sua storia. Esiste sul server Forgejo (copia remota) e sul computer su cui si lavora (copia locale).

Commit: una fotografia dello stato dei file in un determinato momento. Ogni commit ha un messaggio descrittivo che spiega cosa è stato fatto.

Clone: scaricare una copia di un repository dal server remoto al proprio computer.

Push: caricare i propri commit locali sul server.

Pull: scaricare dal server i commit fatti da altri.

Branch: linea di sviluppo parallela. Permette di lavorare su una modifica senza toccare il codice principale finché non si è soddisfatti del risultato.

Merge: unire un branch in un altro. Ad esempio, quando il lavoro su un branch, come una micro modifica, è completo, lo si unisce al branch principale.

Main: il branch principale del progetto. Contiene la versione stabile e ufficiale del software o file modificato.

Staging area: una zona intermedia dove si preparano le modifiche prima di creare un commit. Con git add si aggiungono file alla staging area, con git commit si crea il commit.

3. Installare Git sul proprio computer

Va installato su ogni computer che si usa per lavorare.

Windows

Scarica Git da https://git-scm.com e installa con le opzioni di default. Durante l’installazione, quando ti chiede l’editor di default, puoi scegliere Notepad o Visual Studio Code se li hai installati.

Dopo l’installazione avrai “Git Bash”, un terminale con cui eseguire i comandi Git.

4. Configurare Git per la prima volta

Prima di fare qualsiasi cosa, Git ha bisogno di sapere chi sei. Questi dati vengono allegati a ogni commit che crei. Eseguili una volta sola sul tuo computer.

git config --global user.name "Mario Rossi"
git config --global user.email "mario.rossi@a4x.it"

Usa lo stesso indirizzo email con cui ti sei registrato su Forgejo.

5. Accedere a Forgejo

Apri il browser e visita l’indirizzo del server Forgejo:

http://192.168.40.12:3000

Effettua il login con le credenziali che ti ha fornito l’amministratore. Dopo il login ti trovi nella dashboard, dove vedrai i repository a cui hai accesso.

Cambiare la password

Al primo accesso è buona norma cambiare la password temporanea. Vai su:

Menu in alto a destra (tua icona) > Impostazioni > Account > Cambia password

Aggiungere una chiave SSH

Una chiave SSH è un sistema di riconoscimento basato su crittografia che permette di scrivere le tue modifiche locali sul server.

Quando esegui ssh-keygen vengono creati due file:

id_ed25519 è la chiave privata. Rimane sempre e solo sul tuo computer.
id_ed25519.pub è la chiave pubblica da incollare su Forgejo.

Apri Git Bash e inserisci:

ssh-keygen -t ed25519 -C "mario.rossi@a4x.it"

Premi Invio a tutte le domande per accettare i valori di default.

Ora copia il contenuto della chiave pubblica: Apri Git Bash e inserisci:

cat ~/.ssh/id_ed25519.pub

Copia l’intera riga che inizia con ssh-ed25519.

In Forgejo, vai su Menu in alto a destra > Impostazioni > Chiavi SSH/GPG > Aggiungi chiave

Incolla la chiave, dai un nome descrittivo (es. “PC ufficio 1”) e salva.

6. Creare un repository

Un repository corrisponde a un progetto. Puoi crearne uno nuovo su Forgejo oppure caricare un progetto esistente.

Creare un nuovo repository vuoto

Dalla dashboard, clicca sul pulsante + in alto a destra e scegli Nuovo repository.

Compila i campi:

Proprietario: Seleziona A4X
Nome repository: usa lettere minuscole, numeri e trattini (es. gestionale-magazzino)
Descrizione
Visibilità: lascia “Privato”
Inizializza il repository: spunta questa opzione se stai partendo da zero, lasciala deselezionata se vuoi caricare un progetto esistente
Aggiungi .gitignore: Il .gitignore dice a Git quali file ignorare ed evitare di caricare sul server remoto (file temporanei ecc.)

Clicca Crea repository.

Caricare un progetto esistente sul server

Se hai già una cartella con del codice sul tuo computer e vuoi portarla su Forgejo, prima crea un repository vuoto su Forgejo (senza spuntare “Inizializza”, dal passaggio precedente), poi, da git bash:

# Entra nella cartella del tuo progetto
cd /percorso/del/tuo/progetto
 
# Inizializza Git in questa cartella
git init
 
# Aggiungi tutti i file esistenti
git add .
 
# Crea il primo commit
git commit -m "Prima versione del progetto"
 
# Collega la cartella locale al repository remoto
# l'URL lo trovi nella pagina del repository su Forgejo)
git remote add origin ssh://git@192.168.40.12:222/nomeutente/nome-repo.git
 
# Carica tutto sul server
git push -u origin main

7. Scarocare un repository sul proprio computer

Per lavorare su un repository che esiste già su Forgejo devi clonarlo, ovvero scaricare una copia locale completa.

Dalla pagina del repository su Forgejo, cerca il pulsante Clone o Codice e copia l’URL. Potrebbe essere ad esempio: ssh://git@192.168.40.12:222/nomeutente/nome-repo.git

Su git bash

git clone ssh://git@192.168.40.12:222/nomeutente/nome-repo.git

Questo crea una cartella con il nome del repository nella cartella corrente. Da questo momento la cartella è collegata al server. Git sa già dove fare push e pull.

8. Il flusso di lavoro quotidiano

Questa è la sequenza di operazioni che eseguirai ogni giorno.

Prima di iniziare a lavorare: sincronizzarsi

Prima di modificare qualsiasi file assicurati di avere la versione più aggiornata del repository, dato che qualcuno potrebbe averla modificata:

git pull

Questo scarica le modifiche fatte dai colleghi e le integra nella tua copia locale. Se non lo fai, rischi di lavorare su una versione vecchia e di creare conflitti evitabili.

Controllare lo stato delle modifiche

In qualsiasi momento puoi vedere cosa è cambiato:

git status

Vedrai tre categorie di file:

Changes to be committed (in verde): file già aggiunti alla staging area, pronti per il commit
Changes not staged for commit (in rosso): file modificati ma non ancora aggiunti alla staging area
Untracked files (in rosso): file nuovi che Git non sta ancora monitorando

Per vedere nel dettaglio cosa è cambiato riga per riga:

git diff

Preparare le modifiche per il commit

Aggiungi alla staging area i file che vuoi includere nel prossimo commit:

# Aggiungere tutto ciò che è cambiato
git add .

Creare un commit

git commit -m "Descrizione chiara di cosa hai fatto"

Il messaggio di commit Deve spiegare il perché della modifica. Esempi di messaggi utili:

Corretto bug nel calcolo delle imposte per ordini internazionali
Aggiunti test unitari per il modulo di pagamento

Caricare le modifiche sul server

git push

Questo invia i tuoi commit locali al server Forgejo. I colleghi potranno vederli e scaricarli con git pull.

Il ciclo completo in sintesi

git pull                   = scarica le novità dal server
(Lavori sul progetto)
git add .                  = prepari le modifiche
git commit -m "commento"   = crei la fotografia
git push                   = carichi sul server

9. Lavorare in team

Vedere i commit degli altri

Dalla pagina del repository su Forgejo, clicca su Commit per vedere tutta la storia del progetto

Da Git bash:

# Mostra la storia dei commit
git log
 
 
# Versione grafica, utile con i branch
git log --oneline --graph --all

Le Pull Request

Le Pull Request sono il meccanismo di revisione del codice in team. Quando hai completato una modifica su un branch separato (vedi sezione successiva), anziché fare il merge apri una Pull Request.

I colleghi possono esaminare le modifiche, approvare o richiedere modifiche. Solo dopo l’approvazione si procede con il merge.

Per aprire una PR, dalla pagina del repository clicca su Pull Request > Nuova pull request, seleziona il branch sorgente e quello di destinazione, aggiungi una descrizione e assegna i revisori (chi dovrà controllare il codice o il documento).

10. I branch: lavorare in parallelo senza rischi

I branch permettono di lavorare su una modifica in isolamento, senza toccare la versione principale del progetto e di unire il lavoro quando è pronto.

Quando usare un branch

Ogni volta che inizi qualcosa di significativo come una nuova funzionalità, una correzione di un bug complesso, un esperimento.

Creare e passare a un nuovo branch

# Crea un branch e spostati su di esso
git switch -c nome-del-branch

Scegli nomi descrittivi per i branch, come feature/autenticazione-oauth o fix/calcolo-iva-errato.

Lavorare su un branch

Una volta sul branch, lavori esattamente come al solito: modifichi file, fai git add e git commit. Le modifiche rimangono isolate su questo branch.

Vedere su quale branch sei

git branch

Il branch corrente è evidenziato con un asterisco.

Caricare il branch sul server

git push -u origin nome-del-branch

Il flag -u è necessario solo la prima volta per collegare il branch sul computer locale a quello remoto. Le volte successive basta git push.

Tornare al branch principale

git switch main

Unire un branch nel main

Quando il lavoro sul branch è completo e revisionato, lo unisci al main:

# Prima torna sul branch di destinazione
git switch main
 
# Assicurati di avere l'ultima versione
git pull
 
# Unisci il branch
git merge nome-del-branch

In un contesto di lavoro in gruppo è meglio fare il merge tramite Pull Request su Forgejo, in modo che ci sia sempre una revisione.

Eliminare un branch dopo il merge

# Elimina il branch locale
git branch -d nome-del-branch
 
# Elimina il branch remoto
git push origin --delete nome-del-branch

11. Risolvere i conflitti

Un conflitto avviene quando due persone hanno modificato la stessa parte dello stesso file in modo diverso e Git non sa quale versione tenere.

Come si presenta un conflitto

Quando fai git pull o git merge e c’è un conflitto Git ti avvisa con un messaggio come:

CONFLICT (content): Merge conflict in src/calcolo.py
Automatic merge failed; fix conflicts and then commit the result.

Aprendo il file in conflitto, vedrai delle annotazioni inserite da Git:

<<<<<<< HEAD
risultato = prezzo * 1.22
=======
risultato = prezzo * aliquota_iva
>>>>>>> branch-collega

La sezione tra <<<<<<< HEAD e ======= è la tua versione
La sezione tra ======= e >>>>>>> è la versione dell’altro branch

Risolvere il conflitto

Devi modificare il file manualmente, decidendo cosa tenere. Potresti:

tenere la tua versione
tenere la versione altrui
combinare entrambe in una soluzione nuova

Dopo aver deciso, il file deve risultare privo di qualsiasi annotazione <<<<<<<, =======, >>>>>>>. Ad esempio:

risultato = prezzo * aliquota_iva

Poi aggiungi il file risolto e completa il merge:

git add src/calcolo.py
git commit -m "Risolto conflitto nel calcolo dell'IVA"

12. Situazioni di emergenza

Ho fatto un commit con un errore nel messaggio

Se il commit è ancora solo locale (non hai ancora fatto push):

git commit --amend -m "Messaggio corretto"

Ho modificato un file e voglio tornare alla versione dell’ultimo commit

git restore nomefile.py

Attenzione: questa operazione è irreversibile. Le modifiche non committate vengono perse.

Voglio annullare l’ultimo commit ma tenere le modifiche ai file

git reset --soft HEAD~1

Le modifiche tornano nella staging area, pronte per essere ricommittate con un messaggio diverso.

Voglio annullare l’ultimo commit e anche le modifiche ai file

git reset --hard HEAD~1

Attenzione: questa operazione è irreversibile. Usala solo se sei sicuro di non aver bisogno di quelle modifiche.

13. Buone abitudini

Queste pratiche rendono il lavoro più fluido per tutti.

Fai pull prima di iniziare a lavorare. Ogni mattina, prima di aprire qualsiasi file, esegui:

git pull

Evitando di lavorare su una versione vecchia.

Commit piccoli e frequenti. Un commit dovrebbe rappresentare una singola modifica logica. È molto più facile tornare indietro su commit piccoli che su commit enormi che toccano tanti file.

Scrivi messaggi di commit significativi. Il messaggio deve rispondere alla domanda “perché ho fatto questa modifica?“.

Non committare file generati automaticamente. File come .pyc, node_modules/, __pycache__/, *.log, *.tmp non vanno mai committati. Usa il file .gitignore per escluderli automaticamente.

Non committare credenziali o dati sensibili. Password, chiavi API, token di accesso non devono mai finire in un repository, nemmeno privato. Se per errore lo fai, non basta eliminarli in un commit successivo: contatta immediatamente l’amministratore del sistema per revocare le credenziali compromesse.

Una funzionalità, un branch. Non mescolare modifiche diverse nello stesso branch. Tieni separato il lavoro su feature diverse.

Fai push regolarmente. Non tenere giorni di lavoro solo in locale. Pusha almeno una volta al giorno, anche su branch di feature, in modo che il lavoro sia al sicuro sul server e visibile ai colleghi.

14. Riferimento rapido ai comandi

Setup iniziale

Comando	Descrizione
`git config --global user.name "Nome"`	Imposta il nome utente
`git config --global user.email "email"`	Imposta l’email
`git config --list`	Mostra la configurazione attuale

Operazioni sul repository

Comando	Descrizione
`git init`	Inizializza un nuovo repository nella cartella corrente
`git clone URL`	Clona un repository dal server
`git remote -v`	Mostra i repository remoti collegati

Operazioni quotidiane

Comando	Descrizione
`git pull`	Scarica e integra le modifiche dal server
`git status`	Mostra lo stato dei file
`git diff`	Mostra le modifiche riga per riga
`git add nomefile`	Aggiunge un file alla staging area
`git add .`	Aggiunge tutti i file modificati alla staging area
`git commit -m "messaggio"`	Crea un commit
`git push`	Carica i commit locali sul server

Branch

Comando	Descrizione
`git branch`	Elenca i branch locali
`git branch -a`	Elenca tutti i branch (locali e remoti)
`git checkout -b nome`	Crea un nuovo branch e si sposta su di esso
`git checkout nome`	Si sposta su un branch esistente
`git merge nome`	Unisce il branch indicato nel branch corrente
`git branch -d nome`	Elimina un branch locale
`git push origin --delete nome`	Elimina un branch remoto

Storia e ispezione

Comando	Descrizione
`git log`	Mostra la storia dei commit
`git log --oneline`	Mostra la storia in formato compatto
`git log --oneline --graph --all`	Mostra la storia con rappresentazione grafica dei branch
`git show abc1234`	Mostra i dettagli di un commit specifico

Correzioni

Comando	Descrizione
`git restore nomefile`	Annulla le modifiche a un file (irreversibile)
`git restore --staged nomefile`	Rimuove un file dalla staging area
`git commit --amend -m "msg"`	Modifica il messaggio dell’ultimo commit (solo se non ancora pushato)
`git reset --soft HEAD~1`	Annulla l’ultimo commit, mantiene le modifiche in staging
`git reset --hard HEAD~1`	Annulla l’ultimo commit e le modifiche (irreversibile)
`git revert abc1234`	Crea un commit inverso (sicuro, non riscrive la storia)

A4X

Explorer

index