multi-repo-git-ops

Multi-Repo Git Operations

This skill handles git operations in multi-repo systems that use git submodules. The parent repo orchestrates multiple service repos, each an independent git repository with its own branches, history, and CI/CD.

Understanding this structure is essential — git operations here always involve deciding which repos are affected and operating in each one correctly.

Discovery Protocol

Before performing any git operations, discover the project structure dynamically. Never assume service names, branch mappings, or directory layout — always read from .gitmodules.

Step 1: Identify submodules and their paths

# List all submodules with their paths
git config -f .gitmodules --get-regexp '\.path$'

Step 2: Identify each submodule's tracked branch

# List all submodule branch mappings
git config -f .gitmodules --get-regexp '\.branch$'

# Get a specific service's default branch
git config -f .gitmodules submodule."{submodule-path}".branch

If a submodule has no branch configured in .gitmodules, check the remote:

cd {submodule-path}
git remote show origin | grep 'HEAD branch'

Step 3: Detect project methodology

• BMAD: Check if _bmad-output/implementation-artifacts/ directory exists
• If BMAD is detected, the BMAD Integration section applies

Step 4: Cache discovered info for the session

After discovery, the agent knows:

• All submodule names and paths
• Each submodule's default branch
• Whether BMAD is in use
• The submodule directory prefix (commonly services/)

Use this cached information for all subsequent operations in the session.

Repository Structure

A typical multi-repo project looks like this:

{parent-repo}/                       (parent repo — planning & orchestration only)
├── .gitmodules                      (submodule definitions with tracked branches)
├── services/                        (submodule repos — directory name may vary)
│   ├── auth-service/                (branch: develop)
│   ├── booking-service/             (branch: dev)
│   ├── config-repo/                 (branch: main)
│   └── ...
└── [project methodology dirs]       (e.g., _bmad-output/ if using BMAD)