Back to Details

git-submodule

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Submodule

Git Submodule

Use this skill as the repository's Git submodule choice and operator-workflow anchor.
The job is not to dump every 
git submodule
command in one blob. The job is to:
  1. decide whether submodule is the right boundary at all,
  2. choose one operating mode,
  3. keep pinned-commit, detached-
    HEAD
    , and hosted-platform consequences explicit,
  4. emit the next safe commands only for that mode.
Read references/decision-matrix.md first. Read references/update-and-detached-head.md when the request involves pointer updates, detached 
HEAD
, or editing inside the submodule. Read references/ci-and-automation.md for CI/bootstrap expectations. Read references/mode-packets-and-hosted-constraints.md for mode-specific command packets and GitHub Pages / URL-drift constraints.
If the user mainly needs:
  • local branch/history cleanup, rebase, conflict recovery, or push safety → use 
    git-workflow
  • Node package delivery from Git refs, tarballs, workspaces, or publish-first flows → use 
    npm-git-install
  • repo bootstrap/task-runner automation beyond submodule mechanics → use 
    deployment-automation
  • broader environment or container setup → use 
    system-environment-setup
将此技能作为仓库的Git子模块选择与操作流程指南。
本技能的任务不是一次性罗列所有
git submodule
命令，而是：
  1. 判断子模块是否是合适的边界方案，
  2. 选择一种操作模式，
  3. 明确固定提交、detached-
    HEAD
    以及托管平台带来的影响，
  4. 仅针对该模式输出下一步安全操作命令。
请先阅读references/decision-matrix.md。 当请求涉及指针更新、detached 
HEAD
或在子模块内编辑时，请阅读references/update-and-detached-head.md。 关于CI/初始化预期，请阅读references/ci-and-automation.md。 关于特定模式的命令包以及GitHub Pages / URL偏移限制，请阅读references/mode-packets-and-hosted-constraints.md。
如果用户主要需要：
  • 本地分支/历史清理、变基、冲突恢复或推送安全 → 使用
    git-workflow
  • 从Git引用、压缩包、工作区或先发布流程进行Node包交付 → 使用
    npm-git-install
  • 超出子模块机制的仓库初始化/任务运行器自动化 → 使用
    deployment-automation
  • 更广泛的环境或容器配置 → 使用
    system-environment-setup

When to use this skill

何时使用本技能

  • Add an external repository to a project via 
    git submodule add
  • Clone or initialize a repository that already contains submodules
  • Sync a submodule back to the commit recorded by the superproject
  • Advance a submodule to a tracked remote branch and commit the new pointer
  • Work inside a submodule without getting surprised by detached 
    HEAD
  • Remove a submodule cleanly
  • Configure GitHub Actions or other CI to fetch submodules, including private ones
  • Check hosted-platform constraints such as GitHub Pages public-submodule limits
  • Decide whether submodule vs subtree vs vendoring vs package delivery is the better fit
  • 通过
    git submodule add
    将外部仓库添加到项目中
  • 克隆或初始化已包含子模块的仓库
  • 将子模块同步回父项目记录的提交版本
  • 将子模块推进到跟踪的远程分支并提交新的指针
  • 在子模块内工作，避免遇到detached 
    HEAD
    的意外情况
  • 干净移除子模块
  • 配置GitHub Actions或其他CI以拉取子模块（包括私有子模块）
  • 检查托管平台约束，例如GitHub Pages的公开子模块限制
  • 判断子模块、subtree、依赖包交付哪种方案更合适

When not to use this skill

何时不使用本技能

  • The main problem is ordinary Git collaboration, rebasing, or history repair
  • The dependency should really be a package-manager / registry artifact
  • The task is broader repo bootstrap automation rather than submodule mechanics
  • The request is hosted repo administration outside submodule checkout / visibility constraints
  • The user wants a giant Git tutorial instead of the next safe move for one submodule situation
  • 主要问题是普通Git协作、变基或历史修复
  • 依赖项实际上应该是包管理器/注册表制品
  • 任务是更广泛的仓库初始化自动化，而非子模块机制
  • 请求是超出子模块检出/可见性约束的托管仓库管理
  • 用户想要完整的Git教程，而非针对某一子模块场景的下一步安全操作

