Git notes merge conflicts occur when the same note is modified in both local and remote refs. Resolve conflicts manually in .git/NOTES_MERGE_WORKTREE, then finalize with git notes merge --commit.
This error occurs when you attempt to merge git notes from one ref into another, but both refs have modified the same note entries. Git notes are metadata you can attach to commits (like code review comments, build information, or additional annotations) without changing the commit itself. When Git encounters conflicting changes to the same note, it cannot automatically determine which version to keep. Instead of losing data, Git pauses the merge and creates a special worktree at `.git/NOTES_MERGE_WORKTREE` where you can manually resolve the conflicts. Unlike regular file merge conflicts, notes merge conflicts don't use the standard conflict markers. Instead, Git checks out the conflicting note files into the NOTES_MERGE_WORKTREE directory, where each file represents a note attached to a specific commit (named by the commit's SHA-1 hash). You must edit these files to resolve the conflict, then finalize the merge.
First, check what files are in the NOTES_MERGE_WORKTREE to understand the conflicts:
# List the conflicting note files
ls -la .git/NOTES_MERGE_WORKTREE/
# Each file is named after a commit SHA
# For example: .git/NOTES_MERGE_WORKTREE/a1b2c3d4...
# View the content of a conflicting note
cat .git/NOTES_MERGE_WORKTREE/<commit-sha>The files contain the note content that needs to be resolved. Each file corresponds to a note attached to a specific commit.
Edit each file in the worktree to contain the final desired note content:
# Open the conflicting note file in your editor
nano .git/NOTES_MERGE_WORKTREE/<commit-sha>
# Or use your preferred editor:
# vim, code, etc.Options for resolving:
1. Keep local version: Copy content from your current notes ref
git notes show <commit-sha> > .git/NOTES_MERGE_WORKTREE/<commit-sha>2. Keep remote version: Use the remote's note content
git notes --ref=refs/notes/origin/commits show <commit-sha> > .git/NOTES_MERGE_WORKTREE/<commit-sha>3. Combine both: Manually merge the content from both versions
4. Delete the note: Remove the file to delete the note entirely
rm .git/NOTES_MERGE_WORKTREE/<commit-sha>Once all conflicts are resolved, commit the merge:
# Complete the notes merge
git notes merge --commit
# Verify the merge was successful
git notes list
# Check a specific note
git notes show <commit-sha>If the merge completed successfully, the .git/NOTES_MERGE_WORKTREE directory and related merge files will be cleaned up automatically.
If you want to cancel the merge and return to the previous state:
# Abort the notes merge
git notes merge --abortThis removes the NOTES_MERGE_WORKTREE and restores your notes ref to its pre-merge state. Use this when:
- The conflicts are too complex to resolve
- You started the merge by mistake
- You want to try a different merge strategy
To avoid manual resolution, use an automatic merge strategy:
# Abort the current conflicted merge first
git notes merge --abort
# Then retry with an automatic strategy:
# Keep local versions for all conflicts
git notes merge -s ours origin/commits
# Keep remote versions for all conflicts
git notes merge -s theirs origin/commits
# Concatenate both versions (useful for line-based notes)
git notes merge -s union origin/commits
# Concatenate, sort, and deduplicate lines
git notes merge -s cat_sort_uniq origin/commitsStrategy comparison:
| Strategy | Behavior |
|----------|----------|
| manual | Default; requires conflict resolution in worktree |
| ours | Always keeps local version |
| theirs | Always keeps remote version |
| union | Concatenates both versions |
| cat_sort_uniq | Concatenates, sorts, removes duplicate lines |
Set a default strategy to avoid future manual conflicts:
# Set default strategy for all notes refs
git config notes.mergeStrategy union
# Set strategy for a specific notes ref (e.g., refs/notes/commits)
git config notes.commits.mergeStrategy cat_sort_uniqThe namespace-specific configuration (notes.<name>.mergeStrategy) takes precedence over the general setting.
To prevent conflicts, always fetch notes into a separate ref before merging:
# Fetch remote notes into a namespaced ref
git fetch origin refs/notes/commits:refs/notes/origin/commits
# Then merge with your local notes
git notes merge origin/commits
# After resolving, push your notes
git push origin refs/notes/commitsSet up automatic notes fetching:
# Configure fetch to include notes
git config --add remote.origin.fetch '+refs/notes/*:refs/notes/origin/*'
# Now 'git fetch' will include notes automatically
git fetch origin### Understanding Git Notes Architecture
Git notes are stored in refs (typically refs/notes/commits) and work like a parallel tree structure. Each note is a blob object whose name is the SHA-1 of the commit it annotates.
### The NOTES_MERGE_PARTIAL File
During a conflicted merge, Git creates:
- .git/NOTES_MERGE_WORKTREE/: Directory with conflicting note files
- .git/NOTES_MERGE_PARTIAL: The commit hash of the partial merge state
- .git/NOTES_MERGE_REF: The ref being merged into
When you run git notes merge --commit, Git amends the partial commit with the resolved notes.
### Common Notes Use Cases
| Use Case | Example |
|----------|---------|
| Code review comments | git notes add -m "Reviewed by Alice" |
| CI/CD metadata | Build numbers, test results |
| Ticket references | JIRA/GitHub issue links |
| Signature timestamps | GPG signing metadata |
### Notes vs Regular Commits
Unlike commit amendments which change history, notes:
- Don't modify commit hashes
- Can be modified after pushing
- Can be shared or kept private
- Are stored in separate refs (can be pushed independently)
### Preventing Notes Conflicts in Teams
Best practices:
1. Use union or cat_sort_uniq strategy for append-only notes
2. Establish notes ownership (one person/system per note)
3. Pull notes before modifying: git fetch origin refs/notes/*:refs/notes/*
4. Push notes immediately after changes
5. Consider separate notes refs for different purposes
### Rebase and Notes
When rebasing, commit SHAs change but notes stay attached to old SHAs:
# Copy notes to rebased commits
git notes copy <old-sha> <new-sha>
# Or use git-notes-rewrite (requires git-filter-repo)### Viewing Notes in Log
# Show notes in log output
git log --notes
# Show notes from a specific ref
git log --notes=refs/notes/review
# Show all notes from all refs
git log --notes='*'### Merge Without git notes merge
Alternative approach using checkout:
git checkout refs/notes/commits
git fetch origin refs/notes/commits
git merge FETCH_HEAD
# Resolve any conflicts like regular files
git add .
git commit -m "Merged notes"
git update-ref refs/notes/commits HEAD
git checkout -This treats notes as a regular branch, allowing use of standard merge tools.
warning: 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