Handling Merge Conflicts
Learn how to resolve merge conflicts in NeoArc JSON files. Understand conflict patterns, use the right tools, and adopt practices that minimise conflicts.
NeoArc files are JSON, which makes them text-based and mergeable. But JSON has structure that must remain valid after a merge. Understanding how conflicts occur and how to resolve them keeps your documentation workflow smooth.
How Conflicts Happen
A merge conflict occurs when two branches modify the same part of a file in incompatible ways.
Anatomy of a JSON Conflict
Git marks conflicts with standard markers. The section between <<<<<<< and ======= is your current branch. The section between ======= and >>>>>>> is the incoming branch.
{
"title": "My Page",
<<<<<<< HEAD
"summary": "Original summary text",
=======
"summary": "Updated summary from feature branch",
>>>>>>> feature-branch
"content": [...]
}Resolving Conflicts
Content Array Conflicts
The most complex conflicts occur in the content array when multiple blocks change. The array structure makes this tricky.
Resolving Content Array Conflicts
Using Merge Tools
Visual merge tools make JSON conflicts easier to resolve.
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'ModifiedDate Conflicts
A common conflict: both branches update modifiedDate. Resolution is simple: use the current date.
Preventing Conflicts
The best conflict is one that never happens. Practices that reduce conflicts.
After Resolving
Once conflicts are resolved and committed.
This documentation site is maintained through the same Git workflows, and the practices described here are how we handle conflicts in our own content.