git-repository

What this skill does

# Git Repository Management Skill

This skill provides comprehensive guidance on repository management strategies, branching models, repository organization patterns, and scaling git for large teams and codebases.

## When to Use

Activate this skill when:
- Setting up new repository structure
- Choosing branching strategy
- Managing monorepo vs polyrepo
- Organizing multi-project repositories
- Implementing submodule or subtree strategies
- Scaling git for large teams
- Migrating repository structures
- Establishing team workflows

## Branching Strategies

### Git Flow

**Branch Structure:**
- `main` (or `master`) - Production releases only
- `develop` - Integration branch for next release
- `feature/*` - Feature development branches
- `release/*` - Release preparation branches
- `hotfix/*` - Emergency production fixes

**Workflow:**

```bash
# Feature Development
git checkout develop
git checkout -b feature/user-authentication
# Work on feature...
git commit -m "feat: add JWT authentication"
git checkout develop
git merge --no-ff feature/user-authentication
git branch -d feature/user-authentication

# Release Preparation
git checkout develop
git checkout -b release/v1.2.0
# Bump version, update changelog, final testing...
git commit -m "chore: prepare release v1.2.0"

# Deploy Release
git checkout main
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"
git checkout develop
git merge --no-ff release/v1.2.0
git branch -d release/v1.2.0
git push origin main develop --tags

# Hotfix
git checkout main
git checkout -b hotfix/security-patch
git commit -m "fix: patch security vulnerability"
git checkout main
git merge --no-ff hotfix/security-patch
git tag -a v1.2.1 -m "Hotfix v1.2.1"
git checkout develop
git merge --no-ff hotfix/security-patch
git branch -d hotfix/security-patch
git push origin main develop --tags
```

**Best For:**
- Scheduled releases
- Multiple production versions
- Large teams with QA process
- Products with maintenance windows
- Enterprise software

**Drawbacks:**
- Complex workflow
- Long-lived branches
- Potential merge conflicts
- Delayed integration

### GitHub Flow

**Branch Structure:**
- `main` - Production-ready code (always deployable)
- `feature/*` - All feature and fix branches

**Workflow:**

```bash
# Create Feature Branch
git checkout main
git pull origin main
git checkout -b feature/add-api-logging

# Develop Feature
git commit -m "feat: add structured logging middleware"
git push -u origin feature/add-api-logging

# Open Pull Request on GitHub
# Review, discuss, CI passes

# Merge and Deploy
# Merge PR on GitHub
# Automatic deployment from main

# Cleanup
git checkout main
git pull origin main
git branch -d feature/add-api-logging
```

**Best For:**
- Continuous deployment
- Small to medium teams
- Web applications
- Rapid iteration
- Cloud-native applications

**Drawbacks:**
- Requires robust CI/CD
- No release staging
- Less structured than Git Flow

### Trunk-Based Development

**Branch Structure:**
- `main` (or `trunk`) - Single source of truth
- Short-lived feature branches (< 2 days, optional)
- Feature flags for incomplete work

**Workflow:**

```bash
# Direct Commit to Main (Small Changes)
git checkout main
git pull origin main
# Make small change...
git commit -m "fix: correct validation logic"
git push origin main

# Short-Lived Branch (Larger Changes)
git checkout -b optimize-query
# Work for < 1 day
git commit -m "perf: optimize database query"
git push -u origin optimize-query
# Immediate PR, quick review, merge same day

# Feature Flags for Incomplete Features
git checkout main
git commit -m "feat: add payment gateway (behind feature flag)"
# Feature disabled in production until complete
git push origin main
```

**Best For:**
- High-velocity teams
- Continuous integration
- Automated testing
- Feature flag infrastructure
- DevOps culture

**Drawbacks:**
- Requires discipline
- Needs comprehensive tests
- Feature flag management
- Higher deployment frequency

### Release Branch Strategy

**Branch Structure:**
- `main` - Current development
- `release/v*` - Long-lived release branches
- `feature/*` - Feature branches

