How to fix warning: refname 'feature' is ambiguous in Git

GitBEGINNERLOW

This Git warning occurs when a reference name (like 'feature') matches multiple refs such as a branch and a tag with the same name. Git cannot determine which one you mean, so you need to use the full refname or remove the duplicate reference.

What this error means

This warning appears when Git finds multiple references matching the same name in your repository. Git stores references in several namespaces: `refs/heads/` for branches, `refs/tags/` for tags, `refs/remotes/` for remote-tracking branches, and others. When you use a short reference name like "feature", Git searches through these namespaces in a specific order. If it finds "feature" in more than one location (for example, both `refs/heads/feature` and `refs/tags/feature`), it issues this ambiguous refname warning. While Git will typically proceed using its priority rules (branches usually take precedence over tags), the warning indicates that you may not be working with the reference you intended. This can lead to unexpected behavior, especially during merges, checkouts, or when setting upstream branches.

How to fix "warning: refname 'feature' is ambiguous"

1Identify all conflicting references

First, find all references that match the ambiguous name:

bash

# Show all refs matching the name
git show-ref feature

# Example output showing conflict:
# a1b2c3d refs/heads/feature
# e4f5g6h refs/tags/feature

You can also search more broadly:

bash

# Find all references containing the name
git show-ref | grep feature

# List all branches and tags
git branch -a
git tag -l

This will reveal whether the ambiguity is between a branch and tag, or involves other reference types.

2Use full refname to specify the exact reference

To avoid ambiguity in your commands, use the full reference path:

bash

# Checkout the branch (not the tag)
git checkout refs/heads/feature

# Checkout the tag (not the branch)
git checkout refs/tags/feature

# Merge using explicit branch reference
git merge refs/heads/feature

# Compare using explicit references
git diff refs/heads/feature refs/tags/feature

# Set upstream with explicit remote reference
git branch --set-upstream-to=refs/remotes/origin/master master

You can also use shorter but still unambiguous forms:

bash

# Use heads/ prefix for branches
git checkout heads/feature

# Use tags/ prefix for tags
git checkout tags/feature

3Delete the conflicting tag

If the tag is no longer needed or was created by mistake, delete it:

bash

# Delete local tag
git tag -d feature

# If the tag exists on remote, delete it there too
git push origin :refs/tags/feature

# Or use the --delete flag
git push origin --delete tag feature

After deleting, verify the ambiguity is resolved:

bash

git show-ref feature
# Should now show only one reference

4Delete the conflicting branch

If the branch is the duplicate that should be removed:

bash

# Delete local branch (use -D to force if unmerged)
git branch -d feature
git branch -D feature  # Force delete

# If it's a remote branch
git push origin --delete feature

Warning: Make sure you're deleting the correct reference. Use git log refs/heads/feature and git log refs/tags/feature to compare what each points to before deleting.

5Fix erroneous refs in .git directory

Sometimes a typo or failed operation creates an erroneous reference file. Check for misplaced refs:

bash

# Check for refs that shouldn't exist
ls -la .git/refs/
ls -la .git/refs/heads/
ls -la .git/refs/tags/

# Look for refs like 'origin/branch' in heads (wrong location)
ls -la .git/refs/heads/origin/

If you find erroneous refs, you can delete them:

bash

# Remove an erroneous ref file (be careful!)
git update-ref -d refs/heads/origin/feature

# Or manually delete the file
rm .git/refs/heads/origin/feature

Safer alternative: Use git's update-ref command rather than manually deleting files:

bash

# Delete a reference safely
git update-ref -d refs/origin/master

6Rename conflicting branch to avoid future issues

If you need to keep both references, rename the branch to make it unique:

bash

# Rename local branch
git branch -m feature feature-branch

# If you need to update the remote
git push origin :feature  # Delete old remote branch
git push origin feature-branch  # Push renamed branch
git push origin -u feature-branch  # Set upstream

Recommended naming conventions to avoid conflicts:

| Type | Convention | Example |
|------|------------|---------|
| Feature branch | feature/name | feature/user-auth |
| Release branch | release/version | release/1.2.0 |
| Release tag | v1.2.0 | v1.2.0 |
| Hotfix branch | hotfix/name | hotfix/login-fix |

Using prefixes like feature/, release/, or v for tags naturally prevents naming collisions.

7Clean up local branch named like remote

A common mistake is creating a local branch with a name like origin/feature instead of checking out the remote branch:

bash

# This creates a local branch named 'origin/feature' (wrong!)
git branch origin/feature

# This checks out the remote branch (correct)
git checkout origin/feature

To fix this:

bash

# Delete the incorrectly named local branch
git branch -D origin/feature

# Now checkout works correctly
git checkout feature
# or
git switch feature

Verify the fix:

bash

git show-ref | grep feature
# Should show only expected refs

Advanced notes

### Git Reference Resolution Order

When you provide a short refname, Git searches in this order:

1. $GIT_DIR/<refname> (e.g., HEAD, FETCH_HEAD, MERGE_HEAD)
2. refs/<refname>
3. refs/tags/<refname>
4. refs/heads/<refname>
5. refs/remotes/<refname>
6. refs/remotes/<refname>/HEAD

The first match wins, but Git warns if multiple matches exist because the behavior could change or be unexpected.

### Preventing Ambiguous Refs in Team Workflows

Establish naming conventions:
- Use v prefix for version tags: v1.0.0, v2.1.3
- Use directory-style branch names: feature/X, bugfix/Y
- Never name a tag the same as a branch

Add a pre-receive hook on the server:

bash

#!/bin/bash
# Reject pushes that would create ambiguous refs
while read oldrev newrev refname; do
  shortname=${refname##*/}
  if git show-ref --verify "refs/heads/$shortname" &>/dev/null && \
     git show-ref --verify "refs/tags/$shortname" &>/dev/null; then
    echo "Error: Would create ambiguous ref '$shortname'"
    exit 1
  fi
done

### Checking for Ambiguous Refs Repository-Wide

bash

# Find all potentially ambiguous refs
git for-each-ref --format='%(refname:short)' refs/heads refs/tags | \
  sort | uniq -d

If this outputs any names, those refs are ambiguous.

### The core.warnAmbiguousRefs Configuration

You can disable the warning (not recommended):

bash

git config core.warnAmbiguousRefs false

However, this just hides the symptom without fixing the underlying issue. It's better to resolve the ambiguity.

### Understanding Remote Tracking Branch Ambiguity

Sometimes ambiguity involves remote tracking branches:

bash

# These can conflict:
refs/heads/origin/feature       # Local branch (mistake)
refs/remotes/origin/feature     # Remote tracking branch (correct)

This usually happens when someone types git branch origin/feature instead of git checkout origin/feature.

### Git 2.30+ Improvements

Git 2.30 and later versions have improved handling of ambiguous refs in some commands, but the warning still appears. Always resolve ambiguities rather than relying on default behavior.

How to fix warning: refname 'feature' is ambiguous in Git

What this error means

Typical symptoms

Common causes

How to fix "warning: refname 'feature' is ambiguous"

Advanced notes

Related errors

Official resources & further reading