Git Branch Naming Conventions

Overview

Consistent branch naming enables automated workflows, improves team collaboration, and provides clear context about development work. Follow these conventions for integration with CI/CD pipelines and project management tools.

Branch Naming Structure

Standard Format

<type>/<scope>-<description>

Branch Type Flow

graph TD
    A[New Development Work] --> B{Work Type?}

    B -->|New Feature| C[feature/]
    B -->|Bug Fix| D[fix/]
    B -->|Hotfix| E[hotfix/]
    B -->|Chore/Maintenance| F[chore/]
    B -->|Refactoring| G[refactor/]
    B -->|Documentation| H[docs/]
    B -->|Experimental| I[experiment/]

    C --> J[Add Scope & Description]
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J

    J --> K[feature/auth-jwt-implementation]
    J --> L[fix/payment-gateway-timeout]
    J --> M[hotfix/security-vulnerability-patch]

Branch Types

feature/ - New Features

Developing new functionality or capabilities

# Standard format
feature/user-authentication
feature/payment-integration
feature/dashboard-analytics

# With ClickUp task ID (REQUIRED for automation)
feature/CU-abc123-payment-integration
feature/CU-2x8zp19-user-authentication-system

fix/ - Bug Fixes

Fixing existing functionality issues

# Standard format
fix/login-validation-error
fix/payment-gateway-timeout
fix/mobile-responsive-issue

# With ClickUp task ID
fix/CU-def456-mobile-responsive-issue
fix/CU-3y9aq20-login-validation-safari

hotfix/ - Critical Production Fixes

Emergency fixes for critical production issues

# Standard format
hotfix/critical-security-patch
hotfix/production-database-fix
hotfix/payment-processing-error

# With ClickUp task ID
hotfix/CU-ghi789-critical-security-patch
hotfix/CU-4z0br31-payment-gateway-timeout

chore/ - Maintenance Tasks

Maintenance, updates, and non-feature work

chore/dependency-updates
chore/cleanup-unused-code
chore/deps-update-react-18
chore/lint-fix-typescript-errors

refactor/ - Code Restructuring

Improving code structure without changing functionality

refactor/auth-service-simplification
refactor/database-query-optimization
refactor/performance-user-queries
refactor/bundle-size-reduction

docs/ - Documentation

Documentation-only changes

docs/api-endpoint-documentation
docs/readme-update-installation
docs/contributing-guidelines-update
docs/openapi-schema-update

experiment/ - Experimental Features

Proof of concept and experimental development

experiment/ai-recommendation-engine
experiment/performance-worker-threads
experiment/poc-serverless-deployment
experiment/prototype-realtime-collaboration

Scope Guidelines

Frontend Scopes

# Component-based
feature/button-loading-states
fix/navbar-mobile-toggle

# Page/Route-based
feature/dashboard-analytics-page
fix/checkout-payment-flow

# Feature-based
feature/auth-two-factor
fix/search-functionality

Backend Scopes

# Service-based
feature/user-service-registration
fix/payment-service-webhook

# API-based
feature/api-v2-endpoints
fix/api-validation-middleware

# Database-based
feature/database-user-profiles
fix/database-connection-pooling

Infrastructure Scopes

# Infrastructure
feature/docker-multi-stage-builds
fix/kubernetes-deployment-config

# CI/CD
feature/github-actions-deployment
fix/ci-test-coverage-reporting

# Monitoring
feature/prometheus-metrics-collection
fix/grafana-dashboard-alerts

ClickUp Integration (Primary)

Required for automation - Task IDs in branch names enable automatic PR linking and status updates.

# ClickUp task format (REQUIRED)
feature/CU-abc123-payment-integration
fix/CU-def456-mobile-responsive-issue
hotfix/CU-ghi789-critical-security-patch
chore/CU-jkl012-dependency-updates

# Examples with full descriptions
feature/CU-2x8zp19-user-authentication-system
fix/CU-3y9aq20-login-validation-safari
hotfix/CU-4z0br31-payment-gateway-timeout

Note: Use exact ClickUp task ID format (e.g., CU-abc123). Find task ID in ClickUp URL or copy from task details.

Automation Benefits: - PR automatically links to ClickUp task - Task status updates on PR merge - Streamlined workflow tracking

See GitHub-ClickUp Integration Workflow for setup and usage.

