Git as a discipline: atomic commits, short-lived branches and a history you can read

How to use git so that the project's history really helps: small, descriptive commits, short-lived branches, conflicts resolved calmly, tagged versions, parallel work.

Methodologymetodologiagitversionamentoingegneria del software19 November 2026 · 3 min read

A commit history made of "fix", "wip" and "assorted changes" is no use to anyone: it does not let you understand why a behaviour changed, it does not allow undoing a single change and it makes review a chore. Git is the same tool in both cases: what changes is the discipline with which it is used.

Atomic commits

A commit contains one change with a single intention, and stands on its own: the project builds and the tests pass before and after. If describing the commit needs the word "and", it is two commits. The advantage is practical: you can undo one change without dragging others along, and whoever looks for the origin of a defect finds a readable change.

Messages that explain why

The opening line says what changes, briefly and specifically. The body, when needed, explains why: the problem being solved, the choice made, the alternative discarded. The "what" is already shown by the diff; the "why" is shown by nobody.

Short-lived branches

A branch lives days, not weeks. The longer it lives, the further it drifts from the main branch and the more it costs to merge back. For long jobs you cut small changes that go in every day, hiding what is unfinished behind a configuration switch. The branch name states the intention (for example, fix or feature, plus a short subject).

Before saving, look

Before every commit you reread the diff: are there debug lines, unrelated files, secrets? What goes into the history stays there. Generated files, downloaded dependencies and secrets do not belong in the repository.

Conflicts

You resolve them calmly, understanding the two intentions, not choosing one or the other at random. After resolving you rerun the tests. You realign your own branch often, so conflicts stay small.

Versions

Released versions are tagged with numbers that say something about compatibility (major for incompatible changes, minor for additions, patch for fixes). The tag is applied after the release has gone well, not before.

Parallel work

When several people or agents work on the same project, each has their own branch (or their own working copy), with tasks that do not touch the same files. Parallel work works if the boundaries are clear; if two activities touch the same files, they are done one after the other.

Warning signs

  • Commits with messages like "fix" or "wip".
  • Giant commits that mix several intentions.
  • Branches weeks old.
  • Secrets or generated files in the repository.
  • Conflicts resolved without retesting.
  • Rewrites of history that has already been shared.
  • Large unsaved changes piling up.

An example

A fix touches three things: the calculation of a total, the name of a variable and a test. In three commits: "Fix rounding of the order total (two rounding points)", "Rename tot to order_total", "Add test for orders with two discounts". If the fix causes a problem, you undo the first without losing the others.

When to use it

Every time you change the code; when saving, creating a branch, resolving a conflict or organising work into several parallel streams.

This method derives from the open-source agent-skills family by Addy Osmani (MIT licence), rewritten and adapted.

This article is an OIAR skill

What you have just read is the content of a skill from the OIAR catalogue, written for people. Knowledge like this, but richer and deeper, written for the agents, drives the interviews, the analysis and the report inside the platform. Skills are used in OIAR: to try this one on a project of yours you need an account.

git-workflow-and-versioningA method for using git so that the history is useful: atomic commits with messages that explain why, short-lived branches, checking the diff before saving, conflicts resolved with tests, tagged versions, parallel work. Use it every time you save a change or organise work into branches.