Guida completa Git HTTPS per Forgejo in italiano - Comandi, esempi pratici e troubleshooting

Find a file

emanuelegori 3b4ebb9640 Aggiorna README.md		2025-12-25 20:17:35 +01:00
README.md	Aggiorna README.md	2025-12-25 20:17:35 +01:00

README.md

Guida Git HTTPS per Forgejo/Gitea in Italiano

🎯 Introduzione

Questa guida spiega come utilizzare Git con HTTPS su server Forgejo o Gitea self-hosted.

Compatibilità: Questa guida funziona sia con Forgejo che con Gitea (Forgejo è un fork di Gitea, quindi i comandi sono identici).

HTTPS vs SSH: Quale scegliere?

Entrambi i protocolli permettono di lavorare con Git, ma hanno caratteristiche diverse:

Caratteristica	HTTPS	SSH
Porta	443 (standard web)	22 o custom (es. 2222)
Autenticazione	Username + Password/Token	Chiavi pubbliche/private
Firewall	✅ Passa ovunque	⚠️ Spesso bloccata
Setup	⭐ Semplice	🔧 Richiede chiavi SSH
Sicurezza	✅ TLS/SSL (Let's Encrypt)	✅ Crittografia SSH
Gestione certificati	✅ Automatica	➖ Non applicabile
Superficie attacco	✅ Minore (1 porta)	⚠️ Maggiore (2+ porte)

🔒 Perché HTTPS è sicuro

HTTPS sulla porta 443 è una scelta sicura per server self-hosted:

✅ Meno porte esposte = meno vettori di attacco
✅ Protezione TLS/SSL = traffico crittografato
✅ Certificati Let's Encrypt = autenticità garantita
✅ Reverse proxy = sicurezza centralizzata (NGINX, Traefik, Caddy)
✅ Niente scansioni SSH = evita bot che cercano porte SSH per brute force
✅ Firewall-friendly = funziona ovunque (aziende, hotel, WiFi pubblici)

SSH è utile quando:

Si lavora in team complessi con molti sviluppatori
Serve autenticazione senza password interattiva
Si vuole automatizzare deploy con CI/CD

Per server personali o piccoli team, HTTPS è più che sufficiente!

⚙️ Setup Iniziale

0. Prerequisiti - Installazione Git

Prima di iniziare, è necessario avere Git installato sul proprio computer.

Verifica se Git è già installato:

Apri il terminale/prompt dei comandi:

Windows: Premi Win + R, digita cmd e premi Invio
macOS: Apri Spotlight (Cmd + Spazio) e cerca "Terminale"
Linux: Premi Ctrl + Alt + T o cerca "Terminale" nelle applicazioni

Digita nel terminale:

git --version

Se vedi qualcosa come git version 2.x.x, Git è già installato. Altrimenti, procedi con l'installazione:

Installazione Git:

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install git

Linux (Fedora/RHEL):

sudo dnf install git

macOS:

# Con Homebrew (consigliato)
brew install git

# Oppure scarica da: https://git-scm.com/download/mac

Windows:

Scarica Git da: https://git-scm.com/download/win
Esegui l'installer
Durante l'installazione, usa le opzioni di default
Riavvia il terminale dopo l'installazione

Verifica installazione:

git --version

1. Generare un Personal Access Token (PAT)

Git con HTTPS richiede un token invece della password per maggiore sicurezza.

Sul server Forgejo/Gitea:

Apri il browser e accedi al server (es. https://git.example.com)
Clicca sull'icona del profilo (in alto a destra) → Impostazioni
Nel menu laterale sinistro → Applicazioni → Gestisci Token di Accesso
Clicca il pulsante Genera Nuovo Token
Assegna un nome descrittivo (es. "Laptop Casa", "CI/CD Server")
Seleziona i permessi necessari:
- ✅ repo (accesso completo ai repository)
- ✅ write:repository (push)
- ✅ read:repository (pull/clone)
Clicca Genera Token
Copia il token generato (viene mostrato solo questa volta!)

⚠️ IMPORTANTE: Salva il token in un posto sicuro (password manager) - non sarà più possibile visualizzarlo!

2. Configurazione Git Globale

Ora che Git è installato, è necessario configurare nome e email che appariranno nei commit.

Apri il terminale (vedi sezione 0 per come aprirlo) e digita questi comandi:

# Configura il tuo nome (sostituisci con il tuo nome reale)
git config --global user.name "Nome Cognome"

# Configura la tua email (sostituisci con la tua email)
git config --global user.email "email@esempio.com"

Verifica che la configurazione sia corretta:

git config --list

Dovresti vedere:

user.name=Nome Cognome
user.email=email@esempio.com
...

3. Salvare le Credenziali (Credential Helper)

Per evitare di inserire username e token ad ogni operazione Git, configuriamo il credential helper.

Nel terminale, scegli una delle seguenti opzioni:

Opzione A: Cache temporanea (15 minuti) - Consigliata per iniziare

git config --global credential.helper cache

Aumenta il timeout a 1 ora (opzionale):

git config --global credential.helper 'cache --timeout=3600'

Opzione B: Salvataggio permanente (⚠️ token salvato in chiaro)

git config --global credential.helper store

⚠️ Il token viene salvato in ~/.git-credentials in formato leggibile. Usa questa opzione solo se:

Hai accesso esclusivo al computer
Il disco è criptato
Nessun altro utente può accedere ai tuoi file

4. Primo Repository - Test Configurazione

Ora testiamo la configurazione creando un repository e facendo il primo push. Esistono due approcci:

🎯 Approccio 1: Git Puro (Consigliato)

Questo è il metodo più semplice e usa solo comandi Git. Funziona se il server Forgejo/Gitea ha questa configurazione abilitata:

[repository]
ENABLE_PUSH_CREATE_USER = true

La maggior parte dei server self-hosted ha questa opzione attiva. Se non funziona, usa l'Approccio 2.

Workflow completo:

# 1. Crea cartella e inizializza repository locale
mkdir test-repo-2025
cd test-repo-2025
git init

# 2. Crea file README
echo "# Test Repository 2025" > README.md

# 3. Aggiungi e committa
git add README.md
git commit -m "Initial commit"

# 4. Collega al repository remoto (sostituisci con i tuoi dati)
git remote add origin https://git.example.com/username/test-repo-2025.git

# 5. Push - Crea automaticamente il repo sul server!
git push -u origin master

Cosa succede al punto 5:

Git chiederà le credenziali (solo la prima volta):

Username for 'https://git.example.com': username
Password for 'https://username@git.example.com': [INCOLLA IL TOKEN]

Dopo aver inserito le credenziali:

✅ Il repository viene creato automaticamente sul server
✅ Il codice viene caricato
✅ Le credenziali vengono salvate dal credential helper
✅ Il branch viene configurato per il tracking

Verifica che funzioni:

# Torna indietro e clona
cd ..
git clone https://git.example.com/username/test-repo-2025.git test-clone

# Questa volta NON chiede credenziali! ✅

Se il clone funziona senza chiedere credenziali, tutto è configurato correttamente! 🎉

Nota Git crea una nuova cartella locale del repository remoto che contiene:

tutti i file del progetto
tutta la cronologia dei commit
tutti i branch
tutti i tag
tutta la struttura interna del repository (.git/)

Si ottiene una copia completa del repository remoto sul tuo computer, non una semplice copia dei file.

🔧 Approccio 2: API REST (Universale)

Se l'Approccio 1 non funziona (repository non creato), usa l'API REST di Forgejo/Gitea per creare prima il repository remoto.

Passo 1 - Crea repository con API:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: token IL_TUO_TOKEN_PAT" \
  -d '{
    "name": "test-repo-2025",
    "description": "Repository di test",
    "private": false
  }' \
  https://git.example.com/api/v1/user/repos

Se il comando funziona, vedrai una risposta JSON con i dettagli del repository creato.

Passo 2 - Lavora con Git normalmente:

# Crea repo locale
mkdir test-repo-2025
cd test-repo-2025
git init
echo "# Test Repository 2025" > README.md
git add README.md
git commit -m "Initial commit"

# Collega al remoto (già esistente)
git remote add origin https://git.example.com/username/test-repo-2025.git

# Push (chiederà credenziali)
git push -u origin master

Alternativa veloce - Crea e clona:

Se usi l'API con auto_init: true, il repository viene creato già con README:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: token IL_TUO_TOKEN_PAT" \
  -d '{
    "name": "test-repo-2025",
    "auto_init": true,
    "private": false
  }' \
  https://git.example.com/api/v1/user/repos

# Poi clonalo direttamente
git clone https://git.example.com/username/test-repo-2025.git

📌 Nota importante: Branch master vs main

Git di default crea un branch chiamato master. Molti progetti moderni usano main invece.

Se vuoi usare main come branch predefinito:

# Configura globalmente
git config --global init.defaultBranch main

# Oppure rinomina il branch corrente
git branch -m master main

# Poi fai push con main
git push -u origin main

Da questo momento, tutti i nuovi repository useranno main invece di master.

Nella guida useremo entrambi i nomi, ma ricorda:

master = nome storico di Git (default se non configurato)
main = convenzione moderna (devi configurarla)

Scegli quello che preferisci, basta essere coerente nel tuo progetto!

✅ Verifica finale

Dopo aver completato uno dei due approcci, verifica che tutto funzioni:

# 1. Verifica remote configurato
git remote -v
# Output: origin  https://git.example.com/username/test-repo-2025.git (fetch)

# 2. Verifica branch tracking
git branch -vv
# Output: * master  abc1234 [origin/master] Initial commit

# 3. Prova a fare modifiche
echo "Test modifica" >> README.md
git add README.md
git commit -m "Test commit"
git push  # ← NON chiede credenziali!

# 4. Verifica online
# Apri https://git.example.com/username/test-repo-2025
# Dovresti vedere il repository con i tuoi commit

Se tutto funziona senza chiedere credenziali, la configurazione è perfetta! 🎊

🔐 Credenziali salvate

Dopo il primo push/clone, le tue credenziali sono salvate in:

Cache temporanea: In memoria (15 minuti o timeout configurato)
Store permanente: File ~/.git-credentials

Per vedere il file delle credenziali (se usi store):

cat ~/.git-credentials
# Output: https://username:token@git.example.com

⚠️ Attenzione: Questo file contiene il tuo token in chiaro! Assicurati che solo tu possa leggerlo:

ls -la ~/.git-credentials
# Output: -rw------- 1 user user ... (solo owner può leggere/scrivere)

5. Verifica Configurazione Completa

Se hai completato tutti i passaggi precedenti, fai una verifica finale:

# Controlla configurazione Git
git config --list

# Dovresti vedere:
# user.name=Nome Cognome
# user.email=email@esempio.com
# credential.helper=store (o cache)

Tutto pronto! Ora puoi lavorare con Git e Forgejo/Gitea! 🚀

📚 Documentazione Completa

Per la guida completa a tutti i comandi Git con esempi pratici, consulta il Wiki:

📖 Vai al Wiki Completo

Indice rapido:

🗂️ Comandi Repository - clone, init, remote
📝 Staging e Commit - add, commit, status, diff
🌿 Branching e Merging - branch, checkout, merge, rebase
📜 History - log, show, blame, reflog
🔄 Sincronizzazione - fetch, pull, push
🏷️ Tag - tag operations
💾 Stash - stash operations
⏪ Reset e Undo - reset, revert, restore
ℹ️ Informazioni - ls-remote, describe
📊 Tabella HTTPS vs SSH
🔧 Troubleshooting

🚀 Quick Start

Una volta completato il setup, ecco il workflow base:

# 1. Clone repository (se non l'hai già fatto)
git clone https://git.example.com/username/repo.git
cd repo

# 2. Crea un nuovo branch per le modifiche
git switch -c mia-feature

# 3. Modifica i file con il tuo editor preferito
# (VS Code, Notepad++, nano, vim, ecc.)

# 4. Vedi cosa hai modificato
git status

# 5. Aggiungi i file modificati
git add .

# 6. Crea un commit con un messaggio
git commit -m "Descrizione delle modifiche"

# 7. Scarica eventuali aggiornamenti
git pull origin main

# 8. Invia le modifiche al server
git push origin mia-feature

🔗 Link Utili

Forgejo - Git forge community-driven
Gitea - Self-hosted Git service
Documentazione ufficiale Git
Git Cheat Sheet (PDF)

📝 Note

Sostituzioni necessarie negli esempi:

git.example.com → URL del proprio server Forgejo/Gitea
username → Il proprio username
test-repo-2025 / repository.git → Nome del repository
Nome Cognome → Il proprio nome e cognome
email@esempio.com → La propria email
IL_TUO_TOKEN_PAT → Il token generato al punto 1

❓ Problemi Comuni

"git: command not found" → Git non è installato. Torna alla sezione 0.

"Authentication failed" → Hai inserito la password invece del token PAT. Usa il token generato al punto 1.

"Permission denied" o "403 Forbidden" → Il token non ha i permessi corretti. Rigenera il token con i permessi repo.

"remote: Repository does not exist" (Approccio 1) → Il server non ha ENABLE_PUSH_CREATE_USER = true. Usa l'Approccio 2 con API REST.

Non vedo caratteri quando incollo il token → È normale per sicurezza! Il token è stato incollato. Premi semplicemente Invio.

Per altri problemi, consulta la pagina Troubleshooting nel wiki.

📄 Licenza

Questa guida è rilasciata sotto licenza CC BY-SA 4.0.

Buon lavoro con Git! 🎉

README.md Unescape Escape