Lezione 15 di 35

Git 15

🔀 Git & GitHub · Modulo 3 · Lezione 15

README, licenze e .gitignore 📝

Scrivere un buon README · Markdown · Scegliere una licenza · .gitignore per escludere file indesiderati

⏱️ Durata stimata: 60–75 min 📊 Livello: Intermedio (Modulo 3) 🔧 Strumenti: Terminale · Editor di testo · Repository su GitHub 📋 Prerequisiti: Lezione 14 (sai fare push su GitHub)

📝 Un repository senza README è come un libro senza copertina. Il README è la prima cosa che le persone vedono quando visitano il tuo progetto su GitHub. È la tua occasione per spiegare cosa fa il progetto, come usarlo e come contribuire. In questa lezione impari a scrivere un README professionale in Markdown, a scegliere una licenza e a creare un .gitignore per tenere pulito il repository.

🎯 Obiettivi della lezione

  • Capire l’importanza del README come “biglietto da visita” del progetto
  • Scrivere un README completo usando la sintassi Markdown
  • Conoscere le sezioni standard di un buon README
  • Capire cos’è una licenza software e perché serve
  • Scegliere la licenza giusta per il tuo progetto
  • Creare un file .gitignore per escludere file indesiderati dal repository
  • Usare template .gitignore per i linguaggi più comuni

📖 1. Teoria

1.1 — Il README: la porta d’ingresso del progetto

Quando qualcuno visita il tuo repository su GitHub, la prima cosa che vede (sotto la lista dei file) è il contenuto del file README.md. GitHub lo renderizza automaticamente in HTML con formattazione — titoli, liste, link, immagini, blocchi di codice. È la tua vetrina.

❌ Repository senza README
Il visitatore vede una lista di file senza contesto. Non sa cosa fa il progetto, come installarlo, come usarlo. Se ne va in 5 secondi. Il prof non capisce cosa stai consegnando.
✅ Repository con un buon README
Il visitatore capisce subito: cosa fa il progetto, come installarlo, come usarlo, chi l’ha fatto. Resta, esplora, contribuisce. Il prof vede professionalità e cura.

1.2 — Markdown: il linguaggio del README

Markdown è un linguaggio di formattazione leggero — scrivi testo normale con pochi simboli speciali e GitHub lo renderizza in HTML formattato. L’estensione del file è .md.

