git-submodule

When to use this skill

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "git-submodule" with this command: npx skills add akillness/skills-template/akillness-skills-template-git-submodule

Git Submodule

When to use this skill

  • Including external Git repositories within your main project

  • Managing shared libraries or modules across multiple projects

  • Locking external dependencies to specific versions

  • Working with monorepo-style architectures with independent components

  • Cloning repositories that contain submodules

  • Updating submodules to newer versions

  • Removing submodules from a project

Instructions

Step 1: Understanding submodules

Git submodule is a feature for including other Git repositories within a main Git repository.

Key concepts:

  • Submodules lock version by referencing a specific commit

  • Submodule paths and URLs are recorded in the .gitmodules file

  • Changes within a submodule are managed as separate commits

Step 2: Adding submodules

Basic addition:

Add submodule

git submodule add <repository-url> <path>

Example: Add library to libs/lib path

git submodule add https://github.com/example/lib.git libs/lib

Track a specific branch:

Add to track a specific branch

git submodule add -b main https://github.com/example/lib.git libs/lib

Commit after adding:

git add .gitmodules libs/lib git commit -m "feat: add lib as submodule"

Step 3: Cloning with submodules

When cloning fresh:

Method 1: --recursive option when cloning

git clone --recursive <repository-url>

Method 2: Initialize after cloning

git clone <repository-url> cd <repository> git submodule init git submodule update

Initialize and update in one line:

git submodule update --init --recursive

Step 4: Updating submodules

Update to latest remote version:

Update all submodules to latest remote

git submodule update --remote

Update a specific submodule only

git submodule update --remote libs/lib

Update + merge

git submodule update --remote --merge

Update + rebase

git submodule update --remote --rebase

Checkout to the referenced commit:

Checkout submodule to the commit referenced by the main repository

git submodule update

Step 5: Working inside submodules

Working inside a submodule:

Navigate to submodule directory

cd libs/lib

Checkout branch (exit detached HEAD)

git checkout main

Work on changes

... make changes ...

Commit and push within submodule

git add . git commit -m "feat: update library" git push origin main

Reflect submodule changes in main repository:

Move to main repository

cd ..

Update submodule reference

git add libs/lib git commit -m "chore: update lib submodule reference" git push

Step 6: Batch operations

Run commands on all submodules:

Pull in all submodules

git submodule foreach 'git pull origin main'

Check status in all submodules

git submodule foreach 'git status'

Checkout branch in all submodules

git submodule foreach 'git checkout main'

Also run command on nested submodules

git submodule foreach --recursive 'git fetch origin'

Step 7: Removing submodules

Completely remove a submodule:

1. Deinitialize submodule

git submodule deinit <path>

2. Remove from Git

git rm <path>

3. Remove cache from .git/modules

rm -rf .git/modules/<path>

4. Commit changes

git commit -m "chore: remove submodule"

Example: Remove libs/lib:

git submodule deinit libs/lib git rm libs/lib rm -rf .git/modules/libs/lib git commit -m "chore: remove lib submodule" git push

Step 8: Checking submodule status

Check status:

Check submodule status

git submodule status

Detailed status (recursive)

git submodule status --recursive

Summary information

git submodule summary

Interpreting output:

44d7d1... libs/lib (v1.0.0) # Normal (matches referenced commit) +44d7d1... libs/lib (v1.0.0-1-g...) # Local changes present -44d7d1... libs/lib # Not initialized

Examples

Example 1: Adding an External Library to a Project

1. Add submodule

git submodule add https://github.com/lodash/lodash.git vendor/lodash

2. Lock to a specific version (tag)

cd vendor/lodash git checkout v4.17.21 cd ../..

3. Commit changes

git add . git commit -m "feat: add lodash v4.17.21 as submodule"

4. Push

git push origin main

Example 2: Setup After Cloning a Repository with Submodules

1. Clone the repository

git clone https://github.com/myorg/myproject.git cd myproject

2. Initialize and update submodules

git submodule update --init --recursive

3. Check submodule status

git submodule status

4. Checkout submodule branch (for development)

git submodule foreach 'git checkout main || git checkout master'

Example 3: Updating Submodules to the Latest Version

1. Update all submodules to latest remote

git submodule update --remote --merge

2. Review changes

git diff --submodule

3. Commit changes

git add . git commit -m "chore: update all submodules to latest"

4. Push

git push origin main

