Git è lo strumento di versionamento più usato ad oggi, sia in ambito universitario che aziendale. Nel 2017 la stessa Microsoft ha concluso la titanica impresa (durata due anni) di spostare tutto il codice sorgente di nientemeno che Windows da un certo “Source Depot” sviluppato internamente.
Imparare ad usare le funzioni basilari è semplice ma Git non è uno strumento semplice, è eccezionale. Con il passare del tempo si possono imparare funzionalità avanzate e linee guida per valorizzare appieno tutta la sua potenza.
In questo articolo analizziamo la funzionalità più basilare, utilizzata e apparentemente semplice: scrivere i messaggi nelle commit.
“Meno scrivo, meglio è”
Tutti iniziamo ad usare Git con il comando `git commit -m “Il messaggio qui”`. Ma non è il modo consigliato, perché le modifiche vengono descritte in maniera molto limitata e senza una struttura. Il testo ben costruito può spiegare cosa è stato modificato, perché e come (What, Why, How).
Se non hai mai dedicato tempo a pensare come rendere ideale il messaggio di una commit probabilmente è perché non hai mai speso molto tempo nell’uso del log (la storia dei commit) dei tuoi repository Git. Si è creato un ciclo vizioso: i messaggi rendono la storia inconsistente e non strutturata. E siccome non viene usata, rimarrà inconsistente e non strutturata. (Grazie Chris Beams)
I software, soprattutto aziendali, hanno un ciclo di vita duraturo. Ogni volta che si devono fare modifiche al codice gli sviluppatori possono analizzare il contesto, contattare chi se ne è occupato in precedenza e assegnargli il lavoro. Lui usa le proprie conoscenze per svolgere il lavoro velocemente e con precisione.
Ma scegliere questa strada crea un collo di bottiglia, si vincola fortemente il codice ad una singola persona. Potrebbe essere in vacanza, aver cambiato ufficio o città, essersi licenziato. Può anche tornare sul proprio codice e non riuscire a ricordare informazioni indispensabili.
Le informazioni sono perse. Il codice deve essere letto da cima a fondo per comprenderne il funzionamento. Si investirà molto tempo per capire come è stato implementato (How), ma sarà ancor più complesso comprendere cosa è stato modificato (What) e, soprattutto, perché la modifica è stata fatta (Why).
These days I look at git logs more often than at code. The git log tool is vastly superior to CVS log and the commit discipline in the projects I’m working on now is a lot better. I grep git logs more often than code files and I use git blame all the time to figure out why a particular piece of code looks the way it does. It’s certainly saving me a lot of time and effort. – Peter Hutterer Don Norman, celebre psicologo e autore del libro “The Design of Everyday Things”, consiglia “Use knowledge in the real world and in the head”: per ricordare le informazioni con minor fatica e maggior sicurezza consiglia di memorizzarne una parte nella mente e una parte “nel mondo”, salvando le informazioni in luoghi in cui sapremo ritrovarle. Git, ad esempio. Una prima infarinatura è già presente nella man page di `git commit`. Le linee guida consigliano quindi di usare il semplice comando `git commit` per aprire un editor di testo, e usarlo per scrivere il messaggio del commit con la seguente struttura: Git usa vim o emacs come predefinito. Si può scegliere un altro editor con interfaccia testuale o con interfaccia grafica. La prima riga contiene l’oggetto, o titolo, che descrive in maniera significativa e coincisa la modifica del commit. Si consiglia inoltre di usare al massimo 50/80 caratteri, a seconda del limite scelto in ogni progetto. Alcuni gestori di repository Git, come GitHub, usano punti di sospensione per accorciare titoli scritti con troppi caratteri. Gitkraken ti aiuta a contarli nello stesso modo dei cellulari per gli SMS. Il titolo deve essere seguito da una riga bianca, come separatore, e poi dal corpo del testo. Qui si può scrivere con maggiore libertà con lo scopo di riportare tutte le informazioni che aiuteranno i vostri colleghi e voi stessi non appena verranno dei dubbi. Ricordo che si possono riportare tre cose: What, Why e How. Cosa è stato fatto con questo commit, perché si è scelto di fare questa modifica e come è stata fatta. I client Git grafici spesso guidano nell’usare questa semplice struttura. GitHub Desktop mostra un campo per l’oggetto e un campo per il corpo del testo. Traduzione dell’esempio di un ottimo commit da parte di Tim Pope: Concludo assicurandoti che ogni commit richiede questi standard, nel tempo adottati da tutti i repository più famosi come Linux, Spring Boot, Angular e lo stesso Git. Di seguito alcuni link per continuare ad approfondire le tue conoscenze su Git: How To Write Proper Git Commit Messages, Stephen AmazaLinee guida
DISCUSSION
Though not required, it’s a good idea to begin the
commit message with a single short (less than 50
character) line summarizing the change, followed by a
blank line and then a more thorough description. The
text up to the first blank line in a commit message is
treated as the commit title, and that title is used
throughout Git. For example, git-format-patch(1) turns a
commit into email, and it uses the title on the Subject
line and the rest of the commit in the body.
Ultimi consigli per mantenere una struttura efficiente e leggibile:
Riassume le modifiche in circa 50 caratteri o meno
Aggiungi un testo esplicativo con più dettagli, se necessario. Vai a
capo a circa 72 caratteri o giù di lì. In alcuni contesti, la prima
linea è trattata come l'oggetto del commit e il resto del testo come il
corpo. La linea vuota che separa l'oggetto dal corpo è fondamentale (a
meno che non ometti interamente il corpo); varie funzionalità come
`log`, `shortlog` e `rebase` possono confondersi se non li separi.
Spiega il problema che questo commit sta risolvendo. Concentrati sul
motivo per cui stai apportando questa modifica rispetto al come (il
codice lo chiarirà). Ci sono degli effetti collaterali o altre
conseguenze non intuitive di questo cambiamento? Questo è il posto
giusto per spiegarle.
Ulteriori paragrafi seguono altre righe vuote.
- Anche gli elenchi puntati vanno bene
- Tipicamente si usano trattini o asterischi per i punti elenco,
preceduti da un singolo spazio, separati da linee vuote, ma queste
convenzioni variano
Se usi un gestore delle issue, inserisci i loro riferimenti in fondo,
in questo modo:
Risolve: #123
Vedi anche: #456, #789
Commit Message Guidelines, Angular Contributing
Pro Git Ebook, Scott Chacon, Ben Straub