Scrivi (Markdown) Ottieni (HTML reso)
# Titolo principale Titolo principale
## Sottotitolo Sottotitolo
### Sezione Sezione
**grassetto** grassetto
*corsivo* corsivo
`codice inline` codice inline
– elemento lista
– altro elemento		 • elemento lista
• altro elemento
1. primo
2. secondo		 1. primo
2. secondo
[testo link](https://url.com) testo link
![alt](immagine.png) (mostra l’immagine)
“`python
print(“ciao”)
“`		 print("ciao") (con syntax highlighting)

1.3 — Le sezioni di un buon README

Non tutti i README hanno bisogno di tutte le sezioni — dipende dalla complessità del progetto. Ma ecco la struttura raccomandata, dalla più semplice alla più completa:

ESSENZIALE
Titolo + descrizione
Cos’è questo progetto? Una frase chiara.
Tutti i progetti
ESSENZIALE
Installazione / Come iniziare
Comandi per installare e far partire il progetto.
Tutti i progetti
CONSIGLIATO
Uso
Esempi di come usare il progetto. Screenshot se è un’app visuale.
Progetti medi+
CONSIGLIATO
Tecnologie usate
Linguaggi, framework, librerie.
Progetti medi+
OPZIONALE
Contribuire
Come gli altri possono contribuire al progetto.
Progetti di gruppo / open source
OPZIONALE
Licenza
Sotto quale licenza è rilasciato il codice.
Progetti pubblici
OPZIONALE
Autori / Crediti
Chi ha lavorato al progetto.
Progetti di gruppo

1.4 — Esempio di README completo

# Calcolatrice Web 🧮

Una calcolatrice semplice e responsive che funziona nel browser.
Progetto scolastico per il corso di Informatica — Classe 4A, A.S. 2025/26.

## Funzionalità

– Operazioni base: +, -, ×, ÷
– Cronologia delle operazioni
– Tema chiaro e scuro
– Funziona su desktop e mobile

## Come iniziare

1. Clona il repository:
“`bash
git clone git@github.com:tuousername/calcolatrice-web.git
cd calcolatrice-web
“`
2. Apri `index.html` nel browser.

## Tecnologie

– HTML5
– CSS3 (Flexbox, variabili CSS)
– JavaScript (vanilla, nessun framework)

## Autori

– **Marco Rossi** — interfaccia e stili
– **Giulia Bianchi** — logica della calcolatrice
– **Luca Verdi** — cronologia e localStorage

## Licenza

MIT License — vedi [LICENSE](LICENSE) per i dettagli.

1.5 — Licenze: chi può usare il tuo codice?

Quando pubblichi codice su GitHub, senza una licenza nessuno ha il diritto legale di usarlo, copiarlo o modificarlo — anche se il repository è pubblico. La licenza è un file (LICENSE) che dichiara cosa gli altri possono fare con il tuo codice.

Licenza Permette Richiede Ideale per
MIT ⭐ Tutto: usare, copiare, modificare, vendere Mantenere il copyright originale Progetti scolastici, librerie, codice che vuoi condividere liberamente
Apache 2.0 Come MIT + protezione da brevetti Copyright + documentare le modifiche Progetti aziendali, librerie professionali
GPL v3 Usare, copiare, modificare Il codice derivato deve essere GPL (copyleft) Software che vuoi rimanga sempre open source
Nessuna licenza Niente — il codice è “tutti i diritti riservati” — Mai consigliato per repo pubblici

📌 Per i progetti scolastici: usa la licenza MIT. È la più semplice e permissiva — dice sostanzialmente “fai quello che vuoi, basta che mantieni il mio nome”. È la licenza più popolare su GitHub. Per aggiungerla: quando crei il repository su GitHub, seleziona “MIT License” dal menu delle licenze. Oppure crea un file LICENSE copiando il testo da choosealicense.com/licenses/mit.

1.6 — .gitignore: escludere file dal repository

Non tutti i file devono andare nel repository. File temporanei, password, configurazioni locali, cartelle di dipendenze — tutti questi inquinano il repo e a volte creano problemi di sicurezza. Il file .gitignore dice a Git quali file ignorare.

Tipo di file Esempio Perché ignorarlo
Credenziali e segreti .env, passwords.txt, api_keys.json Sicurezza! Password e token nel repo = compromessi.
Dipendenze installate node_modules/, venv/, vendor/ Pesanti (centinaia di MB) e ricostruibili con un comando.
File compilati / build dist/, build/, *.class, *.o Generati automaticamente dal codice sorgente.
File del sistema operativo .DS_Store (macOS), Thumbs.db (Win) File nascosti creati dal OS — inutili nel progetto.
File dell’IDE / editor .vscode/, .idea/, *.swp Configurazioni personali dell’editor — ogni sviluppatore ha le sue.
Log e cache *.log, .cache/, tmp/ File temporanei che cambiano continuamente — sporcano la storia.

1.7 — Sintassi del .gitignore

# Questo è un commento

# Ignora un file specifico
passwords.txt

# Ignora tutti i file con una certa estensione
*.log
*.tmp

# Ignora un’intera cartella
node_modules/
dist/
build/

# Ignora file di sistema
.DS_Store
Thumbs.db

# Ignora le configurazioni dell’editor
.vscode/
.idea/

# Ignora file .env (contengono variabili d’ambiente / segreti)
.env
.env.local

# Eccezione: NON ignorare questo file specifico (con !)
!.env.example
Regole della sintassi .gitignore
file.txt Ignora il file file.txt ovunque nel progetto
cartella/ Ignora l’intera cartella e tutto il suo contenuto. Lo slash finale indica “è una cartella”.
*.log Ignora tutti i file che terminano con .log. L’asterisco è un wildcard.
!importante.log Eccezione: non ignorare questo file anche se corrisponde a *.log.
# Commento — ignorato da Git. Usa per spiegare le regole.
**/logs Ignora la cartella logs a qualsiasi profondità nell’albero delle cartelle.

⚠️ .gitignore funziona solo sui file non ancora tracciati. Se hai già committato un file e poi lo aggiungi al .gitignore, Git continua a tracciarlo. Per smettere di tracciare un file già committato: git rm --cached file.txt (lo rimuove dal tracking ma lo lascia sul disco), poi committa. Da quel momento il .gitignore lo ignorerà.

1.8 — Template .gitignore per linguaggi comuni

GitHub fornisce template .gitignore pronti per ogni linguaggio. Li trovi su github.com/github/gitignore. Quando crei un repository su GitHub, puoi selezionare un template dal menu “Add .gitignore”.

Progetto web (HTML/CSS/JS)
node_modules/
dist/
.env
.DS_Store
*.log
Progetto Python
__pycache__/
*.pyc
venv/
.env
*.egg-info/
Progetto Java
*.class
target/
.idea/
*.jar
*.war

💻 2. Esempi guidati

Esempio A — Creare un README da zero

$ cd ~/Desktop/mio-progetto

# Crea il README con l’editor (o con cat)
$ cat > README.md <<‘EOF’
# Mio Progetto 🚀

Un progetto di esempio per imparare Git e GitHub.

## Come iniziare

“`bash
git clone git@github.com:tuousername/mio-progetto.git
cd mio-progetto
“`

## Autore

– **Mario Rossi** — [github.com/mario-rossi](https://github.com/mario-rossi)

## Licenza

MIT
EOF

$ git add README.md
$ git commit -m “Aggiunto README con descrizione e istruzioni”
$ git push

Esempio B — Creare un .gitignore per un progetto web

$ cat > .gitignore <<‘EOF’
# Dipendenze
node_modules/

# Build
dist/
build/

# Variabili d’ambiente
.env
.env.local

# Sistema operativo
.DS_Store
Thumbs.db

# Editor
.vscode/
.idea/

# Log
*.log
EOF

# Verifica che funzioni
$ mkdir node_modules && echo “test” > node_modules/test.js
$ git status
# node_modules/ NON appare — il .gitignore lo ignora!

$ git add .gitignore
$ git commit -m “Aggiunto .gitignore per progetto web”
$ git push

Esempio C — Smettere di tracciare un file già committato

# Oops: hai committato un file .env con le password
$ echo “.env” >> .gitignore ← aggiungi al .gitignore

# Ma .env è già tracciato! Il .gitignore da solo non basta.
# Devi rimuoverlo dal tracking (ma tenerlo sul disco):
$ git rm –cached .env
rm ‘.env’ ← rimosso dal tracking, NON dal disco

$ git status
deleted: .env ← Git lo vede come “cancellato” dal repo
modified: .gitignore

$ git commit -m “Rimosso .env dal tracking e aggiornato .gitignore”
$ git push

# Il file .env è ancora sul tuo disco ma non è più nel repository.
$ ls .env ← esiste ancora!
$ git status ← .env non appare (ignorato dal .gitignore)

🏋️ 3. Esercizi

🟢 Esercizio 1 — Il tuo primo README (Facile)

a) Prendi uno dei tuoi repository su GitHub (o creane uno nuovo).
b) Crea un file README.md con almeno: titolo, descrizione, sezione “Come iniziare” e autore.
c) Committa e pusha.
d) Vai su GitHub nel browser — il README viene renderizzato correttamente sotto la lista dei file?
e) Aggiungi un’emoji nel titolo (es. 🚀). Pusha. Si vede su GitHub?

