Git-commitbericht: de regels, voorbeelden en conventies

Waarom een Git-commitbericht ertoe doet

Een commitbericht legt je wijzigingen uit aan iedereen die de code later leest, inclusief jijzelf in de toekomst.

Over drie maanden weet je niet meer waarom je die datapijplijn refactorde of waarom je voor een specifieke bewerking van pandas naar polars overstapte. Je commitbericht is het enige verslag van je redenatie. Zonder dat blijf je gissen of graaf je door Slack-threads en JIRA-tickets.

Hier zijn nog een paar concrete redenen waarom een git-commitbericht ertoe doet.

Code reviews gaan sneller met duidelijke commitberichten. Je reviewer kan het bericht scannen, de intentie begrijpen en focussen op of de implementatie daarmee overeenkomt. Vage berichten dwingen reviewers om je denkproces terug te redeneren uit alleen de diff.

Debuggen wordt ook makkelijker. Als er een bug opduikt, gebruik je git log of git blame om te traceren wanneer de problematische code is geïntroduceerd. Een bericht als "fix authentication bug" vertelt je niets. Een bericht als "fix token expiration check in auth middleware" wijst je rechtstreeks naar het probleem.

Samenwerking in het team hangt af van leesbare geschiedenis. Als iemand bij je project komt of oppakt waar jij was gebleven, leest diegene commits door om te begrijpen hoe de codebase zich ontwikkelde. Duidelijke berichten veranderen je Git-geschiedenis in documentatie die echt helpt.

Kortom: een beschrijvend commitbericht kost 15-30 seconden om te schrijven, maar bespaart later uren aan verwarring.

Kernprincipes van een goed Git-commitbericht

Goede commitberichten volgen een paar eenvoudige principes - meer is het niet.

Schrijf voor toekomstige lezers

Je commitbericht is niet voor jou nu - het is voor wie het over zes maanden leest.

Die persoon kan een nieuw teamlid zijn dat wil begrijpen waarom de codebase op een bepaalde manier werkt. Het kan jijzelf zijn, die probeert te herinneren waarom je een specifieke beslissing nam. Hoe dan ook, ze hebben niet de context die jij vandaag hebt.

Focus op intentie en redenatie, niet alleen op wat er veranderde. De diff laat zien wat er veranderde. Jouw bericht moet uitleggen waarom het veranderde en welk probleem het oplost.

Wees duidelijk en beknopt

Korte, beschrijvende berichten zijn makkelijker te scannen als je door tientallen commits bladert.

Een bericht als "add caching" is vaag. Een bericht als "add Redis caching for API responses" vertelt je precies wat er gebeurde. Je kunt het in git log --oneline lezen en meteen weten wat de commit doet.

Je onderwerpregel moet beantwoorden: wat doet deze commit? Als je meer dan 50-60 tekens nodig hebt om dat te beantwoorden, commit je waarschijnlijk te veel wijzigingen tegelijk.

Wees consistent

Consistentie in je repository maakt de geschiedenis voorspelbaar en makkelijker te parsen.

Als elke commit hetzelfde formaat volgt, kun je snel door de geschiedenis scannen. Je weet waar je het type wijziging, de scope en de beschrijving vindt. Teams die consistente formaten afdwingen, kunnen ook taken automatiseren zoals changelogs genereren of commits filteren op type.

Kies een stijl en hou je eraan. Als je team de gebiedende wijs in tegenwoordige tijd gebruikt, schakel dan niet willekeurig over naar de verleden tijd.

Leg uit wat en waarom (niet hoe)

De code laat zien hoe je het probleem oploste. Je commitbericht moet uitleggen wat het probleem was en waarom je voor deze oplossing koos.

Schrijf niet "refactored load_data() to use list comprehension instead of for loop." Schrijf "speed up data loading by 40% for large CSV files." Het eerste bericht beschrijft de codewijziging. Het tweede legt de impact uit.

Voeg context toe wanneer dat toekomstige lezers helpt je beslissing te begrijpen. Als je drie verschillende aanpakken probeerde voordat je voor deze koos, noem dat dan. Als er een gerelateerd bugrapport of ontwerppatroon is, verwijs ernaar.

