Git Branch Strategy Best Practices - Complete Guide

# GitFlow Branch Strategy

# 1. Main Branches
# master/main - Production-ready code
git checkout -b main
git push -u origin main

# develop - Integration branch for features
git checkout -b develop
git push -u origin develop

# 2. Supporting Branches
# Feature branches
git checkout develop
git checkout -b feature/user-authentication
git push -u origin feature/user-authentication

# Release branches
git checkout develop
git checkout -b release/v1.2.0
git push -u origin release/v1.2.0

# Hotfix branches
git checkout main
git checkout -b hotfix/critical-bug-fix
git push -u origin hotfix/critical-bug-fix

# 3. GitFlow Commands
# Install GitFlow
# macOS
brew install git-flow-avh

# Ubuntu/Debian
sudo apt install git-flow

# Initialize GitFlow
git flow init

# Start feature
git flow feature start user-authentication

# Finish feature
git flow feature finish user-authentication

# Start release
git flow release start 1.2.0

# Finish release
git flow release finish 1.2.0

# Start hotfix
git flow hotfix start critical-bug-fix

# Finish hotfix
git flow hotfix finish critical-bug-fix

# 4. GitFlow Workflow Example
# Feature Development
git flow feature start new-feature
# ... make changes ...
git add .
git commit -m "Add new feature implementation"
git flow feature finish new-feature

# Release Process
git flow release start 1.3.0
# ... update version numbers, changelog ...
git add .
git commit -m "Prepare release 1.3.0"
git flow release finish 1.3.0

# Hotfix Process
git flow hotfix start security-patch
# ... fix critical issue ...
git add .
git commit -m "Fix security vulnerability"
git flow hotfix finish security-patch

# GitHub Flow Strategy

# 1. Simple Branch Structure
# main - Production-ready code
# feature branches - All development work

# 2. GitHub Flow Workflow
# Create feature branch
git checkout main
git pull origin main
git checkout -b feature/new-dashboard

# Make changes and commit
git add .
git commit -m "Add new dashboard component"
git push origin feature/new-dashboard

# Create Pull Request
# Merge to main after review

# 3. Branch Naming Conventions
# Feature branches
feature/user-profile
feature/payment-integration
feature/dashboard-redesign

# Bug fix branches
bugfix/login-error
bugfix/memory-leak
bugfix/performance-issue

# Hotfix branches
hotfix/security-patch
hotfix/critical-bug
hotfix/data-corruption

# 4. GitHub Flow Commands
# Start new feature
git checkout main
git pull origin main
git checkout -b feature/feature-name

# Work on feature
git add .
git commit -m "Descriptive commit message"
git push origin feature/feature-name

# Update feature branch
git checkout main
git pull origin main
git checkout feature/feature-name
git rebase main

# Clean up after merge
git checkout main
git pull origin main
git branch -d feature/feature-name
git push origin --delete feature/feature-name

# 5. Pull Request Workflow
# Create Pull Request with:
# - Clear title
# - Detailed description
# - Link to related issues
# - Screenshots if UI changes
# - Testing instructions

# Pull Request Template
# Title: [Feature] Add user authentication
# 
# Description:
# This PR adds user authentication functionality including:
# - Login/logout forms
# - JWT token management
# - Protected routes
# 
# Changes:
# - Added AuthService class
# - Created login/logout components
# - Updated routing configuration
# 
# Testing:
# - [ ] Unit tests pass
# - [ ] Integration tests pass
# - [ ] Manual testing completed
# 
# Related Issues:
# Closes #123

# 6. Continuous Integration
# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
    - name: Install dependencies
      run: npm install
    - name: Run tests
      run: npm test
    - name: Run linting
      run: npm run lint

# GitLab Flow Strategy

# 1. GitLab Flow Branches
# main - Production-ready code
# staging - Pre-production testing
# feature branches - Development work

# 2. Environment-based Flow
# main -> staging -> production

# Create feature branch
git checkout main
git pull origin main
git checkout -b feature/api-integration

# Work on feature
git add .
git commit -m "Add API integration"
git push origin feature/api-integration

# Merge to main
git checkout main
git merge feature/api-integration
git push origin main

# Deploy to staging
git checkout staging
git merge main
git push origin staging

# Deploy to production
git checkout production
git merge staging
git push origin production

# 3. GitLab CI/CD Integration
# .gitlab-ci.yml
stages:
  - test
  - build
  - deploy-staging
  - deploy-production

variables:
  NODE_VERSION: "18"

test:
  stage: test
  image: node:${NODE_VERSION}
  script:
    - npm install
    - npm test
    - npm run lint
  only:
    - main
    - staging
    - merge_requests

