Varför du ska bry dig om dina commit meddelanden
Jag ska erkänna att jag inte alltid har funderat så mycket på att skriva meningsfulla commit meddelanden.
När jag började lära mig Git tyckte jag att commit meddelandena kändes onaturliga och bara var ett onödigt extrasteg – speciellt när det vara nära en deadline och jag behövde få skiten att funka.
För att illustrera hur jag ibland behandlade mina commit meddelanden så bjuder jag här på mitt sämsta (och roligaste) meddelande:
Om någon skulle läsa detta meddelande i efterhand så skulle det vara svårt att förstå vad ändringen gör – och det är den viktigaste anledningen till att skriva bra commit meddelanden.
Här följer tre tips som har hjälpt mig att förbättra mina commit meddelanden. Jag hoppas att även du har nytta av de.
Tips #1: Skriv vad och varför en ändring har gjorts
Det viktigaste med ett meddelande är att beskriva vad som har förändrats och varför.
Du kan se loggen i Git som en minidokumentation av projektet. En bra dokumentation är tydlig och innehåller svaret på dina potentiella frågor.
Efter att jag började jobba med Git i ett team så har det blivit mer och mer tydligt för mig hur viktiga commit meddelandena är.
Jag har tappat räkningen på hur många gånger jag har behövt gå tillbaka i historiken för att kolla varför en ändring gjordes och sedan mötts av en intetsägande commit. Sjukt frustrerande.
Var en kompis – skriv tydliga meddelanden.
Värt att notera: Det är inte alltid är värdefullt att skriva varför något har gjorts, t.ex. om du rättar en felstavning. Samma sak om du fixar en bugg. Skriv inte varför du fixade buggen (för det är uppenbart), skriv istället vad buggen orsakade för problem och hur du löste det.
Tips #2: Skriv dina ändringar som ett mejl
Ett supertips som jag stötte på när jag lyssnade på ett poddavsnitt om commit meddelanden var att du kan tänka att du skriver ett mejl: En kort rubrik följt av själva innehållet.
Du kanske inte vet detta men ett commit meddelande består av en titel och en body.
Om du använder något verktyg för Git så kan du ha sett att det finns två olika fält för att skriva ett commit meddelanden. Dessa två fält representerar titeln och bodyn.
Om du använder terminalen så är detta mindre uppenbart. I terminalen skulle det kunna se ut så här:
git commit -m"Rubriken av meddelandet följt av en tom rad
>
> Bodyn som innehåller mer utförlig information om ändringen."
Rubriken ska vara kort och koncis (helst under 50 tecken) och sammanfatta vad commiten gör. Bodyn (som är valbar) kan vara mer utförlig och t.ex. beskriva varför en ändring har gjorts.
Tips #3: Skriv commit meddelandet som en uppmaning
Standarden är att skriva sina meddelanden i imperativ. Kortfattat är imperativ en uppmaning, t.ex. öppna dörren, gå ut med soporna och släck lampan.
Detta kan vara lite klurigt att ta till sig. Jag är nog inte ensam om att naturligt vilja skriva mina meddelanden som någonting jag har gjort, t.ex.
- Fixade en bugg.
- Publicerade ett inlägg.
- Uppdaterade startsidan.
I imperativ skulle vi istället skriva:
- Fixa en bugg.
- Publicera ett blogginlägg.
- Uppdatera startsidan.
Varför ska man skriva sina meddelanden i imperativ?
Jag ska vara ärlig och säga att jag inte har hittat någon definitiv anledning till varför man “ska” skriva sina meddelanden i imperativ med än att det är en standard. De flesta brukar hänvisa till att Git i sig är skrivet i imperativ, t.ex. Merge <branch> into main.
Jag kikade igenom en tråd på hacker news som diskuterade just detta och här är två anledningar som jag känner resonerade med mig:
[…] the log is not a history of your actions, but a description of what that particular revision does. So if i take the diff and apply it to my tree, the log tells me what it will do.
[…] I keep a running todo list of things I’m working on. When I complete a task, the todo becomes the commit message […].
Hur skriver man sina meddelanden i imperativ?
Du kan tänka på ditt meddelande som en punkt på din att-göra-lista:
- Publicera blogginlägg.
- Städa bort gammal kod.
Du kan även mentalt börja varje meddelande med “If applied, this commit will…” så kommer du höra vad som är rätt och fel.
Testa meningen framför nedanstående meddelanden. De som låter rätt är skrivna i imperativ.
- … add blog post about Git
- … fix bug that cause issues
- … updated info on startpage
- … restore previous commit
- … removes unsed images
Bonustips: Öva!
Sedan jag började använda Git mer seriöst i mina hobbyprojekt så känner jag att har jag blivit bättre på att skriva commit meddelanden.
Att öva på att skriva commit meddelanden på fritiden när det inte finns någon deadline att förhålla sig till, har hjälpt mig att ta ett steg tillbaka och fundera på hur jag bäst sammanfattar vad jag har gjort.
Det kan ha hänt att jag har spenderat lite för mycket tid på att gå igenom mina ändringar för att dela upp de i fina, tydliga, avgränsande commits – men det man övar blir man bra på, så det är mitt sista tips till dig.