De structuur van een Git-commitbericht

De meeste Git-commitberichten volgen een standaard driedelige structuur: onderwerpregel, body en footer.

Onderwerpregel

De onderwerpregel is een samenvatting op één regel die verschijnt in git log --oneline en pull request-lijsten.

Houd hem indien mogelijk onder de 50 tekens, 72 maximaal. Deze limiet garandeert dat het bericht goed wordt weergegeven in terminaloutput en de UI van GitHub zonder te worden afgekapt. Als je je samenvatting niet in 50 tekens past, probeer je waarschijnlijk te veel wijzigingen in één commit te beschrijven.

Gebruik de gebiedende wijs - schrijf "add feature" in plaats van "added feature" of "adds feature." Zie het als het aanvullen van de zin "If applied, this commit will...". Dus "If applied, this commit will add Redis caching" leest natuurlijk, terwijl "If applied, this commit will adds Redis caching" dat niet doet.

Voorbeelden:

• fix null pointer exception in data loader

• add caching layer for API responses

• remove deprecated pandas functions

Body (wanneer nodig)

Sla de body over voor eenvoudige wijzigingen. Als je onderwerpregel de commit volledig uitlegt, ben je klaar.

Voeg een body toe wanneer je moet uitleggen waarom je de wijziging hebt aangebracht of context moet bieden die toekomstige lezers helpt. Laat een lege regel tussen onderwerp en body - Git gebruikt die om de twee delen te scheiden.

De body moet vragen beantwoorden als: Welk probleem lost dit op? Waarom koos je voor deze aanpak? Zijn er bijwerkingen of beperkingen? Heb je andere oplossingen overwogen?

Regelafbreking op 72 tekens om de tekst leesbaar te houden in de terminal. De meeste teksteditors kunnen dit automatisch doen.

Voorbeeld:

add Redis caching for API responses

API response times were hitting 2-3 seconds for repeated queries.
Added Redis with 5-minute TTL to cache query results. This drops
response time to ~50ms for cached queries.

Considered using in-memory cache but Redis lets us scale horizontally
if needed.

Footer (optioneel)

Gebruik de footer om gerelateerde issues, pull requests of breaking changes te verwijzen.

Als je commit een GitHub-issue oplost, voeg dan Fixes #123 of Closes #456 toe in de footer. GitHub sluit het issue automatisch wanneer de commit merge’t. Voor breaking changes voeg je BREAKING CHANGE: toe, gevolgd door een beschrijving van wat er brak en hoe je kunt migreren.

Voorbeeld:

remove support for Python 3.7

Python 3.7 reached end-of-life in June 2023. This commit drops
support and updates minimum version to Python 3.8.

BREAKING CHANGE: Python 3.7 users must upgrade to 3.8 or later.
Closes #789

Je hebt voor de meeste commits geen footer nodig - alleen wanneer je linkt naar externe referenties of breaking changes markeert.

Veelvoorkomende typen Git-commitberichten en wanneer je ze gebruikt

Veel projecten gebruiken commit-typeprefixen om wijzigingen in één oogopslag te categoriseren.

Je hoeft geen strikte lijst met labels te onthouden. Het doel is lezers te helpen snel te herkennen wat voor soort wijziging er is gebeurd zonder de volledige diff te lezen.

Hier zijn vier categorieën om te kennen:

• Featurewijzigingen introduceren nieuwe functionaliteit. Gebruik prefixen zoals feat: of add: wanneer je iets nieuws bouwt - een nieuwe API-endpoint, een dataprosesseringsfunctie of een user-facing feature. Voorbeeld: feat: add CSV export for analysis results.

• Bugfixes lossen bestaande problemen op. Gebruik fix: wanneer je gedrag corrigeert dat niet werkte zoals bedoeld. Dit kan variëren van een null pointer-exception tot onjuiste berekeningen in je model. Voorbeeld: fix: handle missing values in preprocessing pipeline.