Instructions

操作步骤

Step 1: Normalize the request

步骤1：标准化请求

Capture the request in this form first:
yaml
submodule_intake:
  current_goal: decide-boundary | add | bootstrap | sync-to-pinned-commit | advance-tracked-branch | edit-inside-submodule | remove | ci-checkout | hosted-constraint | unknown
  repo_role: superproject-consumer | submodule-maintainer | both | unknown
  dependency_shape: external-repo | vendor-copy | subtree-candidate | package-candidate | unknown
  submodule_state: absent | present-uninitialized | present-detached-head | present-on-branch | pointer-needs-update | unknown
  update_intent: none | match-recorded-commit | move-to-new-upstream-commit | develop-and-push-submodule | unknown
  ci_context: none | github-actions | other-ci | github-pages | unknown
  auth_context: public | private-ssh | private-token | unknown
  collaboration_risk: solo | shared | unknown
  confidence: high | medium | low
If context is incomplete, make the safest default explicit.
首先将请求整理为以下格式：
yaml
submodule_intake:
  current_goal: decide-boundary | add | bootstrap | sync-to-pinned-commit | advance-tracked-branch | edit-inside-submodule | remove | ci-checkout | hosted-constraint | unknown
  repo_role: superproject-consumer | submodule-maintainer | both | unknown
  dependency_shape: external-repo | vendor-copy | subtree-candidate | package-candidate | unknown
  submodule_state: absent | present-uninitialized | present-detached-head | present-on-branch | pointer-needs-update | unknown
  update_intent: none | match-recorded-commit | move-to-new-upstream-commit | develop-and-push-submodule | unknown
  ci_context: none | github-actions | other-ci | github-pages | unknown
  auth_context: public | private-ssh | private-token | unknown
  collaboration_risk: solo | shared | unknown
  confidence: high | medium | low
如果上下文不完整，请明确说明最安全的默认值。

Step 2: Decide whether submodule is the right tool

步骤2：判断子模块是否是合适的工具

Answer these before giving commands:
  • Do we need a separate upstream Git history inside this repo?
  • Is exact commit pinning the real requirement?
  • Can the team tolerate recursive clone/bootstrap and CI checkout setup?
  • Is the dependency more like a subtree, a vendored snapshot, or a published package instead?
If the answer is "not really", route away instead of forcing submodules.
在给出命令前先回答以下问题：
  • 我们是否需要在本仓库内保留独立的上游Git历史？
  • 精确提交固定是否是实际需求？
  • 团队能否接受递归克隆/初始化以及CI检出配置？
  • 该依赖项是否更适合用subtree、依赖快照或已发布包的形式？
如果答案是否定的，请引导用户使用其他方案，而非强行使用子模块。

Step 3: Choose exactly one primary mode

步骤3：选择唯一的主模式

Pick one primary mode for the current run:
  1. boundary decision
  2. add-and-pin
  3. bootstrap-and-clone
  4. sync-to-pinned-commit
  5. advance-tracked-branch
  6. edit-inside-submodule
  7. remove-and-cleanup
  8. ci-checkout
  9. hosted-constraint
Use 
hosted-constraint
when the user is blocked by platform rules such as GitHub Pages public-only submodules or stale submodule URL forms, rather than by ordinary local Git usage.
为当前操作选择一种主模式：
  1. 边界决策
  2. 添加并固定版本
  3. 初始化并克隆
  4. 同步到固定提交
  5. 推进跟踪分支
  6. 在子模块内编辑
  7. 移除并清理
  8. CI检出
  9. 托管平台约束
当用户被平台规则（如GitHub Pages仅支持公开子模块或子模块URL格式过时）限制而非普通本地Git使用问题时，选择
hosted-constraint
模式。

Step 4: Keep the operator invariants visible

步骤4：保持操作不变性可见