🔵 Esercizio 2 — .gitignore in azione (Medio)

a) Nel tuo repository, crea un file .gitignore che ignora: *.log, .env, node_modules/, .DS_Store.
b) Committa il .gitignore.
c) Crea i file: errori.log, .env, una cartella node_modules/ con un file dentro, e codice.js.
d) Esegui git status. Quali file appaiono? (Solo codice.js — gli altri sono ignorati.)
e) Aggiungi e committa codice.js. Verifica che i file ignorati non siano nel commit con git show --stat HEAD.

🟠 Esercizio 3 — Rimuovere un file già tracciato (Medio)

a) Crea un file segreto.txt con il testo “password123”. Fai add e commit. (Oops!)
b) Aggiungi segreto.txt al .gitignore.
c) Esegui git status — il file appare ancora? (Sì! Il .gitignore non agisce su file già tracciati.)
d) Rimuovi dal tracking: git rm --cached segreto.txt.
e) Committa. Verifica con git status che il file non sia più tracciato.
f) Verifica che il file segreto.txt sia ancora sul disco: ls segreto.txt.

🟣 Esercizio 4 — README professionale completo (Difficile)

Crea un repository portfolio-progetto su GitHub con tutti e tre i file professionali:

a) README.md completo con: titolo + emoji, descrizione (2-3 frasi), funzionalità (lista puntata), “Come iniziare” con blocco di codice bash, tecnologie usate, screenshot (puoi usare un placeholder: ![Screenshot](screenshot.png)), sezione autori con link al profilo GitHub, licenza.

b) .gitignore per un progetto web (node_modules, .env, .DS_Store, log, editor config).

c) LICENSE — scarica il testo della licenza MIT da choosealicense.com e crea il file.

d) Committa tutto e pusha. Visita il repository su GitHub: il README è renderizzato? La licenza è riconosciuta? (GitHub mostra un badge “MIT License” nella sidebar.)