build:
  stage: build
  image: node:${NODE_VERSION}
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - dist/
  only:
    - main
    - staging

deploy-staging:
  stage: deploy-staging
  script:
    - echo "Deploying to staging"
    - # Add deployment commands
  only:
    - staging

deploy-production:
  stage: deploy-production
  script:
    - echo "Deploying to production"
    - # Add deployment commands
  only:
    - main
  when: manual

# 4. Issue-driven Development
# Create issue in GitLab
# Create branch from issue
git checkout -b 123-add-user-profile

# Work on issue
git add .
git commit -m "Implement user profile page

Closes #123"

# Push and create merge request
git push origin 123-add-user-profile

# 5. Release Management
# Create release branch
git checkout main
git checkout -b release/2.0.0

# Update version and changelog
git add .
git commit -m "Prepare release 2.0.0"
git push origin release/2.0.0

# Create merge request to main
# After approval, merge and tag
git checkout main
git merge release/2.0.0
git tag -a v2.0.0 -m "Release version 2.0.0"
git push origin v2.0.0

# Branch Naming Conventions

# 1. Prefix-based Naming
# Feature branches
feature/user-authentication
feature/payment-integration
feature/dashboard-redesign

# Bug fix branches
bugfix/login-error
bugfix/memory-leak
bugfix/performance-issue

# Hotfix branches
hotfix/security-patch
hotfix/critical-bug
hotfix/data-corruption

# Release branches
release/v1.2.0
release/v2.0.0
release/v1.2.1

# Development branches
develop
staging
integration

# 2. Issue-based Naming
# GitHub/GitLab issue numbers
123-add-user-profile
456-fix-login-bug
789-implement-search

# Jira ticket numbers
PROJ-123-feature-name
BUG-456-fix-description
TASK-789-implementation

# 3. Team-based Naming
# Team prefixes
frontend/user-dashboard
backend/api-integration
mobile/push-notifications
devops/deployment-script

# Developer prefixes
john/feature-name
sarah/bugfix-description
mike/refactor-component

# 4. Date-based Naming
# For time-sensitive branches
2024-01-15-security-update
2024-01-20-performance-fix
2024-01-25-feature-release

# 5. Semantic Naming
# Using semantic versioning
v1.2.3-feature-name
v2.0.0-breaking-changes
v1.2.4-bug-fixes

# 6. Branch Naming Script
#!/bin/bash
# branch-naming-helper.sh

# Function to create properly named branch
create_branch() {
    local type=$1
    local name=$2
    local issue_number=$3
    
    # Validate branch type
    case $type in
        feature|bugfix|hotfix|release)
            ;;
        *)
            echo "Invalid branch type. Use: feature, bugfix, hotfix, release"
            return 1
            ;;
    esac
    
    # Create branch name
    if [ -n "$issue_number" ]; then
        branch_name="${type}/${issue_number}-${name}"
    else
        branch_name="${type}/${name}"
    fi
    
    # Create and checkout branch
    git checkout -b "$branch_name"
    echo "Created branch: $branch_name"
}

# Usage examples
# create_branch feature "user-authentication" "123"
# create_branch bugfix "login-error" "456"
# create_branch hotfix "security-patch"

# 7. Branch Validation Hook
# .git/hooks/pre-push
#!/bin/bash

# Check branch naming convention
current_branch=$(git rev-parse --abbrev-ref HEAD)

# Allowed patterns
allowed_patterns=(
    "^main$"
    "^develop$"
    "^staging$"
    "^feature/.*"
    "^bugfix/.*"
    "^hotfix/.*"
    "^release/.*"
    "^[0-9]+-.*"
)

# Check if branch matches allowed patterns
for pattern in "${allowed_patterns[@]}"; do
    if [[ $current_branch =~ $pattern ]]; then
        exit 0
    fi
done

echo "Error: Branch '$current_branch' does not follow naming convention"
echo "Allowed patterns:"
echo "  - main, develop, staging"
echo "  - feature/description"
echo "  - bugfix/description"
echo "  - hotfix/description"
echo "  - release/version"
echo "  - issue-number-description"
exit 1

# Branch Protection Rules

# 1. GitHub Branch Protection
# Repository Settings > Branches > Add rule

# Branch name pattern: main
# Settings:
# - Require a pull request before merging
# - Require approvals: 2
# - Dismiss stale PR approvals when new commits are pushed
# - Require review from code owners
# - Require status checks to pass before merging
# - Require branches to be up to date before merging
# - Require conversation resolution before merging
# - Require signed commits
# - Require linear history
# - Include administrators
# - Restrict pushes that create files
# - Allow force pushes: Never
# - Allow deletions: Never