These truths should survive every answer:
  • A superproject records a submodule by commit, not by "latest branch".
  • git submodule update
    usually restores the recorded commit and may leave the submodule in detached 
    HEAD
    .
  • .gitmodules
    is part of the contract; branch-tracking intent belongs there when 
    update --remote
    is expected.
  • A submodule commit is not reflected in the superproject until the submodule path is staged and committed there.
  • Recursive bootstrap belongs in onboarding and automation docs if the repo depends on submodules.
  • Hosted platforms may add visibility, URL, or auth constraints that normal local Git use does not reveal.
以下要点应体现在所有回复中：
  • 父项目通过提交记录而非“最新分支”来记录子模块。
  • git submodule update
    通常会恢复到记录的提交版本，可能导致子模块处于detached 
    HEAD
    状态。
  • .gitmodules
    是契约的一部分；当预期使用
    update --remote
    时，分支跟踪意图应配置在此文件中。
  • 子模块的提交不会反映到父项目中，除非父项目中对子模块路径执行了暂存和提交操作。
  • 如果仓库依赖子模块，递归初始化应包含在入职文档和自动化流程中。
  • 托管平台可能会增加可见性、URL或权限约束，这些约束在普通本地Git使用中不会体现。

Step 5: Build the submodule brief

步骤5：生成Git子模块简要说明

Return this exact structure:
markdown
undefined
返回以下固定结构：
markdown
undefined

Git Submodule Brief

Git Submodule Brief

Recommended mode

推荐模式

  • Mode: boundary decision | add-and-pin | bootstrap-and-clone | sync-to-pinned-commit | advance-tracked-branch | edit-inside-submodule | remove-and-cleanup | ci-checkout | hosted-constraint
  • Why this mode fits: ...
  • 模式：boundary decision | add-and-pin | bootstrap-and-clone | sync-to-pinned-commit | advance-tracked-branch | edit-inside-submodule | remove-and-cleanup | ci-checkout | hosted-constraint
  • 适配原因：...

Current state

当前状态

  • Superproject goal: ...
  • Submodule state: ...
  • Auth / CI / hosted context: ...
  • Collaboration risk: solo | shared | unknown
  • Confidence: high | medium | low
  • 父项目目标：...
  • 子模块状态：...
  • 权限/CI/托管上下文：...
  • 协作风险：solo | shared | unknown
  • 置信度：high | medium | low

Safest next move

最安全的下一步操作

  1. ...
  2. ...
  3. ...
  1. ...
  2. ...
  3. ...

Commands

命令

bash
...
bash
...

Watch-outs

注意事项

  • ...
  • ...
  • ...
  • ...

Pointer / branch consequences

指针/分支影响

  • ...
  • ...

Adjacent handoff

相关技能转接

  • git-workflow
    when ...
  • npm-git-install
    when ...
  • deployment-automation
    when ...
undefined
  • 当...时使用
    git-workflow
  • 当...时使用
    npm-git-install
  • 当...时使用
    deployment-automation
undefined

Step 6: Use the mode packets, not a giant improvised command dump

步骤6：使用模式命令包，而非随意罗列命令

Pull the exact packet from references/mode-packets-and-hosted-constraints.md.
Rules:
  • boundary decision
    should compare submodule with subtree / vendoring / package delivery directly.
  • bootstrap-and-clone
    and 
    sync-to-pinned-commit
    must preserve the difference between restore recorded state and upgrade pointer.
  • advance-tracked-branch
    must make branch intent explicit and commit the resulting pointer update in the superproject.
  • edit-inside-submodule
    must avoid detached-
    HEAD
    commit loss.
  • ci-checkout
    must make private-submodule auth explicit.
  • hosted-constraint
    must call out public-only or URL-form restrictions instead of pretending hosted builds will authenticate like a local clone.
从references/mode-packets-and-hosted-constraints.md中提取对应的命令包。
规则：
  • boundary decision
    模式应直接对比子模块与subtree/依赖快照/包交付方案。
  • bootstrap-and-clone
    和
    sync-to-pinned-commit
    模式必须区分恢复记录状态与更新指针的差异。
  • advance-tracked-branch
    模式必须明确分支意图，并在父项目中提交指针更新结果。
  • edit-inside-submodule
    模式必须避免detached-
    HEAD
    状态下的提交丢失。
  • ci-checkout
    模式必须明确私有子模块的权限配置。
  • hosted-constraint
    模式必须指出仅公开或URL格式限制，而非假设托管构建会像本地克隆一样进行权限验证。