• Documentatie-updates verbeteren codecomments, README-bestanden of inline documentatie. Gebruik docs: wanneer je niet verandert hoe de code werkt, maar het beter uitlegt. Voorbeeld: docs: add usage examples for data loader class.

• Refactoring en onderhoudswerk verbeteren de structuur van de code zonder het gedrag te veranderen. Gebruik refactor: wanneer je code herorganiseert om hem schoner of beter onderhoudbaar te maken. Gebruik chore: voor routinetaken zoals het updaten van dependencies of het wijzigen van buildconfiguraties. Voorbeelden: refactor: extract validation logic into separate module of chore: update pandas to 3.0.0.

Kies het type dat je wijziging het beste beschrijft en ga door - consistentie is belangrijker dan het "perfecte" label kiezen.

Regels voor het schrijven van een beter Git-commitbericht

Hier is een checklist met regels die je commitberichten nuttiger maken.

• Houd de onderwerpregel onder de 50 tekens. Zo wordt hij goed weergegeven in git log --oneline, de commitlijst van GitHub en terminaloutput zonder afkapping. Als 50 tekens niet lukt, mik dan op maximaal 72.

• Gebruik de gebiedende wijs. Schrijf "add feature" in plaats van "added feature" of "adds feature." Je onderwerpregel moet de zin "If applied, this commit will..." kunnen aanvullen. Dus "If applied, this commit will add caching" leest correct.

• Scheid onderwerp en body met een lege regel. Git gebruikt deze lege regel om het samenvattende deel en de toelichting te onderscheiden. Zonder dat kunnen Git-tools je bericht onjuist tonen.

• Laat de punt aan het einde van de onderwerpregel weg. Je bespaart tekens en de onderwerpregel is toch geen volledige zin. Schrijf fix null pointer in loader in plaats van fix null pointer in loader.

• Begin de onderwerpregel met een hoofdletter. Schrijf Add caching for API calls in plaats van add caching for API calls. Zo oogt je comithistorie consistent en professioneel.

• Gebruik de body om het waarom uit te leggen, niet het wat. De diff laat zien wat er veranderde. Je body moet de reden achter de wijziging uitleggen, alternatieven die je overwoog en eventuele trade-offs die je maakte.

• Wikkel bodytekst af op 72 tekens. Dit voorkomt problemen met regelafbreking in de terminal en houdt je commitberichten leesbaar in verschillende tools.

• Maak elke commit atomair. Eén logische wijziging per commit. Als je een bug fixt en code refactort, splits ze dan op in twee commits met afzonderlijke berichten.

Voorbeelden van een goed Git-commitbericht

Hier zijn praktijkvoorbeelden die laten zien hoe goede commitberichten eruitzien in verschillende scenario’s.

Een eenvoudige fix

fix: handle NaN values in feature engineering

The preprocessing pipeline crashed when encountering NaN values
in the 'age' column. Added fillna() with median imputation before
scaling features.

Dit werkt omdat het het probleem identificeert (NaN-crashes), uitlegt waar het gebeurde (preprocessingpijplijn, age-kolom) en de oplossing beschrijft (mediaanimputatie).

Een nieuwe feature

feat: add model performance tracking to MLflow

Added automatic logging of model metrics, parameters, and artifacts
to MLflow after each training run. This replaces our manual CSV
logging and makes experiment comparison much easier.

Metrics tracked: accuracy, precision, recall, F1 score
Training time also logged for performance monitoring.

Goede feature-commits leggen uit wat je hebt gebouwd, waarom het nuttig is en alle details die lezers helpen de scope te begrijpen.

Een refactor

refactor: split data_loader.py into separate modules

Moved dataset classes to datasets.py, transformation logic to
transforms.py, and utility functions to utils.py. The original
file was 800+ lines and hard to navigate.

No behavior changes - all tests still pass.

Refactor-berichten moeten duidelijk maken dat je de functionaliteit niet veranderde, alleen de structuur. De regel "all tests still pass" stelt reviewers gerust.

Een documentatie-update

docs: add examples for custom loss functions

Previous documentation showed only built-in loss functions.
Added three examples: weighted cross-entropy, focal loss, and
custom regression loss with L1 regularization.

