How to fix merge: branch-name - not something we can merge in Git

GitBEGINNERLOWUpdated Dec 6, 2025· 236 views

This Git error occurs when trying to merge a branch that Git cannot find or recognize. The fix usually involves fetching the remote branch first, checking for typos in the branch name, or using the correct remote prefix.

Quick fix

Fixes merge: branch-name - not something we can merge

# List all local branches
git branch

# List all remote branches
git branch -r

# List all branches (local and remote)
git branch -a

# Search for a specific branch pattern
git branch -a | grep -i "branch-name"
  1. Verify the branch name exists
  2. Fetch the branch from remote
  3. Merge using the correct remote reference
  4. Checkout and pull the branch first
git — error
# List all local branches
git branch
# List all remote branches
git branch -r
# List all branches (local and remote)
git branch -a
# Search for a specific branch pattern
git branch -a | grep -i "branch-name"
merge: branch-name - not something we can merge

What this error means

When Git displays the error "merge: branch-name - not something we can merge", it means Git cannot locate or recognize the reference you're trying to merge. Git requires local knowledge of both branches involved in a merge operation. This error typically appears when you try to merge a branch that: - Doesn't exist locally (you haven't fetched or checked out the branch yet) - Has a typo in the branch name - Exists on the remote but you forgot to use the `origin/` prefix - Contains special characters that Git misinterprets The error message structure follows the pattern "merge: <reference> - not something we can merge" where the reference is whatever Git couldn't find or parse as a valid branch, tag, or commit.

Typical symptoms

  • Git merge command fails with 'not something we can merge' message
  • Attempting to merge a branch that exists on remote but not locally
  • Merge fails immediately without attempting any file changes
  • Git suggests 'Did you mean this?' with alternative branch names
  • CI/CD pipelines fail during merge operations
  • git merge origin/branch-name works but git merge branch-name fails
  • Error occurs after cloning a fresh repository

Common causes

  1. The branch doesn't exist locally - you need to fetch or checkout it first
  2. Typo in the branch name (wrong case, underscore vs dash, misspelling)
  3. Missing 'origin/' prefix when referencing a remote branch
  4. Branch name contains special characters (brackets, commas, apostrophes)
  5. Carriage return character appended to branch name from script output
  6. Attempting to merge a file name instead of a branch name
  7. Missing -m flag before commit message (Git interprets message as branch name)
  8. Branch was deleted on the remote but local refs are stale
  9. In a detached HEAD state without proper branch context

How to fix "merge: branch-name - not something we can merge"

1Verify the branch name exists

First, check if the branch you're trying to merge actually exists:

bash
# List all local branches
git branch

# List all remote branches
git branch -r

# List all branches (local and remote)
git branch -a

# Search for a specific branch pattern
git branch -a | grep -i "branch-name"

If the branch appears in the remote list but not locally, you need to fetch it first.

2Fetch the branch from remote

If the branch exists on the remote but not locally, fetch it:

bash
# Fetch all branches from all remotes
git fetch --all

# Or fetch from a specific remote
git fetch origin

# Fetch a specific branch
git fetch origin branch-name

After fetching, the branch will be available as origin/branch-name.

3Merge using the correct remote reference

When merging a remote branch, use the full remote reference:

bash
# Correct: Include the remote name
git merge origin/branch-name

# Incorrect: This won't work if branch isn't local
git merge branch-name

The origin prefix tells Git to use the remote tracking branch. If you're using a different remote name (like upstream), use that instead:

bash
git merge upstream/branch-name
4Checkout and pull the branch first

Alternatively, create a local copy of the branch first, then merge:

bash
# Checkout the remote branch (creates local tracking branch)
git checkout branch-name
# Git will automatically set up tracking if the remote branch exists

# Switch back to your target branch
git checkout main

# Now merge the local branch
git merge branch-name

Or use the combined fetch and checkout approach:

bash
git checkout -b branch-name origin/branch-name
5Check for typos and special characters

Branch name issues are a common cause. Verify the exact name:

bash
# List branches with exact names
git branch -a --list

# Check for common typos
# - Underscore (_) vs dash (-)
# - Case sensitivity (feature vs Feature)
# - Spaces in names

If the branch name contains special characters, try renaming it:

bash
# Create a new branch from the problematic one
git checkout problem-branch-name
git checkout -b clean-branch-name
git checkout main
git merge clean-branch-name

Check for hidden characters (carriage returns from scripts):

bash
# If branch name comes from a variable, strip whitespace
BRANCH_NAME=$(echo "$BRANCH_NAME" | tr -d '\r\n')
git merge "$BRANCH_NAME"
6Use commit hash as alternative

If the branch name continues to cause issues, use the commit hash instead:

bash
# Find the commit hash of the branch tip
git log origin/branch-name -1 --format="%H"

# Merge using the commit hash
git merge abc123def456

This bypasses any branch name parsing issues entirely.

7Check for common command mistakes

Ensure your command syntax is correct:

bash
# WRONG: Forgot -m flag, "message" is interpreted as branch name
git merge branch-name "Fix merge conflict"

# CORRECT: Include -m for commit message
git merge branch-name -m "Fix merge conflict"

# WRONG: Trying to merge a file
git merge README.md

# CORRECT: Merge a branch
git merge feature-branch

Also verify you're not in a detached HEAD state:

bash
git status
# Should show "On branch <name>", not "HEAD detached at..."

# If detached, checkout a branch first
git checkout main
8Prune stale remote references

If the branch was deleted remotely but local refs are stale:

bash
# Remove stale remote tracking branches
git remote prune origin

# Or fetch with prune
git fetch --prune

# Verify the branch list is now accurate
git branch -r

Then try your merge operation again with the correct branch name.

Advanced notes

### Understanding Git References

Git can merge various types of references:
- Branch names: main, feature-branch
- Remote tracking branches: origin/main, upstream/develop
- Tags: v1.0.0, release-2024
- Commit hashes: abc123, HEAD~3
- Reflog entries: HEAD@{1}

When Git says "not something we can merge", it couldn't resolve the reference to any of these types.

### CI/CD Pipeline Issues

This error commonly occurs in CI/CD pipelines when:

yaml
# Pipeline tries to merge a branch that wasn't fetched
- run: git merge feature-branch  # Fails!

# Fix: Fetch first
- run: |
    git fetch origin feature-branch
    git merge origin/feature-branch

For shallow clones (common in CI), you may need:

bash
git fetch --unshallow origin

### Debugging Branch Reference Resolution

To understand how Git resolves references:

bash
# Show what a reference resolves to
git rev-parse branch-name

# This will show an error if the reference can't be resolved
# fatal: ambiguous argument 'branch-name': unknown revision

# Check all possible matches
git show-ref branch-name

### Windows Line Ending Issues

On Windows, scripts might add carriage returns to branch names:

powershell
# PowerShell: Trim the variable
$branch = $branch.Trim()
git merge $branch
bash
# Bash on Windows: Remove carriage returns
BRANCH=$(echo $BRANCH | tr -d '\r')
git merge "$BRANCH"

### Git Worktrees and Submodules

In complex setups with worktrees or submodules:

bash
# Ensure you're in the correct repository context
git rev-parse --show-toplevel

# For submodules, navigate to the submodule first
cd submodule-path
git fetch origin
git merge origin/branch-name

### Older Git Version Considerations

Some older Git versions handle branch resolution differently. If you're on an older version:

bash
# Check Git version
git --version

# Update Git if possible, or use explicit references
git merge refs/remotes/origin/branch-name

Frequently asked questions

What does "merge: branch-name - not something we can merge" mean?
When Git displays the error "merge: branch-name - not something we can merge", it means Git cannot locate or recognize the reference you're trying to merge. Git requires local knowledge of both branches involved in a merge operation. This error typically appears when you try to merge a branch that: - Doesn't exist locally (you haven't fetched or checked out the branch yet) - Has a typo in the branch name - Exists on the remote but you forgot to use the origin/ prefix - Contains special characters that Git misinterprets The error message structure follows the pattern "merge: <reference> - not something we can merge" where the reference is whatever Git couldn't find or parse as a valid branch, tag, or commit.
How do I fix "merge: branch-name - not something we can merge"?
This Git error occurs when trying to merge a branch that Git cannot find or recognize. The fix usually involves fetching the remote branch first, checking for typos in the branch name, or using the correct remote prefix.
What causes "merge: branch-name - not something we can merge"?
The branch doesn't exist locally - you need to fetch or checkout it first Typo in the branch name (wrong case, underscore vs dash, misspelling) Missing 'origin/' prefix when referencing a remote branch
Is the "merge: branch-name - not something we can merge" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading