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.
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.
First, check if the branch you're trying to merge actually exists:
# 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.
If the branch exists on the remote but not locally, fetch it:
# 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-nameAfter fetching, the branch will be available as origin/branch-name.
When merging a remote branch, use the full remote reference:
# Correct: Include the remote name
git merge origin/branch-name
# Incorrect: This won't work if branch isn't local
git merge branch-nameThe origin prefix tells Git to use the remote tracking branch. If you're using a different remote name (like upstream), use that instead:
git merge upstream/branch-nameAlternatively, create a local copy of the branch first, then merge:
# 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-nameOr use the combined fetch and checkout approach:
git checkout -b branch-name origin/branch-nameBranch name issues are a common cause. Verify the exact name:
# List branches with exact names
git branch -a --list
# Check for common typos
# - Underscore (_) vs dash (-)
# - Case sensitivity (feature vs Feature)
# - Spaces in namesIf the branch name contains special characters, try renaming it:
# 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-nameCheck for hidden characters (carriage returns from scripts):
# If branch name comes from a variable, strip whitespace
BRANCH_NAME=$(echo "$BRANCH_NAME" | tr -d '\r\n')
git merge "$BRANCH_NAME"If the branch name continues to cause issues, use the commit hash instead:
# Find the commit hash of the branch tip
git log origin/branch-name -1 --format="%H"
# Merge using the commit hash
git merge abc123def456This bypasses any branch name parsing issues entirely.
Ensure your command syntax is correct:
# 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-branchAlso verify you're not in a detached HEAD state:
git status
# Should show "On branch <name>", not "HEAD detached at..."
# If detached, checkout a branch first
git checkout mainIf the branch was deleted remotely but local refs are stale:
# 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 -rThen try your merge operation again with the correct branch name.
### 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:
# 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-branchFor shallow clones (common in CI), you may need:
git fetch --unshallow origin### Debugging Branch Reference Resolution
To understand how Git resolves references:
# 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: Trim the variable
$branch = $branch.Trim()
git merge $branch# 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:
# 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:
# Check Git version
git --version
# Update Git if possible, or use explicit references
git merge refs/remotes/origin/branch-namewarning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server