How to fix fatal: 'branch name' is not a valid branch name in Git

# If you tried this:
git checkout -b -my-feature
# Git responds: fatal: '-my-feature' is not a valid branch name

# The leading hyphen is the problem

# Check if a branch name is valid
git check-ref-format --branch "my-branch-name"
# Returns 0 if valid, non-zero if invalid

# Or with verbose output
git check-ref-format --branch "my-branch-name" && echo "Valid" || echo "Invalid"

git checkout -b -bugfix
# fatal: '-bugfix' is not a valid branch name

# Option 1: Use a prefix before the hyphen
git checkout -b fix-bugfix

# Option 2: Use a different separator
git checkout -b bugfix_123

# Option 3: Use a category prefix (recommended)
git checkout -b bugfix/issue-123

# Strip leading hyphens in a script
BRANCH_NAME="-my-branch"
SAFE_NAME="${BRANCH_NAME#-}"  # Removes leading hyphen
git checkout -b "$SAFE_NAME"

# These will all fail:
git checkout -b HEAD        # fatal: 'HEAD' is not a valid branch name
git checkout -b FETCH_HEAD  # Same error

# Use descriptive names instead
git checkout -b feature/head-refactor
git checkout -b update-fetch-logic

# These all fail:
git checkout -b "feature branch"    # Space
git checkout -b "feature~1"         # Tilde
git checkout -b "fix:bug"           # Colon
git checkout -b "test..suite"       # Double dots

# Replace with hyphens or underscores
git checkout -b feature-branch
git checkout -b feature_1
git checkout -b fix-bug
git checkout -b test-suite

# Or use slashes for hierarchy
git checkout -b feature/branch-name

# These fail:
git checkout -b .hidden           # Starts with dot
git checkout -b feature.lock      # Ends with .lock
git checkout -b v1..v2            # Contains ..
git checkout -b refs/heads/.test  # Component starts with dot

# For hidden-like names, use a prefix
git checkout -b dot-hidden
git checkout -b _hidden

# For lock-like names, use different suffix
git checkout -b feature-locked
git checkout -b feature.locked

# For version ranges, use single dots or hyphens
git checkout -b v1.2
git checkout -b v1-to-v2

# These fail:
git checkout -b feature/          # Ends with slash
git checkout -b feature//login    # Consecutive slashes
git checkout -b feature/.hidden   # Component starts with dot

# Remove trailing slashes
git checkout -b feature/login

# Remove duplicate slashes
git checkout -b feature/user/login

# Ensure each component is valid
git checkout -b feature/hidden-file

# Basic validation
git check-ref-format --branch "proposed-name"

# Normalize a name (fix some issues automatically)
git check-ref-format --normalize "refs/heads/FEATURE"
# Output: refs/heads/feature (lowercased)

# In a script:
validate_branch_name() {
  local name="$1"
  if git check-ref-format --branch "$name" >/dev/null 2>&1; then
    echo "Valid branch name: $name"
    return 0
  else
    echo "Invalid branch name: $name"
    return 1
  fi
}

# Usage
validate_branch_name "feature/new-login" && git checkout -b "feature/new-login"

# If you get an error fetching:
# fatal: 'origin/feature branch' is not a valid branch name

# You'll need to rename it on the remote
# First, on a system where the branch exists:
git branch -m "feature branch" "feature-branch"
git push origin "feature-branch"
git push origin --delete "feature branch"

# List all branches
git branch -a

# Rename problematic local branches
git branch -m "old name" "new-name"

# Push with the new name and delete the old
git push origin "new-name"
git push origin --delete "old name"