Primi passi
Lezione 02 del corso di Digital Humanities e Data Management per i Beni Culturali (2024/2025)
Sebastian Barzaghi | sebastian.barzaghi2@unibo.it | https://orcid.org/0000-0002-0799-1527 | https://www.unibo.it/sitoweb/sebastian.barzaghi2/
Versionamento
Il versionamento è la gestione delle modifiche nei file
La maggior parte delle persone utilizza una qualche forma di versionamento per gestire i propri file.
tesi brutta.docx
tesi brutta2.docx
tesi vera.docx
tesi vera finale.docx
Un buon sistema di versionamento è sistematico
Aggiungere le date rende leggermente più facile seguire quando sono state apportate le modifiche.
tesi_20-03-2024.docx
tesi_06-05-2024.docx
tesi_10-05-2024.docx
tesi_30-05-2024.docx
Un ottimo sistema di versionamento è descrittivo, permissivo, collaborativo
Monitora sviluppi e modifiche nei tuoi documenti, registra le modifiche apportate al tuo documento in un modo che tu possa comprenderle in seguito, permette di annullare le modifiche e tornare a verisoni precedenti, e facilita la collaborazione tra diverse persone per lavorare sullo stesso documento.
Git è un ottimo sistema di versionamento distribuito
Permette di tenere traccia delle modifiche apportate ai file in un progetto.
In pratica, consente di salvare diverse versioni di un file o di un intero progetto nel tempo, così puoi vedere cosa è cambiato, chi ha fatto le modifiche e quando.
Glossario Git
Git (e sistemi costruiti su Git, come GitHub) è basato su una serie di concetti identificati con una terminologia particolare che bisogna riconoscere, studiare e ricordare.
Repository (“repo”)
Cartella contenente tutti i file di un progetto, insieme alla cronologia completa delle modifiche che sono state fatte su di essi.
Commit
Operazione che registra le modifiche apportate ai file in una repository (simile ad una “fotografia” dello stato del progetto in un determinato momento).
Branch
Copia indipendente del progetto ma collegata ad esso, utile per apportare modifiche senza influire sui file originali.
Merge
Operazione che unisce le modifiche fatte in un branch con un’altro branch (di solito quello principale).
Clone
Copia locale di una repository.
Pull
Operazione che scarica le modifiche da una repository remota ad un clone sul tuo computer.
Push
Operazione che invia le modifiche da un clone sul tuo computer ad una repository remota.
Conflict
Evento che si verifica quando si cerca di unire due modifiche incompatibili fatte sugli stessi file in branch diversi.
Fork
Copia online di una repository.
Pull request
Proposta di modifica inviata ad una repository remota.
GitHub è una piattaforma online per repository Git
Permette di caricare, condividere e collaborare su progetti Git con altre persone.
Strumento fondamentale per la comunità open-source e per i progetti aziendali.
Sempre più importante anche per gestire i flussi di lavoro della pubblicazione di riviste, dei libri di testo aperti, e di altri progetti di natura più “umanistica”.
Una panoramica veloce
1. Registriamoci su GitHub
Registriamo un account su GitHub: https://github.com/signup.
2. Dalla home iniziale si può accedere a tutto
3. La barra laterale destra si riferisce al nostro profilo
4. Dal nostro profilo possiamo accedere alle nostre repository
5. Dal nostro profilo possiamo accedere alle nostre repository
6. In una repository vediamo le cartelle e i file che contiene
7. Cliccando su una cartella o file, ne vediamo i contenuti
8. Cliccando su Settings, vediamo le impostazioni della repository
9. Possiamo creare una nuova repository direttamente su GitHub o caricandola da locale
10. Proviamo a crearne una nuova direttamente
11. La nuova repository appena creata
12. Vediamo un file della repository (es. README.md)
13. Proviamo a modificarlo…
14. … Aggiungendo del testo
15. Facciamo un commit delle modifiche appena fatte
16. Le modifiche sono state salvate correttamente
17. Ora proviamo ad interagire con una repository di qualcun’altro
18. Potete clonare l’intera repository in vari modi, incluso un download in formato .zip
19. Ora proviamo a forkare la repository
20. Eseguire un fork è simile a creare una nuova repository
21. La repository da cui abbiamo forkato può subire modifiche nel frattempo…
22. … Ma possiamo ri-allineare il nostro fork molto facilmente
23. Ora il nostro fork è allineato con la repository di origine
24. Se invece vogliamo inviare modifiche dal nostro fork alla repository di origine, dobbiamo mandare un pull request
25. Prima apriamo il pull request
26. Poi verifichiamo che non ci siano conflitti, e facciamo merge
27. Confermiamo il merge tramite un commit
28. Il merge è stato effettuato con successo
29. Possiamo verificarlo anche nella repo di origine
30. Potete creare nuovi file in almeno due modi
31. Potete creare un nuovo file direttamente su GitHub
32. Per confermare la creazione del file, è sufficente eseguire un commit
33. Ora il file è stato creato ed è visualizzabile
34. In alternativa, potete anche caricare un file esistente sul vostro computer
35. Una volta caricato il file, eseguite il commit
36. Di nuovo, ora il file è stato caricato ed è visualizzabile
37. Potete ovviamente eliminare i file
38. Prima di eliminare i file, prima avrete un’anticipazione…
39. … E poi dovrete confermare l’operazione con un commit
40. Ora il file è stato correttamente eliminato
Attività pratica
Obiettivo: creare un file README per il nostro progetto su Mythologiae
Un README è un file di testo che introduce e spiega un progetto, fornendo informazioni necessarie a contestualizzare e comprendere i contenuti, le metodologie, e i risultati.
Si tratta di uno strumento molto semplice ed efficace per comunicare con altre persone potenzialmente interessate al vostro progetto.
Solitamente, è il primo file che viene creato (rigorosamente nella cartella principale), ed è uno dei file da aggiornare in continuazione nel corso del tempo.
Può essere scritto in qualsiasi formato di testo. Solitamente viene usato il Markdown (.md), ma lo vedremo nella prossima puntata. Per ora, limitiamoci ad utilizzare il formato .txt.
1. Troviamo la repo del tutorial
Link: https://github.com/dhdmch/tutorial
Questa sarà la repo di riferimento per le nostre lezioni pratiche.
2. Creiamo un nuovo file e chiamiamolo README.txt
3. Stabiliamo la struttura del nostro README
# Nome
## Descrizione
Il cosa, perché e come del progetto. Qual'è
la motivazione? Quale problema stiamo risolvendo?
Cosa abbiamo imparato?
## Fonti
Link alle fonti dei dati utilizzati
## Metodi e strumenti
Metodologie e/o strumenti utilizzati
## Credits
Contatti di tutte le persone coinvolte
## Licenza
Etichetta e link alla licenza
## Changelog
Sezione dove teniamo traccia di quello che
abbiamo fatto e delle modifiche avvenute
(prima la più recente)
4. Facciamo un commit per salvare il file
5. Modifichiamo il file, inserendo informazioni vere (tra quelle che abbiamo a disposizione)
6. Facciamo un altro commit per salvare le modifiche
7. Ora creiamo due cartelle: una chiamata data, l’altra docs
Non è possibile creare cartelle direttamente su GitHub, quindi le creeremo in locale e le caricheremo.
GitHub non accetta cartelle vuote, quindi dobbiamo riempirle con qualcosa per poterle caricare con successo.
8. Per ora, docs e data conterranno altri README.txt (vuoti)
9. Finalizziamo il caricamento di docs e data con un commit
10. Ora tocca a voi
- Dividetevi in due gruppi
- Forkate la repository
- Un gruppo compilerà il README di
docs - L’altro gruppo si occuperà del README di
data - Una volta modificati i rispettivi documenti, effettuate i pull request
11. README di docs
# Documentazione di progetto
## Indice
- Data Management Plan
## Data Management Plan
### Nome del file
dmp.md
### Descrizione
Piano di gestione dei dati del progetto.
### Data di creazione
2024-11-18
12. README di data
# Dataset utilizzati
## Indice
- Dataset Mythologiae
## Dataset Mythologiae
### Nome del file
dataset_mythologiae.csv
### Descrizione
Dataset contenente i dati degli oggetti appartenenti alla collezione Mythologiae.
### Formato
CSV
Oltre la semplice interfaccia
1. GitHub Desktop
Applicazione ufficiale che offre un’interfaccia grafica per facilitare l’uso di Git e GitHub.
Installazione
Scaricate GitHub Desktop: https://desktop.github.com/download/;
Installate GitHub Desktop seguendo le istruzioni fornite.
Git su linea di comando
Decisamente il metodo migliore, soprattutto per gli sviluppatori.
Richiede un certo tipo di sforzo, ma una volta compresi i concetti di Git e il funzionamento della linea di comando, diventa parte naturale del flusso di lavoro.
git add .
git commit -m "Testo del commit"
git push origin main