e) Chiedi a un compagno di visitare il tuo repository e dirti se capisce cosa fa il progetto in meno di 30 secondi.

❓ 4. Quiz di verifica

1. Perché è importante avere un README nel repository?

Mostra risposta

Il README è la prima cosa che le persone vedono quando visitano il tuo repository su GitHub — è il “biglietto da visita” del progetto. Senza README, il visitatore vede solo una lista di file senza contesto e non sa cosa fa il progetto, come installarlo o come usarlo. Un buon README comunica professionalità, facilita la collaborazione (i compagni sanno come contribuire), aiuta il prof a capire cosa stai consegnando, e se il progetto è pubblico, attira potenziali contributori o datori di lavoro.

2. Se un repository pubblico su GitHub non ha una licenza, cosa possono fare gli altri con il codice?

Mostra risposta

Legalmente, niente. Senza licenza, il codice è sotto “tutti i diritti riservati” — nessuno ha il permesso di usarlo, copiarlo, modificarlo o distribuirlo, anche se il repository è pubblico e chiunque può vederlo. Il fatto che il codice sia visibile non significa che sia utilizzabile. Per permettere agli altri di usare il tuo codice, devi aggiungere esplicitamente una licenza (come MIT, Apache o GPL). Per i progetti scolastici, la licenza MIT è la scelta più semplice e permissiva.

3. Hai aggiunto node_modules/ al .gitignore, ma git status continua a mostrare file dentro node_modules. Perché?

Mostra risposta

Probabilmente la cartella node_modules/ era già stata aggiunta al tracking prima che il .gitignore fosse creato. Il .gitignore funziona solo sui file non ancora tracciati — non ha effetto sui file che Git sta già tracciando. Per risolvere: git rm -r --cached node_modules/ (rimuove dal tracking tutta la cartella ma la lascia sul disco), poi committa. Da quel momento, il .gitignore impedirà che venga ri-tracciata.

4. Qual è la differenza tra git rm file e git rm --cached file?

Mostra risposta

git rm file rimuove il file sia dal tracking di Git che dal disco — il file viene cancellato fisicamente. git rm --cached file rimuove il file solo dal tracking di Git ma lo lascia sul disco — il file resta nella tua cartella ma Git smette di seguirlo. Il secondo è quello che usi quando vuoi smettere di tracciare un file (per poi ignorarlo con .gitignore) senza cancellarlo dal tuo computer.

5. Cosa fa la riga !.env.example in un .gitignore che contiene anche .env?

Mostra risposta

Il punto esclamativo ! è una negazione: dice a Git “non ignorare questo file, anche se corrisponde a una regola precedente”. In questo caso, .env ignora tutti i file che si chiamano .env o iniziano con .env, ma !.env.example fa un’eccezione per .env.example. È una pratica comune: il file .env.example contiene le variabili d’ambiente senza i valori reali (es. API_KEY=inserisci_qui) come modello per i compagni — va nel repository. Il vero .env con i valori segreti resta ignorato.

6. Come si formatta un blocco di codice in Markdown?

Mostra risposta

Con tre backtick (```) prima e dopo il blocco. Per attivare il syntax highlighting (colorazione del codice), aggiungi il nome del linguaggio dopo i primi tre backtick: ```javascript per JavaScript, ```python per Python, ```bash per comandi da terminale. Per codice inline (nel mezzo di una frase), usa un singolo backtick: `variabile`. GitHub renderizza automaticamente il blocco con sfondo grigio e colorazione del codice appropriata per il linguaggio indicato.

📚 Riepilogo della lezione

Cosa hai imparato oggi:
  • README.md: il biglietto da visita del progetto — GitHub lo renderizza in HTML
  • Markdown: # titoli, **grassetto**, - lista, [link](url), ```blocco codice```
  • Sezioni essenziali: titolo + descrizione, come iniziare, autore
  • Licenza: senza licenza = tutti i diritti riservati. Per la scuola: MIT
  • .gitignore: dice a Git quali file ignorare — credenziali, dipendenze, file di sistema
  • Sintassi: file.txt (file), cartella/ (cartella), *.log (wildcard), !eccezione
  • .gitignore non agisce su file già tracciati — serve git rm --cached prima
  • Template pronti su github.com/github/gitignore

Prossima lezione →

Lezione 16 — GitHub Issues
Creare, assegnare, etichettare e chiudere issue.
Referenziare issue nei commit. Template per issue.

Corso Git & GitHub · Per studenti e insegnanti · Lezione 15 di 45