← knowledge.oriz.in

Bump a submodule pointer in master

runbook runbookgitsubmoduleworkflow

Bump a submodule pointer in master

The master oriz repo references each oriz-* site as a git submodule. Every change inside a site lands as two commits: the feature commit inside the submodule, and a chore: bump commit in master that moves the pointer.

Steps

  1. Enter the submodule.

    cd sites/oriz-<name>

  2. Verify you're on main. Per one-branch-only.md, no other branch should exist.

    git status        # confirms branch and clean tree
git rev-parse --abbrev-ref HEAD   # must print "main"

  3. Commit the feature inside the submodule. Use a conventional commit message that describes the actual change.

    git add -A
git commit -m "feat(<scope>): <one-line summary>"

  4. Push the submodule — but only when the user has explicitly authorised pushing this turn. See

    .
    git push origin main

  5. Capture the short SHA of the submodule HEAD.

    SHORT_SHA=$(git rev-parse --short HEAD)
echo "$SHORT_SHA"

  6. Return to master and stage the new pointer.

    cd ../..
git add sites/oriz-<name>

  7. Commit the pointer bump with a chore(submodule) message that names the submodule and the new short SHA.

    git commit -m "chore(submodule): bump oriz-<name> to ${SHORT_SHA}"

  8. Push master — again, only when authorised.

    git push origin main

Why two commits

The submodule's history records the actual change. The master commit records which version of the submodule the family is shipping. They serve different audiences (engineers reading the submodule's git log vs. operators rolling back the family) and should not be squashed.

See also