# 2. GitLab Branch Protection
# Project Settings > Repository > Protected branches

# Branch: main
# Allowed to push: Maintainers
# Allowed to merge: Maintainers
# Allowed to unprotect: Maintainers

# Branch: develop
# Allowed to push: Developers + Maintainers
# Allowed to merge: Developers + Maintainers
# Allowed to unprotect: Maintainers

# 3. Branch Protection Script
#!/bin/bash
# setup-branch-protection.sh

# GitHub CLI required
# gh auth login

# Protect main branch
gh api repos/:owner/:repo/branches/main/protection \
  --method PUT \
  --field required_status_checks='{"strict":true,"contexts":["ci/tests","ci/lint"]}' \
  --field enforce_admins=true \
  --field required_pull_request_reviews='{"required_approving_review_count":2,"dismiss_stale_reviews":true,"require_code_owner_reviews":true}' \
  --field restrictions='{"users":[],"teams":[]}' \
  --field allow_force_pushes=false \
  --field allow_deletions=false

# Protect develop branch
gh api repos/:owner/:repo/branches/develop/protection \
  --method PUT \
  --field required_status_checks='{"strict":true,"contexts":["ci/tests"]}' \
  --field enforce_admins=false \
  --field required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}' \
  --field restrictions='{"users":[],"teams":[]}' \
  --field allow_force_pushes=false \
  --field allow_deletions=false

# 4. CODEOWNERS File
# .github/CODEOWNERS

# Global owners
* @team-leads

# Frontend code
/src/components/ @frontend-team
/src/pages/ @frontend-team
/src/styles/ @frontend-team

# Backend code
/api/ @backend-team
/server/ @backend-team
/database/ @backend-team

# Documentation
/docs/ @tech-writers
/README.md @tech-writers

# Configuration files
/.github/ @devops-team
/docker/ @devops-team
/kubernetes/ @devops-team

# 5. Required Status Checks
# .github/workflows/required-checks.yml
name: Required Checks

on:
  pull_request:
    branches: [ main, develop ]

jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
    - name: Install dependencies
      run: npm install
    - name: Run tests
      run: npm test
    - name: Run linting
      run: npm run lint
    - name: Run type checking
      run: npm run type-check

  security:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Run security audit
      run: npm audit --audit-level moderate

  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
    - name: Install dependencies
      run: npm install
    - name: Build application
      run: npm run build

# 6. Branch Protection Validation
#!/bin/bash
# validate-branch-protection.sh

# Check if branch is protected
check_branch_protection() {
    local branch=$1
    local repo=$2
    
    # Check GitHub branch protection
    if gh api repos/:owner/:repo/branches/$branch/protection >/dev/null 2>&1; then
        echo "Branch $branch is protected"
        return 0
    else
        echo "Branch $branch is not protected"
        return 1
    fi
}

# Check all important branches
check_branch_protection "main" "my-repo"
check_branch_protection "develop" "my-repo"
check_branch_protection "staging" "my-repo"

# Branch Management Tools

# 1. Git Hooks for Branch Management
# .git/hooks/pre-commit
#!/bin/bash

# Check branch naming
current_branch=$(git rev-parse --abbrev-ref HEAD)

# Skip check for main branches
if [[ $current_branch =~ ^(main|develop|staging)$ ]]; then
    exit 0
fi

# Check branch naming convention
if [[ ! $current_branch =~ ^(feature|bugfix|hotfix|release)/ ]]; then
    echo "Error: Branch '$current_branch' must start with feature/, bugfix/, hotfix/, or release/"
    exit 1
fi

# Check commit message format
commit_msg_file=$1
commit_msg=$(cat "$commit_msg_file")

if [[ ! $commit_msg =~ ^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .+ ]]; then
    echo "Error: Commit message must follow conventional commit format"
    echo "Format: type(scope): description"
    echo "Types: feat, fix, docs, style, refactor, test, chore"
    exit 1
fi

# 2. Branch Cleanup Script
#!/bin/bash
# cleanup-branches.sh

# Function to clean up merged branches
cleanup_merged_branches() {
    echo "Cleaning up merged branches..."
    
    # Update main branch
    git checkout main
    git pull origin main
    
    # List merged branches
    merged_branches=$(git branch --merged main | grep -v main | grep -v develop)
    
    if [ -z "$merged_branches" ]; then
        echo "No merged branches to clean up"
        return
    fi
    
    echo "Merged branches:"
    echo "$merged_branches"
    
    # Confirm deletion
    read -p "Delete these branches? (y/N): " -n 1 -r
    echo
    
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        echo "$merged_branches" | xargs git branch -d
        echo "Local branches deleted"
        
        # Delete remote branches
        echo "$merged_branches" | xargs -I {} git push origin --delete {}
        echo "Remote branches deleted"
    fi
}