Each example includes code and explanation of when to use it.

Documentatie-commits moeten uitleggen wat je documenteerde en waarom dat nodig was.

Verwijzen naar een issue of ticket

fix: prevent memory leak in batch processing

Large datasets caused memory usage to grow unbounded during batch
processing. The issue was holding references to processed batches
in the results list.

Changed to yield results instead of accumulating them in memory.
Memory usage now stays constant regardless of dataset size.

Fixes #247

Als je naar een issue verwijst, voeg dan genoeg context toe zodat iemand de fix kan begrijpen zonder door te klikken naar het ticket. De Fixes #247 onderaan vertelt GitHub om het issue automatisch te sluiten wanneer deze commit merge’t.

Alle voorbeelden volgen hetzelfde patroon: begin met wat er veranderde, leg uit waarom, voeg context toe die toekomstige lezers helpt, en verwijs naar gerelateerde issues wanneer relevant.

Conventional Commits als standaard voor Git-commitberichten

Conventional Commits is een populair formaat dat structuur toevoegt aan commitberichten via een eenvoudig prefixpatroon.

Basisformaat

Het formaat ziet er zo uit: type(scope): description.

Het type beschrijft wat voor soort wijziging je maakt - feat voor features, fix voor bugfixes, docs voor documentatie, refactor voor herstructurering van code, enzovoort. De scope is optioneel en specificeert welk deel van de codebase veranderde - zoals (auth) of (api). De description legt uit wat je deed.

Voorbeelden:

feat(api): add endpoint for batch predictions
fix(auth): prevent token expiration edge case
docs(readme): add installation instructions for Windows
refactor(data): extract validation logic to separate module

Onthoud dat dit een conventie is, geen vereiste. Git kan het niet schelen of je dit formaat gebruikt. Het komt vooral neer op een teamkeuze over hoe je berichten structureert voor consistentie en tooling.

Wanneer Conventional Commits nuttig zijn

Teams die releaseprocessen automatiseren halen de meeste waarde uit Conventional Commits.

Tools kunnen je commitgeschiedenis parsen en automatisch changelogs genereren. Wanneer je een release tagt, scant de tool commits sinds de laatste release, groepeert ze op type (feat, fix, docs) en maakt een geformatteerde changelog. Dat bespaart het handmatige werk om bij te houden wat er tussen versies veranderde.

Conventional Commits ondersteunen ook automatisering van semantische versies. Als al je commits sinds de laatste release fixes zijn, verhoogt de tool de patchversie (1.2.3 → 1.2.4). Als je features toevoegde, gaat de minorversie omhoog (1.2.3 → 1.3.0). Breaking changes triggeren een major bump (1.2.3 → 2.0.0).

Maar als je team geen geautomatiseerde releases of changeloggeneratie gebruikt, kunnen Conventional Commits overkill zijn. De structuur helpt machines meer dan mensen, dus houd dat in gedachten.

Veelgemaakte fouten in Git-commitberichten om te vermijden

Zelfs ervaren developers maken soms fouten bij het schrijven van commitberichten, maar dat heeft vaker met luiheid te maken dan met een gebrek aan kennis.

Hier zijn een paar fouten die je moet vermijden.

Vage of generieke berichten

Berichten als "fix bug" of "update code" vertellen toekomstige lezers niets.

Wanneer je in git log naar een specifieke wijziging zoekt, scan je door tientallen commits. Een bericht dat "fix bug" zegt, dwingt je om de diff te openen en de code te lezen om te begrijpen wat er is gefixt. Een bericht dat "fix null pointer in data preprocessing" zegt, vertelt je meteen of dit de commit is die je zoekt.

Generieke berichten verspillen ieders tijd. Als je je wijziging niet goed genoeg herinnert om een specifiek bericht te schrijven, zou je waarschijnlijk nog niet moeten committen.

Ongerelateerde wijzigingen mengen

Eén commit moet één logische wijziging bevatten.

