How to fix fatal: ref HEAD is not a symbolic ref, cannot determine current branch in Git

# Check HEAD status
git symbolic-ref HEAD
# If detached, you'll see: fatal: ref HEAD is not a symbolic ref

# Check what HEAD points to
cat .git/HEAD
# Detached: Shows a commit SHA (e.g., "a1b2c3d4e5f6...")
# Normal: Shows "ref: refs/heads/main" or similar

# Alternative check using rev-parse
git rev-parse --abbrev-ref HEAD
# Returns "HEAD" if detached, or branch name if on a branch

# Modern alternative (Git 2.22+)
git branch --show-current
# Returns empty string if detached, or branch name if on a branch

# Checkout the main branch
git checkout main

# Or checkout a specific branch
git checkout develop

# Force checkout if there are conflicts
git checkout -f main

#!/bin/bash
# Ensure we're on a branch, not detached HEAD
BRANCH=${BRANCH_NAME:-main}
git checkout -f "$BRANCH" || git checkout -B "$BRANCH" origin/"$BRANCH"

- uses: actions/checkout@v4
  with:
    ref: main

- uses: actions/checkout@v4
  with:
    ref: ${{ github.head_ref }}

- uses: actions/checkout@v4
  with:
    ref: ${{ github.event.release.target_commitish }}

- uses: actions/checkout@v4

- name: Checkout branch (not detached HEAD)
  run: |
    git checkout -B "${{ github.ref_name }}" || true

- uses: peter-evans/create-pull-request@v5
  with:
    base: main  # Handles commit checkouts by rebasing

checkout([
    $class: 'GitSCM',
    branches: [[name: '*/main']],
    extensions: [
        [$class: 'LocalBranch', localBranch: '**'],
        [$class: 'CleanCheckout']
    ],
    userRemoteConfigs: [[url: 'https://github.com/your/repo.git']]
])

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                checkout scm: [
                    $class: 'GitSCM',
                    extensions: [[$class: 'LocalBranch', localBranch: '**']]
                ]
            }
        }
    }
}

sh '''
    git checkout -f ${BRANCH_NAME}
'''

before_script:
  - git checkout -B "$CI_COMMIT_REF_NAME" "$CI_COMMIT_SHA"
  # Or simply:
  - git checkout "$CI_COMMIT_REF_NAME"

release:
  stage: deploy
  before_script:
    - git fetch origin
    - git checkout -f $CI_COMMIT_REF_NAME
  script:
    - mvn release:prepare release:perform

variables:
  GIT_STRATEGY: fetch
  GIT_CHECKOUT: "true"

before_script:
  - git checkout $CI_COMMIT_REF_NAME

mvn release:prepare -DpushChanges=false -DlocalCheckout=true \
    -DdevelopmentVersion=1.0.1-SNAPSHOT \
    -DreleaseVersion=1.0.0

#!/bin/bash
# Run before mvn release:prepare
BRANCH=${GIT_BRANCH:-main}
BRANCH=${BRANCH#origin/}  # Remove origin/ prefix if present
git checkout -f "$BRANCH"

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-release-plugin</artifactId>
    <version>3.0.1</version>
    <configuration>
        <localCheckout>true</localCheckout>
        <pushChanges>false</pushChanges>
    </configuration>
</plugin>

# DON'T use this - fails on detached HEAD
git symbolic-ref --short HEAD

# Returns empty string on detached HEAD (no error)
BRANCH=$(git branch --show-current)
if [ -z "$BRANCH" ]; then
    echo "Detached HEAD - no branch"
else
    echo "On branch: $BRANCH"
fi

# Returns "HEAD" if detached, otherwise returns branch name
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [ "$BRANCH" = "HEAD" ]; then
    echo "Detached HEAD state"
else
    echo "On branch: $BRANCH"
fi

# Exit code 1 on detached HEAD, no error message
if git symbolic-ref -q HEAD > /dev/null; then
    BRANCH=$(git symbolic-ref --short HEAD)
    echo "On branch: $BRANCH"
else
    echo "Detached HEAD state"
fi

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full history
    ref: main       # Checkout branch, not detached

variables:
  GIT_DEPTH: 0  # Full clone, not shallow
  GIT_STRATEGY: clone

before_script:
  - git checkout $CI_COMMIT_REF_NAME

# Convert shallow to full clone if needed
git fetch --unshallow origin || true
git fetch origin "+refs/heads/*:refs/remotes/origin/*"
git checkout $BRANCH_NAME