# Function to clean up stale branches
cleanup_stale_branches() {
    echo "Cleaning up stale branches..."
    
    # Fetch latest remote branches
    git fetch --prune
    
    # List stale branches (not on remote)
    stale_branches=$(git branch -vv | grep ': gone]' | awk '{print $1}')
    
    if [ -z "$stale_branches" ]; then
        echo "No stale branches found"
        return
    fi
    
    echo "Stale branches:"
    echo "$stale_branches"
    
    # Confirm deletion
    read -p "Delete these stale branches? (y/N): " -n 1 -r
    echo
    
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        echo "$stale_branches" | xargs git branch -D
        echo "Stale branches deleted"
    fi
}

# Main cleanup function
main() {
    case $1 in
        merged)
            cleanup_merged_branches
            ;;
        stale)
            cleanup_stale_branches
            ;;
        all)
            cleanup_merged_branches
            cleanup_stale_branches
            ;;
        *)
            echo "Usage: $0 {merged|stale|all}"
            exit 1
            ;;
    esac
}

main "$@"

# 3. Branch Status Dashboard
#!/bin/bash
# branch-status.sh

# Function to show branch status
show_branch_status() {
    echo "=== Branch Status Dashboard ==="
    echo
    
    # Current branch
    current_branch=$(git rev-parse --abbrev-ref HEAD)
    echo "Current branch: $current_branch"
    echo
    
    # Branch information
    echo "Branch Information:"
    git for-each-ref --format='%(refname:short) %(committerdate:relative) %(authorname)' refs/heads/ | head -10
    echo
    
    # Remote branches
    echo "Remote branches:"
    git branch -r | head -10
    echo
    
    # Uncommitted changes
    if [ -n "$(git status --porcelain)" ]; then
        echo "Uncommitted changes:"
        git status --short
        echo
    fi
    
    # Ahead/behind status
    if [ "$current_branch" != "main" ]; then
        ahead=$(git rev-list --count main..HEAD)
        behind=$(git rev-list --count HEAD..main)
        
        if [ $ahead -gt 0 ]; then
            echo "Ahead of main by $ahead commits"
        fi
        
        if [ $behind -gt 0 ]; then
            echo "Behind main by $behind commits"
        fi
    fi
}

show_branch_status

# 4. Branch Comparison Tool
#!/bin/bash
# compare-branches.sh

# Function to compare branches
compare_branches() {
    local branch1=$1
    local branch2=$2
    
    if [ -z "$branch1" ] || [ -z "$branch2" ]; then
        echo "Usage: $0  "
        exit 1
    fi
    
    echo "Comparing branches: $branch1 vs $branch2"
    echo
    
    # Show commits in branch1 but not in branch2
    echo "Commits in $branch1 but not in $branch2:"
    git log --oneline $branch2..$branch1
    echo
    
    # Show commits in branch2 but not in branch1
    echo "Commits in $branch2 but not in $branch1:"
    git log --oneline $branch1..$branch2
    echo
    
    # Show file differences
    echo "File differences:"
    git diff --name-status $branch1..$branch2
}

compare_branches "$1" "$2"

# 5. Branch Creation Helper
#!/bin/bash
# create-branch.sh

# Function to create branch with validation
create_branch() {
    local type=$1
    local name=$2
    local issue_number=$3
    
    # Validate inputs
    if [ -z "$type" ] || [ -z "$name" ]; then
        echo "Usage: $0   [issue_number]"
        echo "Types: feature, bugfix, hotfix, release"
        exit 1
    fi
    
    # Validate branch type
    case $type in
        feature|bugfix|hotfix|release)
            ;;
        *)
            echo "Invalid branch type. Use: feature, bugfix, hotfix, release"
            exit 1
            ;;
    esac
    
    # Create branch name
    if [ -n "$issue_number" ]; then
        branch_name="${type}/${issue_number}-${name}"
    else
        branch_name="${type}/${name}"
    fi
    
    # Check if branch exists
    if git show-ref --verify --quiet refs/heads/"$branch_name"; then
        echo "Branch $branch_name already exists"
        exit 1
    fi
    
    # Create and checkout branch
    git checkout -b "$branch_name"
    echo "Created and switched to branch: $branch_name"
    
    # Push to remote
    git push -u origin "$branch_name"
    echo "Pushed branch to remote"
}

create_branch "$1" "$2" "$3"