Alternative Issue Tracking Systems

GitHub Issues:

feature/123-user-authentication
fix/456-payment-gateway-bug
feature/123-124-user-profile-system

Jira:

feature/AZMX-123-user-dashboard
fix/AZMX-456-login-validation
hotfix/AZMX-789-security-vulnerability

Team-Specific Conventions

Optional Team/Technology Prefixes

Use for large teams or multi-technology projects:

# Team prefixes
frontend/feature/component-library
backend/feature/api-authentication
devops/feature/monitoring-setup

# Technology-specific
react/feature/hooks-custom-auth
django/feature/admin-interface
k8s/fix/ingress-configuration

Quick Reference

Type	Purpose	Example
feature/	New functionality	`feature/CU-123-user-auth`
fix/	Bug fixes	`fix/CU-456-login-error`
hotfix/	Critical production fixes	`hotfix/CU-789-security-patch`
chore/	Maintenance tasks	`chore/dependency-updates`
refactor/	Code restructuring	`refactor/database-optimization`
docs/	Documentation only	`docs/api-documentation`
experiment/	POC/experimental	`experiment/ai-integration`

Validation Rules

Naming Requirements

Format: <type>/<scope>-<description>
Case: lowercase with hyphens
Length: 10-50 characters
Pattern: Letters, numbers, hyphens only
ClickUp ID: CU-xxxxx format when using task integration

Valid Examples

# ✅ Good
feature/user-authentication
fix/login-validation-error
feature/CU-abc123-payment-integration
hotfix/critical-security-patch

# ❌ Bad
Feature/User-Authentication  # Wrong case
fix_login_bug                # Underscore instead of hyphen
feature/updates              # Too generic
HOTFIX-SECURITY             # Wrong format

Branch Naming Validation

Git Hook for Validation

#!/bin/sh
# .git/hooks/pre-push

branch=$(git rev-parse --abbrev-ref HEAD)
valid_pattern="^(feature|fix|hotfix|chore|refactor|docs|experiment)\/[a-z0-9-]+$"

if [[ ! $branch =~ $valid_pattern ]]; then
  echo "❌ Invalid branch name: $branch"
  echo "Branch name must follow pattern: <type>/<scope>-<description>"
  echo "Valid types: feature, fix, hotfix, chore, refactor, docs, experiment"
  echo "Example: feature/user-authentication"
  exit 1
fi

echo "✅ Branch name is valid: $branch"

Branch Lifecycle

Creation Workflow

graph LR
    A[Issue Created] --> B[Create Branch]
    B --> C[Name Following Convention]
    C --> D[Local Development]
    D --> E[Push to Remote]
    E --> F[Create Pull Request]
    F --> G[Code Review]
    G --> H{Approved?}
    H -->|Yes| I[Merge to Main]
    H -->|No| J[Address Feedback]
    J --> D
    I --> K[Delete Branch]

Branch Cleanup

# Delete local merged branches
git branch --merged main | grep -v "main\|develop" | xargs -n 1 git branch -d

# Delete remote tracking branches that no longer exist
git remote prune origin

Common Anti-Patterns

Too Generic

❌ feature/updates
❌ fix/bugs
❌ chore/cleanup

✅ feature/user-profile-picture-upload
✅ fix/login-form-validation-error
✅ chore/npm-dependency-security-updates

Too Long

❌ feature/implement-comprehensive-user-authentication-system-with-two-factor-support

✅ feature/user-auth-two-factor

Inconsistent Format

❌ Feature/User-Authentication
❌ fix_login_bug
❌ HOTFIX-SECURITY

✅ feature/user-authentication
✅ fix/login-validation-error
✅ hotfix/security-vulnerability-patch

Handling Conflicts

# If branch name already exists, append version or developer name
feature/user-auth-v2
feature/john-user-profile-api

# For similar features by different developers
feature/john-user-profile-api
feature/sarah-user-profile-ui

Git Workflow - Basic Git workflow implementation
Git Commit Standards - Commit message conventions
Git Branching Strategy - Advanced GitFlow strategy
GitHub-ClickUp Integration Workflow - ClickUp automation setup
Pre-commit Hooks - Automated validation setup

Last Updated: 2025-01-20 Tools Required: Git, GitHub/GitLab, branch naming validation hooks Team Contacts: Tech Leads for scope definitions, DevOps for automation setup