Submodule pointer bumps belong at wrap-up
- Path
- reminders/Submodule-Pointer-Bumps-Belong-At-Wrap-Up.md
- Authors
- Michael Staton
- Augmented with
- Claude Code on Claude Opus 5 (1M context)
The ruling
Every commit inside a submodule dirties the parent’s recorded gitlink. That is mechanics, not a problem.
Bumping the parent each time turns one unit of work into two commits — the real one, and a second that says only pointer moved. Across a working day that is pure drag, and it drowns the parent’s history in noise.
| When | What |
|---|---|
| During the session | Commit and push freely in the child. Leave the parent’s M <submodule> dirty. |
| At wrap-up | Bump every moved pointer once, in a single chore(submodule): bump <names> commit. |
Wrap-up means end of session, end of day, or handing off.
For agents — the part that keeps getting violated
Do not offer to commit parent pointers mid-session, and do not treat a dirty gitlink as an error worth reporting. Mention it at wrap-up or when asked.
A M ai-labs in git status is not a finding. Reporting it as one trains the
operator to ignore your status summaries, which is expensive in a tree this
deep — this repo alone routinely carries five or six dirty gitlinks at once from
work spanning several days.
Judge the dirty pointer the same way you judge any other uncommitted change: is it yours, from this session? If not, leave it alone and don’t narrate it.
The exception — collaboration
A parent pointer is how another person’s clone resolves which child commit to check out. If someone else is working the same tree, a stale pointer hands them a checkout that does not match what you said you shipped.
So bump more eagerly when collaborating. The once-at-wrap-up rhythm assumes a single operator — usually true in this tree, but check rather than assume.
Why this is a reminder and not just a skill section
The authority is the skill; this file exists because the failure mode is one of recall under momentum. An agent deep in a child repo, having just pushed, sees the parent go dirty and reaches to “finish the job” — which is exactly wrong, and exactly the moment nobody is re-reading a skill.
Related
- [[../agent-skills/pseudomonorepos/SKILL|pseudomonorepos]] — the full rhythm, the collaboration exception, and the agent corollary (the authoritative statement)
- [[../agent-skills/git-conventions/SKILL|git-conventions]] — same corollary from the commit-hygiene side
- [[Pseudomonorepo-Settings]] — sibling reminder on tree-wide git settings