Hoe een effectief, nuttig Git Commit-bericht te schrijven

Commit-berichten zijn korte beschrijvingen van elke commit in een versiecontrolesysteem zoals Git. Wanneer u wijzigingen doorvoert in uw projectbestanden, moet u een bericht geven waarin wordt uitgelegd wat ze doen of waarom u ze hebt gemaakt.

Commit-berichten dienen als een vorm van documentatie en communicatie. Ze spelen een cruciale rol bij het bijhouden van een duidelijke en georganiseerde versiegeschiedenis van een project. Leer hoe je goede commit-berichten schrijft en de andere leden van je team zullen je werk nog meer waarderen.

Structuur van een goede commit-boodschap

Een goed voorbeeld van een commit-bericht bestaat uit vier secties: Type, Beschrijving, Hoofdgedeelte en Voettekst.

Zoals zo:

: 
[optionele hoofdtekst]
[optionele voettekst]

Type

Het type beschrijft het soort wijziging dat is gemaakt in de huidige commit. U kunt elk systeem gebruiken dat zinvol is voor uw omstandigheden. Hier zijn bijvoorbeeld enkele voorbeeldzoekwoorden die u kunt gebruiken om elk type wijziging aan te geven, naast voorbeeldgebruik:

• prestatie: uw wijzigingen introduceren een nieuwe functie.
• repareren: u repareert een fout.
• refactoren: uw verandering refactoren code zonder een bug te repareren of een nieuwe functie toe te voegen.
• test: u brengt testgerelateerde wijzigingen aan. Wanneer je bijvoorbeeld schrijf tests met Jest of welke dan ook ander toetsingskader jij kiest.
• klus: wijzigingen die geen verband houden met een fix, functie of test. Bijvoorbeeld het bijwerken van afhankelijkheden.
• documenten: wanneer u de documentatie bijwerkt.
• stijl: wijzigingen die geen invloed hebben op de betekenis van de code, zoals het toevoegen van witruimte, ontbrekende puntkomma's, enz.
• prestatie: wijzigingen met betrekking tot prestatieverbeteringen.
• bouwen: wanneer u wijzigingen aanbrengt die van invloed zijn op de build-bestanden.
• ci: wijzigingen met betrekking tot continue integratie.
• terugdraaien: bij het terugkeren naar een vorige commit.

Beschrijving

De "beschrijving" van een commit-bericht is een beknopte en beschrijvende samenvatting van de wijzigingen die in de commit zijn aangebracht. Het dient als een kop die de essentie van de commit vastlegt.

Houd bij het schrijven van de beschrijving rekening met het volgende:

• Maak het duidelijk en specifiek genoeg om de commit in één oogopslag te beschrijven.
• Maak het kort en bondig. Idealiter zou het het beste zijn om het te beperken tot 50 tekens of minder.
• Schrijf het in de tegenwoordige tijd, zelfs als je reeds aangebrachte wijzigingen beschrijft.
• Maak tijdens het schrijven gebruik van de gebiedende wijs.
• Begin het met een hoofdletter.
• Sluit het niet af met een punt.

Bijvoorbeeld:

prestatie: Implementeer schakelaar voor donkere modus voor startpagina

Dit voorbeeld laat zien hoe je de beschrijving kunt schrijven voor een commit die implementeert de donkere modus. Het gebruikt de prestatie type omdat het een nieuwe functie introduceert.

Lichaam (optioneel)

De body-sectie van een commit-bericht biedt aanvullende details en context over de wijzigingen die in de commit zijn aangebracht. Je hebt niet altijd een instantie nodig, maar het kan helpen om meer informatie te geven, de redenering van een wijziging uit te leggen of technische overwegingen te beschrijven.

Hier zijn enkele dingen om op te letten bij het schrijven van de body-sectie van een commit-bericht:

• Git laat tekst nooit automatisch omlopen, dus wikkel het handmatig om 72 tekens wanneer je de hoofdtekst schrijft. Dit geeft Git voldoende ruimte om tekst in te laten springen, waardoor het leesbaarder wordt.
• Gebruik de hoofdtekst om uit te leggen wat er in de wijziging is gebeurd, waarom u de wijziging hebt aangebracht en de redenering achter uw wijziging.
• U moet een lege regel laten tussen de beschrijvingsregel en de hoofdtekst. Hierdoor kan Git er een onderscheid tussen maken.
• Als de commit meerdere wijzigingen introduceert of verschillende delen van de codebase beïnvloedt, overweeg dan om opsommingstekens of alinea's te gebruiken om de wijzigingen op te splitsen. Dit verbetert de leesbaarheid en helpt lezers de verschillende aspecten van de commit te begrijpen.

