multi-repo-git-ops

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

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

### Step 2: Identify each submodule's tracked branch

```bash
# 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:
```bash
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)
```

**Key principle**: The parent repo tracks **commit pointers** to each submodule, not the submodule code itself. When you change code in a service, you commit in the service repo, then update the parent's pointer.

## Branch Conventions

### Default Branches by Service

Services may track different default branches — always look up the correct one before branching:

```bash
# Get a service's default branch (always use this — never assume)
git config -f .gitmodules submodule."{submodule-path}".branch
```

Different services in the same project often use different default branches (e.g., `develop`, `dev`, `main`). The only reliable source of truth is `.gitmodules`.

### Feature Branch Naming

**For ticket-based work** (JIRA/project tracker):
```
{type}/{TICKET-ID}-{short-description}
```
Examples: `feat/PROJ-1234-add-search-by-date`, `bugfix/PROJ-5678-fix-null-pointer`

**For BMAD story work** (derived from story file name):
```
feat/{story-key}
```
The story key comes from the story file name. A story file named `1-2-user-authentication.md` (representing Epic 1, Story 2) produces branch name `feat/1-2-user-authentication`.

**Branch type prefixes**: `feat/`, `fix/`, `bugfix/`, `chore/`, `base/`

## BMAD Integration (If Applicable)

This section applies only if the project uses the BMAD methodology. Detect this by checking for the `_bmad-output/implementation-artifacts/` directory.

BMAD manages work through story files and sprint status tracking. This section explains how git operations map to the BMAD lifecycle.

### How Stories Reference Services

BMAD story files live at `_bmad-output/implementation-artifacts/{story-key}.md`. Stories reference affected services in several ways — check all of these:

1. **Service tags in story title or body**: `[auth-service]`, `[scheduler-service]`
2. **Dev Notes section**: Lists "Source tree components to touch" with service paths
3. **Project Structure Notes**: References paths like `services/{service-name}/src/...`
4. **Tasks/Subtasks**: Individual tasks may reference different services

When a story doesn't explicitly tag services, look at the file paths mentioned in Dev Notes and Tasks to determine which submodule directories are involved.

### BMAD Status and Git Operations Mapping

BMAD tracks story status in `_bmad-output/implementation-artifacts/sprint-status.yaml`. Each status transition has corresponding git operations:

| Story Status Change | Git Operations Required |
|---|---|
| `backlog` → `ready-for-dev` | No git ops (story file creation only) |
| `ready-for-dev` → `in-progress` | Create feature branches in affected services |

From bmad-labs/skills, MIT.

More from bmad-labs/skills