Example 4: Using Shared Components Across Multiple Projects

In Project A

git submodule add https://github.com/myorg/shared-components.git src/shared

In Project B

git submodule add https://github.com/myorg/shared-components.git src/shared

When updating shared components (in each project)

git submodule update --remote src/shared git add src/shared git commit -m "chore: update shared-components"

Example 5: Handling Submodules in CI/CD

GitHub Actions

jobs: build: steps: - uses: actions/checkout@v4 with: submodules: recursive # or 'true'

GitLab CI

variables: GIT_SUBMODULE_STRATEGY: recursive

Jenkins

checkout scm: [ $class: 'SubmoduleOption', recursiveSubmodules: true ]

Advanced workflows

Nested Submodules

Initialize all nested submodules

git submodule update --init --recursive

Update all nested submodules

git submodule update --remote --recursive

Changing Submodule URL

Edit the .gitmodules file

git config -f .gitmodules submodule.libs/lib.url https://new-url.git

Sync local configuration

git submodule sync

Update submodule

git submodule update --init --recursive

Converting a Submodule to a Regular Directory

1. Back up submodule contents

cp -r libs/lib libs/lib-backup

2. Remove submodule

git submodule deinit libs/lib git rm libs/lib rm -rf .git/modules/libs/lib

3. Restore backup (excluding .git)

rm -rf libs/lib-backup/.git mv libs/lib-backup libs/lib

4. Add as regular files

git add libs/lib git commit -m "chore: convert submodule to regular directory"

Saving Space with Shallow Clones

Add submodule with shallow clone

git submodule add --depth 1 https://github.com/large/repo.git libs/large

Update existing submodule as shallow clone

git submodule update --init --depth 1

Best practices

  • Version locking: Always lock submodules to a specific commit/tag for reproducibility

  • Documentation: Specify submodule initialization steps in README

  • CI configuration: Use --recursive option in CI/CD pipelines

  • Regular updates: Regularly update submodules for security patches and more

  • Branch tracking: Configure branch tracking during development for convenience

  • Permission management: Verify access permissions for submodule repositories

  • Shallow clone: Use --depth option for large repositories to save space

  • Status check: Verify status with git submodule status before committing

Common pitfalls

  • detached HEAD: Submodules are in detached HEAD state by default. Checkout a branch when working

  • Missing initialization: git submodule update --init is required after cloning

  • Reference mismatch: Must update reference in main repository after submodule changes

  • Permission issue: Private submodules require SSH key or token configuration

  • Relative paths: Using relative paths in .gitmodules can cause issues in forks

  • Incomplete removal: Must also delete .git/modules cache when removing a submodule

Troubleshooting

Submodule not initialized

Force initialize

git submodule update --init --force

Submodule conflict

Check submodule status

git submodule status

After resolving conflict, checkout desired commit

cd libs/lib git checkout <desired-commit> cd .. git add libs/lib git commit -m "fix: resolve submodule conflict"

Permission error (private repository)

Use SSH URL

git config -f .gitmodules submodule.libs/lib.url git@github.com:org/private-lib.git git submodule sync git submodule update --init

Submodule in dirty state

Check changes within submodule

cd libs/lib git status git diff

Discard changes

git checkout . git clean -fd

Or commit

git add . git commit -m "fix: resolve changes" git push

Configuration

Useful Configuration

Show submodule changes in diff

git config --global diff.submodule log

Show submodule summary in status

git config --global status.submoduleSummary true

Check submodule changes on push

git config --global push.recurseSubmodules check

Also fetch submodules when fetching

git config --global fetch.recurseSubmodules on-demand

.gitmodules Example

[submodule "libs/lib"] path = libs/lib url = https://github.com/example/lib.git branch = main

[submodule "vendor/tool"] path = vendor/tool url = git@github.com:example/tool.git shallow = true

References

  • Git Submodules - Official Documentation

  • Git Submodule Tutorial - Atlassian

  • Managing Dependencies with Submodules

  • Git Submodule Cheat Sheet

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

git-submodule

No summary provided by upstream source.

Repository SourceNeeds Review
10.2K-supercent-io
General

omc

No summary provided by upstream source.

Repository SourceNeeds Review
28-akillness
General

plannotator

No summary provided by upstream source.

Repository SourceNeeds Review
27-akillness
General

vibe-kanban

No summary provided by upstream source.

Repository SourceNeeds Review
27-akillness