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

# Check if a tag name is valid
git check-ref-format "refs/tags/your-tag-name" && echo "Valid" || echo "Invalid"

# Alternative: check with the tags prefix
git check-ref-format --allow-onelevel "your-tag-name" && echo "Valid" || echo "Invalid"

# Instead of spaces, use hyphens or underscores
git tag "v1.0-beta-1"      # Not: "v1.0 beta 1"

# Instead of special characters, use descriptive text
git tag "v2.0-feature-x"   # Not: "v2.0[feature]"
git tag "v1.0-rc1"         # Not: "v1.0~rc1"

# Use single dots, not double
git tag "v1.0.1"           # Not: "v1..1"

# Valid characters for Git tags:
# - Alphanumeric: a-z, A-Z, 0-9
# - Hyphens: -
# - Underscores: _
# - Single dots: .
# - Forward slashes: / (not at start/end)

# Brackets are interpreted by shells like zsh
git tag "[1.0]"            # zsh: no matches found: [1.0]

# Even with quotes, these characters are still invalid in Git
# The error changes from shell error to Git error
git tag 'v1.0[beta]'       # fatal: 'v1.0[beta]' is not a valid tag name

# Solution: use valid characters instead
git tag "v1.0-beta"

# Check for hidden characters using cat with special flags
echo "v1.0.0" | cat -A
# Should show: v1.0.0$
# If you see ^M or other symbols, there are hidden characters

# Check using hexdump
echo "v1.0.0" | hexdump -C
# Look for bytes other than expected ASCII letters/numbers

# In scripts, trim whitespace from variables
TAG_NAME=$(echo "$TAG_NAME" | tr -d '[:space:]')
git tag "$TAG_NAME"

# Or use parameter expansion in bash
TAG_NAME="${TAG_NAME//[$'\t\r\n']}"
git tag "$TAG_NAME"

# Standard semantic versioning (always valid)
git tag "v1.0.0"
git tag "v2.1.3"
git tag "1.0.0"            # v prefix is optional

# Pre-release versions (use hyphens, not tildes)
git tag "v1.0.0-alpha.1"
git tag "v1.0.0-beta.2"
git tag "v1.0.0-rc.1"

# Build metadata (use plus sign, which is valid)
git tag "v1.0.0+build.123"
git tag "v1.0.0-beta.1+sha.abc123"

# Valid hierarchical tags
git tag "release/v1.0.0"
git tag "feature/awesome-feature"

# Invalid patterns
git tag "/v1.0.0"          # Cannot start with /
git tag "v1.0.0/"          # Cannot end with /
git tag "release//v1.0.0"  # Cannot have consecutive slashes
git tag ".hidden/tag"      # Components cannot start with .
git tag "release/v1.lock"  # Components cannot end with .lock

# Fix by removing leading/trailing slashes
git tag "release/v1.0.0"   # Correct

# Normalize a tag name (fixes consecutive slashes)
git check-ref-format --normalize "refs/tags/release//v1.0"
# Output: refs/tags/release/v1.0

# Create a shell function to validate before tagging
validate_tag() {
  if git check-ref-format "refs/tags/$1" 2>/dev/null; then
    echo "Valid tag name: $1"
    return 0
  else
    echo "Invalid tag name: $1"
    return 1
  fi
}

# Use it before creating tags
validate_tag "v1.0.0" && git tag "v1.0.0"

# Bash function to sanitize tag names
sanitize_tag() {
  echo "$1" | \
    tr '[:upper:]' '[:lower:]' | \    # Optional: lowercase
    sed 's/[^a-zA-Z0-9._-]/-/g' | \   # Replace invalid chars
    sed 's/--*/-/g' | \               # Remove consecutive hyphens
    sed 's/^-//' | \                  # Remove leading hyphen
    sed 's/-$//'                       # Remove trailing hyphen
}

# Usage
RAW_TAG="v1.0 [beta]"
CLEAN_TAG=$(sanitize_tag "$RAW_TAG")
git tag "$CLEAN_TAG"  # Creates: v1.0-beta

- name: Create sanitized tag
  run: |
    TAG_NAME=${{ github.event.inputs.tag }}
    SAFE_TAG=$(echo "$TAG_NAME" | sed 's/[^a-zA-Z0-9._-]/-/g')
    git tag "$SAFE_TAG"
    git push origin "$SAFE_TAG"