What Does a "Commit" Mean When You Change a Resistor Value?
By the CADPreview Team · Series: Git for Hardware Engineers
"The diff shows what changed. The message explains why. One without the other is half an answer."
You have a repository. You have made your first commit. Now you are sitting in front of a real design change and the question that always follows the setup article:
When exactly do I commit, what do I include, and what do I write?
This is not a Git documentation question. It is a judgment question, and the answer is different for hardware than it is for software.
A Commit Is Not a Save
The first thing to get clear: saving and committing are not the same operation.
Save constantly. Ctrl+S every few minutes. That is just not losing work.
A commit is something else. It is a declaration that the design, in this state, means something. Not "I pressed save." Something with a reason behind it.
Hardware engineers already make these declarations, they just do not always formalise them. The moment you finish a schematic and hand it to someone for review, that is a commit. The moment you freeze the layout before generating fab outputs, that is a commit. The moment you approve a last-minute component swap before the board goes to the CM, that is a commit. Git just makes those moments permanent and retrievable.
The discipline is deciding which moments qualify. Too many commits and the history becomes noise. Too few and the history has gaps at exactly the points where you will later need it.
The Resistor Value Change
Here is a concrete case. You are reviewing the SPI pull-up network. R12 is 10k. You scope the bus and the rise time is marginal. You change R12 to 4k7, recheck the loading, and you are satisfied.
That is one commit. The decision has a beginning and an end, a reason and a conclusion. Everything that went into making it is knowable and could be written down in a sentence.
Compare that to a session where you change R12, notice that three net labels are inconsistent with your naming convention, fix those, add a bypass capacitor you forgot on U4, and then move a connector symbol because it was overlapping a note. That session contains four separate decisions. Committing all of it as one block does not erase the decisions, it just makes them impossible to separate later.
The rule is: one logical change per commit. Not one file. Not one symbol. One design decision, with the scope that decision actually had.
What to Write
"Changed resistor value" is a file change log. Git already has the file change log. The diff shows exactly which line changed and from what to what. The message is not for recording the change. It is for recording the reason.
A useful commit message for the R12 change:
R12 10k to 4k7, pull-up was marginal at 3.3V, SPI rise time outside spec
That is one sentence. It tells you the component, the before and after, and why. In six months, when a firmware engineer is investigating a slow GPIO and looking at the repository history, that message is the difference between understanding the design decision and having to track down the hardware engineer and ask them to reconstruct it from memory.
The message is not documentation. It is communication across time.
The Right Moment
Not after every edit. Not at end of day as a catch-all. After each decision that has a reason behind it.
A useful test: if you cannot write a one-sentence explanation of why the design is in this state, you have probably not finished the decision yet. Wait until you can.
Some natural commit points during a typical PCB project:
During schematic capture. Each functional block completed: power supply, processor, communications peripherals, analog front end. Each is a coherent decision with a reason behind it, and each is something someone might want to review in isolation.
At schematic review. Before you hand it to anyone, commit with a message that says it is ready for review. After review, commit the changes with a message that captures what was found and what was changed.
At component placement. Placement done, ready to route. One commit. If you iterate on placement significantly, commit the intermediate states that represent real decisions, not every drag and drop.
Before generating fab outputs. This is the one you cannot afford to miss. The tagged release commit is the record of what you actually sent to the manufacturer. If that commit does not exist, you are relying on a file in a folder and hoping it matches.
Snapshots, Not Patches
One more concept worth having right, because it changes how you think about what a commit is.
Git does not store diffs. It stores complete snapshots of every tracked file, at every commit, and computes diffs on request. What this means in practice: any commit is a fully self-contained state of the design. Not a reconstruction from patches applied in sequence. The actual files, as they were, at that moment.
When you check out Rev A to compare it with the current state, you are not replaying history. You are opening the design as it existed when you tagged that release. Every Gerber that commit would produce is deterministic. The BOM is exactly what it was. The schematic is exactly what it was.
That is the mental model that matters for hardware: a commit is a snapshot of the complete design state, not a record of changes. The changes are visible, but they are computed from the snapshots. The thing you are preserving is the state.
The Note Your Firmware Engineer Reads
The commit message for the R12 change is not just for you. It is for the firmware engineer who is looking at the GPIO driver six months from now, wondering why the pull-up is sized the way it is. It is for the supply chain person who is asking whether the alternate part they found has the same loading. It is for you, six months from now, when you cannot remember why that value is not round.
The discipline of writing a useful commit message is not version control hygiene. It is communication, deferred to the moment it is needed, by the person who has the context to write it, which is you, right now, while the reason is still in your head.
Write the message while you know why. You will not remember later.
What Is Next
The next article covers branching: what to do when two engineers are working on the same board at the same time, how to propose a change without overwriting someone else's work, and how to use a pull request as a lightweight design review process.
CADPreview is a web-based viewer for KiCad projects hosted on GitHub. Connect your repository once, share a link, and your whole team sees the current schematic, layout, and BOM in a browser, on any branch, at any release, without installing anything.