Sync Go Modules

Sync Go Modules

When To Use

Use this skill when the go-mod-consistency workflow fails or when a dependency change needs repo-wide go.mod / go.sum reconciliation. The workflow mirrors .github/workflows/go-mod-consistency.yaml and .github/actions/discover-go-modules/action.yml, then also refreshes the main module's vendor/ tree.

Workflow

Replace <SKILL_DIR> with the path to this skill directory.

1. Check for unrelated local work before mutating files:

GIT_OPTIONAL_LOCKS=0 git status --short

If there are unrelated uncommitted changes, stop and report the conflict. If the existing changes are the module/dependency edits you are intentionally syncing, pass --allow-dirty to the helper.

2. Run the sync from the repo root:

python3 <SKILL_DIR>/scripts/sync_go_modules.py --repo .

For an intentionally dirty dependency branch:

python3 <SKILL_DIR>/scripts/sync_go_modules.py --repo . --allow-dirty

The helper discovers modules with the same tracked-file pathspec as CI:

GIT_OPTIONAL_LOCKS=0 git ls-files 'go.mod' '**/go.mod'

It then runs go mod tidy and go mod verify in every discovered module, with GOTOOLCHAIN=local so local behavior does not drift through automatic toolchain downloads.

3. Keep the main module vendor tree in sync. This is enabled by default:

(cd . && go mod vendor)

Use --skip-vendor only when the user explicitly asks to sync nested modules without touching root vendored dependencies.

4. Inspect the generated diff:

GIT_OPTIONAL_LOCKS=0 git diff --stat

Expected changes are scoped to tracked module files (go.mod / go.sum) and, when the root module changed, vendor/ plus vendor/modules.txt. If the vendor dependency set changed and the PR also needs license snapshots refreshed, rerun the helper with --update-vendor-licenses or run make update-vendor-licenses. That license update is adjacent to vendoring, but it is not part of the go-mod-consistency workflow itself.

5. To check a clean branch the same way CI will, run the helper after committing or otherwise clearing the generated diff:

python3 <SKILL_DIR>/scripts/sync_go_modules.py --repo . --check-clean

--check-clean fails if the sync produces any repository diff, matching the CI "Fail on uncommitted changes" step.

Helper-owned Git commands are read-only and run with GIT_OPTIONAL_LOCKS=0. This suppresses optional index refresh writes without weakening required locking for checkout, staging, commit, push, or ref-update operations performed outside this helper.

Manual Fallback

If the helper cannot be used, run the CI-equivalent loop manually:

mapfile -t go_mods < <(GIT_OPTIONAL_LOCKS=0 git ls-files 'go.mod' '**/go.mod')
mapfile -t modules < <(for mod in "${go_mods[@]}"; do dirname "$mod"; done | sort -u)
for m in "${modules[@]}"; do
  echo ">> go mod tidy (${m})"
  (cd "${m}" && GOTOOLCHAIN=local go mod tidy)
  echo ">> go mod verify (${m})"
  (cd "${m}" && GOTOOLCHAIN=local go mod verify)
done
GOTOOLCHAIN=local go mod vendor
GIT_OPTIONAL_LOCKS=0 git diff --stat

Do not use find . -name go.mod for this repo. Hidden local worktrees and other untracked directories can contain extra modules that CI does not discover.