Bijvoorbeeld:

prestatie: GitHub toevoegen als OAuth-provider
Integreer GitHub als OAuth-provider om naadloze integratie mogelijk te maken 
authenticatie met GitHub-accounts.
- Implementeer OAuth-authenticatiestroom met GitHub API
- Configureer de benodigde eindpunten en instellingen voor GitHub-authenticatie
- Update de gebruikersinterface om de GitHub-inlogoptie op te nemen

Het bovenstaande voorbeeld toont een goed Git commit-bericht voor een functie die toevoegt GitHub als OAuth-provider naar uw aanvraag. Dit commit-bericht heeft een beknopte samenvattingsregel (50 tekens of minder), een meer gedetailleerde verklarende tekst (verpakt tot ongeveer 72 tekens) en opsommingstekens voor aanvullende informatie.

De voettekstsectie in een commit-bericht is een optioneel onderdeel dat aanvullende informatie of metadata geeft met betrekking tot de commit. Het wordt meestal na het hoofdgedeelte geplaatst, gescheiden door een lege regel. De voettekst kan verschillende soorten informatie bevatten, zoals verwijzingen naar gerelateerde problemen, tags of speciale opmerkingen.

Gebruik bij het verwijzen naar problemen, pull-aanvragen of andere gerelateerde items de juiste syntaxis of indeling die wordt vereist door het systeem voor het volgen van problemen van uw project. Dit zorgt ervoor dat de referenties goed herkend en gekoppeld worden.

Bijvoorbeeld:

prestatie: GitHub toevoegen als OAuth-provider
Integreer GitHub als OAuth-provider om naadloze integratie mogelijk te maken 
authenticatie met GitHub-accounts.
- Implementeer OAuth-authenticatiestroom met GitHub API
- Configureer de benodigde eindpunten en instellingen voor GitHub-authenticatie
- Update de gebruikersinterface om de GitHub-inlogoptie op te nemen
Lost op: #123
Zie ook: #456, #789

De voettekst verwijst naar het gerelateerde probleem #123 en vermeldt andere gerelateerde problemen #456 en #789 voor aanvullende context.

Het Commit-bericht toevoegen

Je kunt commit-berichten schrijven met behulp van de -M vlag gevolgd door het commit-bericht tussen aanhalingstekens (optioneel maar aanbevolen).

De -M flag is ideaal voor korte commit-berichten, meestal inclusief het type en de beschrijving.

Bijvoorbeeld:

git commit -m "karwei: verander linter in ESlint"

Als je commit-bericht echter meer details vereist, zoals een hoofdtekst en een voettekst, kun je de commit beter in een teksteditor of IDE schrijven.

Als alternatief kun je lange commit-berichten in een tekstbestand schrijven en de --bestand flag om de commit-berichten op te geven als de inhoud van het tekstbestand.

Bijvoorbeeld:

git commit --file commit_message.txt

Als je het bovenstaande commando uitvoert, zal git de inhoud van het bestand gebruiken als het commit-bericht.

Je kunt git ook vertellen om je standaard editor te openen om een ​​langer bericht te schrijven. Als je de omgevingsvariabele GIT_EDITOR of EDITOR hebt ingesteld, zal git dat programma openen wanneer je een bare uitvoert git vastleggen commando.

Waarom u goede commit-berichten zou moeten schrijven

Het schrijven van goede commit-berichten is cruciaal voor effectieve samenwerking en codeonderhoud. Duidelijke en beschrijvende berichten helpen bij het begrijpen, debuggen en codebeoordelingen. Ze kunnen zelfs bijdragen aan projectdocumentatie of release-opmerkingen.

Ze maken het delen van kennis, soepele onboarding en ondersteuning voor versiebeheer mogelijk. Het prioriteren van hoogwaardige commit-berichten verbetert ontwikkelingsprocessen en zorgt voor onderhoudbaarheid van de codebase.