Output format

输出格式

Return a short operator-style Git Submodule Brief.
Required qualities:
  • pick one workflow mode
  • say whether submodule is actually the right tool
  • make detached-
    HEAD
    / pointer consequences explicit
  • include CI/auth or hosted-platform notes when relevant
  • route away cleanly when the problem belongs to another skill
返回简短的操作式Git Submodule Brief。
必备特性：
  • 选择一种工作流模式
  • 说明子模块是否确实是合适的工具
  • 明确detached-
    HEAD
    /指针带来的影响
  • 相关时包含CI/权限或托管平台说明
  • 当问题属于其他技能时，清晰引导用户转接

Examples

示例

Example 1: bootstrap after clone

示例1：克隆后初始化

Input: "I cloned the repo and the vendor directory is empty. There's a 
.gitmodules
file." Output: choose 
bootstrap-and-clone
, recommend 
git submodule update --init --recursive
, explain that this restores the pinned contents rather than upgrading anything, and mention private-auth caveats if applicable.
输入："我克隆了仓库，但vendor目录是空的，里面有一个
.gitmodules
文件。" 输出：选择
bootstrap-and-clone
模式，推荐
git submodule update --init --recursive
，说明此操作会恢复固定内容而非升级，若适用则提及私有权限注意事项。

Example 2: update a tracked dependency

示例2：更新跟踪的依赖项

Input: "We track the main branch of a docs repo as a submodule and want the latest commit." Output: choose 
advance-tracked-branch
, set or confirm 
submodule.<name>.branch
, run 
git submodule update --remote <path>
, then commit the pointer update in the superproject.
输入："我们将一个文档仓库的main分支作为子模块跟踪，想要获取最新提交。" 输出：选择
advance-tracked-branch
模式，设置或确认
submodule.<name>.branch
，运行
git submodule update --remote <path>
，然后在父项目中提交指针更新。

Example 3: choose boundary

示例3：边界选择

Input: "Should this shared component repo be a submodule or subtree?" Output: choose 
boundary decision
, compare separate-history/pinning needs against clone simplicity, and route to subtree if consumers should not deal with recursive bootstrap.
输入："这个共享组件仓库应该用子模块还是subtree？" 输出：选择
boundary decision
模式，对比独立历史/固定需求与克隆简易性，如果使用者无需处理递归初始化则引导使用subtree。

Example 4: hosted-platform constraint

示例4：托管平台约束

Input: "Our GitHub Pages build uses a private docs-theme submodule and keeps failing." Output: choose 
hosted-constraint
, explain the public-
https://
GitHub Pages limitation, and route away from a private-submodule Pages design instead of pretending auth fixes it.
输入："我们的GitHub Pages构建使用了私有文档主题子模块，一直失败。" 输出：选择
hosted-constraint
模式，解释GitHub Pages仅支持公开
https://
子模块的限制，引导用户放弃在Pages中使用私有子模块的设计，而非假设权限配置可以解决问题。

Best practices

最佳实践

  1. Start with the boundary decision, not the command list.
  2. Distinguish match pinned commit from advance upstream pointer.
  3. Treat detached 
    HEAD
    as normal-but-important operator state, not as a mysterious Git bug.
  4. Keep submodule mechanics separate from generic Git history repair.
  5. Make CI checkout, hosted-platform limits, and auth part of the main workflow whenever submodules are involved.
  1. 从边界决策开始，而非命令列表。
  2. 区分匹配固定提交与推进上游指针。
  3. 将detached 
    HEAD
    视为正常但重要的操作状态，而非神秘的Git bug。
  4. 将子模块机制与通用Git历史修复分开处理。
  5. 只要涉及子模块，就将CI检出、托管平台限制和权限配置纳入主工作流。

References

参考资料