Als je in dezelfde commit een bug fixt en ongerelateerde code refactort, maak je code reviews lastiger en git bisect nutteloos. Als die commit een regressie introduceert, moet iemand ontrafelen welk deel van de wijziging de oorzaak was. Als ze alleen de bugfix willen reverten, kan dat niet - dan reverten ze ook de refactor.

Je moet wijzigingen altijd opsplitsen in aparte commits. Fix de bug in één commit, refactor in een andere. Elke commit moet iets zijn dat je onafhankelijk kunt reverten zonder de codebase te breken.

Als je lokaal al wijzigingen hebt gemengd, gebruik dan git add -p om delen van bestanden apart te stagen en ze in logische brokken te committen.

Work-in-progress-berichten laten staan

Commits met berichten als "WIP" of "temp fix" zijn prima lokaal maar zouden de main branch niet moeten halen.

Voordat je je featurebranch merge’t, ruim je commitgeschiedenis op. Squash WIP-commits tot betekenisvolle commits met nette berichten. Herschrijf "asdf" en "trying something" naar beschrijvingen die uitleggen wat je daadwerkelijk deed.

Gebruik git rebase -i om commits te combineren, berichten te herschrijven en wijzigingen te herschikken vóór je pusht. Je team zou een schone geschiedenis moeten zien van wat er veranderde en waarom, niet jouw hele debugproces hoeven teruglezen.

Best practices voor teams die Git-commitberichten gebruiken

Als je team de Git-geschiedenis echt nuttig wil maken, heb je consistentie nodig. Volg deze best practices.

Spreek vroeg een gedeelde stijl af. Bepaal of je Conventional Commits, een aangepast formaat of gewoon een set basisregels gebruikt. Kies één aanpak en hou je eraan met het hele team. Als de helft van je commits zegt "feat: add feature" en de andere helft "Added new feature", wordt je geschiedenis lastiger te scannen en kan automatisering stuklopen.

De stijl zelf is minder belangrijk dan dat iedereen die volgt. Sommige teams geven de voorkeur aan gebiedende wijs tegenwoordige tijd ("add feature"), anderen gebruiken de verleden tijd ("added feature"). Beide werken prima als je ze consistent toepast.

Documenteer je conventies op een toegankelijke plek. Voeg een CONTRIBUTING.md-bestand toe aan je repo waarin je je commitberichtformaat uitlegt met voorbeelden. Neem het op in onboardingdocs voor nieuwe teamleden. Als iemand vraagt "hoe formatteer ik deze commit?", verwijs dan naar de documentatie in plaats van het opnieuw uit te leggen.

Je documentatie moet het basisformaat dat je gebruikt behandelen, wanneer je een body toevoegt versus alleen een onderwerpregel, hoe je issues of tickets verwijst, en een paar echte voorbeelden uit je repo.

Gebruik commitberichten tijdens code reviews. Goede commitberichten maken pull request-reviews sneller en gerichter. Reviewers kunnen de commitberichten lezen om de voortgang van wijzigingen te begrijpen voordat ze de code induiken.

Controleer bij het reviewen de commitberichten net zoals je de code controleert. Als een bericht vaag of misleidend is, vraag dan om het te herschrijven vóór het mergen. Een PR met duidelijke commits is makkelijker te reviewen, makkelijker te reverten indien nodig en later eenvoudiger te begrijpen.

Conclusie

Een duidelijk commitbericht kost 30 seconden om te schrijven maar bespaart later uren aan verwarring.

Zie je commitgeschiedenis als documentatie die met je code meeleeft. Als je "fix bug" schrijft in plaats van "fix null pointer in data preprocessing", verspil je tijd voor iedereen die die commit later leest - inclusief jezelf.

Behandel je commitberichten als code. Als je geen slordige, ongecommentarieerde code naar productie zou pushen, push dan ook geen slordige commitberichten. Gebruik de gebiedende wijs, houd onderwerpregels onder 50 tekens, leg het waarom in de body uit wanneer nodig, en maak elke commit atomair.

Nu weet je hoe je betekenisvolle commitberichten schrijft. Wil je je skills verder uitbouwen, schrijf je dan in voor onze cursus Intermediate Git.