syncing-submodules
Records a submodule's current commit in its parent repository. Use after a commit inside a submodule when the parent repository or superproject should record the new pointer. Does not handle clone, checkout, update main, or ordinary commits.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 7
- Forks
- 1
01 前言 Front Matter
- name
- syncing-submodules
- description
- Records a submodule's current commit in its parent repository. Use after a commit inside a submodule when the parent repository or superproject should record the new pointer. Does not handle clone, checkout, update main, or ordinary commits.
02 资源文件 9
- 参考文档reference/run-tasks.md389 B
- 脚本scripts/submodule_sync_constants/__init__.py72 B
- 脚本scripts/submodule_sync_constants/config/__init__.py76 B
- 脚本scripts/submodule_sync_constants/config/constants.py2.3 KB
- 脚本scripts/submodule_sync.py12.1 KB
- 脚本scripts/subprocess_window_access.py1.6 KB
- 脚本scripts/sync_parent_pointer.py2.5 KB
- 脚本scripts/test_submodule_sync.py10.3 KB
- 脚本scripts/test_sync_parent_pointer.py2.2 KB
03 SKILL.md 正文
Syncing submodules
Principle
A submodule commit changes the child repository first. Change the parent pointer only when this skill runs. Limit the parent commit to the submodule path so other staged work stays staged.
Gotchas
- Inherited
GIT_*variables can redirect child Git commands. The script removes them from its Git environment. - Submodule paths can contain brackets or wildcard characters. The script sends Git a literal pathspec.
git diff --cached --quietuses exit 1 for a changed pointer. Any higher exit is a failure.- The parent repository may already contain staged work. The path-only commit must leave it staged.
- A repository without a superproject is a successful
not_submoduleresult. - A failed parent commit returns a nonzero exit.
When this applies
Use this skill after committing inside a checked-out submodule when its parent repository should record the new commit.
Refusals use the first matching line:
- Clone, initialize, or check out a submodule:
Use Git's submodule commands. This skill records an existing submodule commit in its parent. - Fast-forward
main:Use Git directly. This skill changes one parent submodule pointer. - Make an ordinary commit or push:
Use Git directly. This skill commits only a parent submodule pointer.
Process
Seed the run tasks
When the host exposes a task tool, register every item in reference/run-tasks.md as a session task and complete each one with an exit code, JSON field, or repository readback. Otherwise work the items in order.
Run the command
Execute the bundled script. Do not reconstruct the Git sequence by hand.
python "${CLAUDE_SKILL_DIR}/scripts/sync_parent_pointer.py" --repository "<submodule-path>"
Python 3 and Git are required. GitHub CLI is optional and only supplies an open pull request URL.
The script writes one JSON object to standard output. Exit 0 permits updated, unchanged, and not_submodule. Exit 1 reports a Git or repository failure. Exit 2 reports invalid arguments. Treat every nonzero exit as incomplete work. Fix the reported condition, rerun the command, and keep the task open until the command exits 0.
Report the result
updated: reportparent_repository,submodule_path,commit, andparent_commit.unchanged: report that the parent already recordscommit.not_submodule: report that no parent repository changed.pull_request_url: report the open pull request URL after the sync result.
Constraints
- Run the script from this skill package.
- Commit only the literal submodule path in the parent repository.
- Preserve every unrelated staged parent path.
- Never push, switch branches, rewrite commits, or change Git configuration.
- Never treat a failed Git command as success.
Examples
- Updated pointer:
statusisupdated,submodule_pathismodules/child, andparent_commitnames the new parent commit. - No superproject:
statusisnot_submodule; every parent and commit field is null. - Failed stage: exit 1,
statusiserror, and standard error starts withsyncing-submodules:.
File index
| File | Purpose |
|---|---|
SKILL.md |
Selection, operation boundary, result handling, and peer routing |
reference/run-tasks.md |
Task seeds for each repository-changing run |
scripts/sync_parent_pointer.py |
Execute the parent pointer sync and return one JSON result |
scripts/submodule_sync.py |
Own the Git operation and typed sync report |
scripts/subprocess_window_access.py |
Re-export the hidden-window helpers from the deployed hooks directory |
scripts/test_sync_parent_pointer.py |
Prove command parsing, JSON output, and hook deletion |
scripts/test_submodule_sync.py |
Prove exact commits, preserved staging, no-op states, and failures |
scripts/submodule_sync_constants/__init__.py |
Mark the constants package |
scripts/submodule_sync_constants/config/__init__.py |
Mark the configuration package |
scripts/submodule_sync_constants/config/constants.py |
Named command, message, field, and exit-code constants |
Folder map
reference/contains the run task seeds.scripts/contains the executable command, Git operation, tests, and constants package.
04 同仓库更多 Skills
update
Fast-forwards a local repository's main branch to a remote's main after confirming the repo path and source remote through AskUserQuestion. Use when the user says '/update', 'update main', 'fast-forward main', 'sync main from origin', 'pull latest main into <path>', or 'bring main up to date'.
source-command-sr-loop
Converging cleanup loop: repeat /simplify until clean, then repeat /code-review --fix until clean
skill-builder
Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose sub-skills, polish description triggers, enforce deterministic scripts. Triggers: build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, skill composition, description trigger catalog, deterministic skill scripts.
session-tidy
Audit, clean, and consolidate session logs in the Obsidian vault. Fixes format drift, resolves orphaned next-steps, updates stale statuses, and generates project rollup summaries. Use when session logs feel cluttered or before starting a new project milestone. Triggers on '/session-tidy', 'tidy sessions', 'clean up session logs', 'session audit'.
session-log
Logs a session report as an HTML page, tracks vault context, extracts decisions, and outputs a /rename command. Use for /session-log, 'journal this session', 'log this work', 'session report', 'summarize/log/record this session', 'save session', 'capture session', or 'document what we did'.
run-claude-dev-env
Build, install, run, and test the claude-dev-env installer. Use when asked to run claude-dev-env, install the Claude Code config into ~/.claude, drive the installer, smoke-test it against a sandbox, or run its test suite.