DiscordSign up
SKILLS.SH

git-submodule

Version-control external repositories within a main project using Git submodules. Add, update, and remove submodules with commands for locking specific commits, branches, or tags Clone repositories with submodules using --recursive or manual initialization and update steps Batch operations across all submodules via git submodule foreach for pulling, checking status, and branch management Nested submodule support with recursive initialization and updates for complex dependency hierarchies Troubleshooting guidance for detached HEAD states, permission errors, dirty submodules, and reference mismatches

INSTALLATION
npx skills add https://github.com/supercent-io/skills-template --skill git-submodule
Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

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

BrowserAct

Let your agent run on any real-world website

Bypass CAPTCHA & anti-bot for free. Start local, scale to cloud.

Explore BrowserAct Skills →

Related skills

find-skills
2/3

Discover and install specialized agent skills from the open ecosystem when users need extended capabilities. Helps identify relevant skills by domain and task when users ask "how do I do X" or "find a skill for X" Integrates with the Skills CLI ( npx skills find , npx skills add ) to search, verify, and install packages from the skills.sh directory Recommends skills based on install count, source reputation, and GitHub stars to ensure quality before suggesting installation Presents skill options with install commands and links to skills.sh for user review and one-click installation

Verified authorvercel-labs
SKILLS.SH
1.5M19.6K
2026-05-22
vercel-react-best-practices
3/3

React and Next.js performance optimization guide with 64 prioritized rules across 8 categories. Organized by impact level, from critical waterfalls and bundle optimization down to advanced patterns, each rule includes incorrect/correct code examples and explanations Covers eight domains: async patterns, bundle size, server-side caching, client-side data fetching, re-render optimization, rendering performance, JavaScript efficiency, and advanced patterns Designed for use during component writing, code review, refactoring, and performance audits on React and Next.js applications Each rule has a prefix code (e.g., async-parallel , bundle-barrel-imports ) for easy reference in automated tooling and documentation

Verified authorvercel-labs
SKILLS.SH
389K26.9K
2026-05-22
azure-validate
2/3

Pre-deployment validation for Azure infrastructure, configuration, and permissions before deployment. Requires .azure/plan.md from a prior azure-prepare run; stops immediately if the plan is missing Executes recipe-specific validation commands (azd provision, bicep build, terraform validate) and records proof in the plan document Performs build verification, configuration checks, and permission validation; blocks deployment if any check fails Only authorized method to set plan status to Validated ; must be followed by azure-deploy skill to execute the actual deployment

Verified authormicrosoft
SKILLS.SH
324K1.1K
2026-05-22
appinsights-instrumentation
3/3

Guidance and reference material for instrumenting webapps with Azure Application Insights. Covers SDK setup, telemetry patterns, and configuration for ASP.NET Core and Node.js applications hosted in Azure Distinguishes between this skill (reference and guidance) and azure-prepare (actual implementation); invoke azure-prepare when the user wants to add instrumentation to their project Provides auto-instrumentation guidance for C# ASP.NET Core apps in Azure App Service, plus manual instrumentation paths for creating App Insights resources via Bicep templates or Azure CLI Includes language-specific code modification guides for ASP.NET Core, Node.js, and Python, plus quick references for OpenTelemetry SDKs and exporters

Verified authormicrosoft
SKILLS.SH
324K1.1K
2026-05-22

Stop writing automation&scrapers

Install the CLI. Run your first Skill in 30 seconds. Scale when you're ready.

Start free
free · no credit card