**Workflow:**

```bash
# Create Release Branch
git checkout -b release/v1.0 main
git push -u origin release/v1.0

# Continue Development on Main
git checkout main
# Work on v2.0 features...

# Backport Fixes to Release
git checkout release/v1.0
git cherry-pick abc123  # Fix from main
git push origin release/v1.0
git tag -a v1.0.5 -m "Patch release v1.0.5"
git push origin v1.0.5

# Multiple Release Maintenance
git checkout release/v0.9
git cherry-pick def456
git tag -a v0.9.8 -m "Security patch v0.9.8"
```

**Best For:**
- Multiple product versions
- Long-term support releases
- Enterprise customers
- Regulated industries

**Drawbacks:**
- Maintenance overhead
- Complex cherry-picking
- Diverging codebases

### Feature Branch Workflow

**Branch Structure:**
- `main` - Stable production code
- `feature/*` - Feature branches from main
- `bugfix/*` - Bug fix branches

**Workflow:**

```bash
# Feature Development
git checkout main
git checkout -b feature/payment-integration

# Long-Running Feature (Sync with Main)
git fetch origin
git rebase origin/main
# Or merge
git merge origin/main

# Complete Feature
git push origin feature/payment-integration
# Create pull request
# After review and approval, merge to main
```

**Best For:**
- Medium-sized teams
- Code review processes
- Parallel feature development
- Quality gates before merge

## Repository Organization

### Monorepo

**Structure:**
```
monorepo/
├── .git/
├── services/
│   ├── api/
│   ├── web/
│   └── worker/
├── packages/
│   ├── shared-utils/
│   ├── ui-components/
│   └── api-client/
├── tools/
│   ├── build-tools/
│   └── scripts/
└── docs/
```

**Advantages:**
- Single source of truth
- Shared code visibility
- Atomic cross-project changes
- Unified versioning
- Simplified dependency management
- Consistent tooling

**Disadvantages:**
- Large repository size
- Slower clone/fetch
- Complex CI/CD
- Access control challenges
- Tooling requirements

**Implementation:**

```bash
# Initialize Monorepo
git init
mkdir -p services/api services/web packages/shared-utils

# Workspace Setup (Node.js example)
cat > package.json << EOF
{
  "name": "monorepo",
  "private": true,
  "workspaces": [
    "services/*",
    "packages/*"
  ]
}
EOF

# Sparse Checkout (Partial Clone)
git clone --filter=blob:none --no-checkout <url>
cd repo
git sparse-checkout init --cone
git sparse-checkout set services/api packages/shared-utils
git checkout main

# Build Only Changed Packages
git diff --name-only HEAD~1 | grep "^services/api" && cd services/api && npm run build
```

**Tools:**
- **Bazel** - Build system for large monorepos
- **Nx** - Monorepo build system (Node.js)
- **Lerna** - JavaScript monorepo management
- **Turborepo** - High-performance build system
- **Git-subtree** - Merge external repositories

### Polyrepo

**Structure:**
```
organization/
├── api-service/       (separate repo)
├── web-app/           (separate repo)
├── mobile-app/        (separate repo)
├── shared-utils/      (separate repo)
└── documentation/     (separate repo)
```

**Advantages:**
- Clear ownership boundaries
- Independent versioning
- Smaller repository size
- Granular access control
- Flexible CI/CD
- Team autonomy

**Disadvantages:**
- Dependency version conflicts
- Cross-repo changes are complex
- Duplicated tooling/config
- Harder to refactor across repos

**Implementation:**

```bash
# Template Repository
git clone [email protected]:org/template-service.git new-service
cd new-service
rm -rf .git
git init
git remote add origin [email protected]:org/new-service.git

# Shared Configuration
# Use git submodules or packages
git submodule add [email protected]:org/shared-config.git config
```

### Monorepo vs Polyrepo Decision Matrix

| Factor | Monorepo | Polyrepo |
|--------|----------|----------|
| Team Size | Large teams | Small, autonomous teams |