Conflict Resolution

Learn how to handle conflicts when local and server edits collide during sync.

When conflicts happen

A conflict occurs when both conditions are true:

• You edited a file locally since your last sync
• Someone (or you, in the web UI) edited the same file on the server

Meldoc detects this automatically during meldoc pull and meldoc push.

Resolution modes

Both meldoc pull and meldoc push support the --resolve flag:

merge (default) — Three-way merge using Git. Changes in different parts of the file are combined automatically. If changes overlap, conflict markers are added for you to resolve manually.

ours — Keep your local version for all conflicts.

theirs — Use the server version for all conflicts.

ask — Stop at each conflict, show the difference, and let you choose. When there is nobody to ask — a non-interactive terminal, or a CI run — it falls back to the server version.

# Default: automatic merge
meldoc pull

# Always keep local changes
meldoc pull --resolve ours

# Always use server version
meldoc pull --resolve theirs

# Decide each conflict yourself
meldoc pull --resolve ask

# Fresh pull — ignore the cache and overwrite local files with the server version
meldoc pull --force

The same --resolve flag works with meldoc push.

Note: meldoc push --force is different — it re-pushes every file, ignoring the cache. It does not change conflict handling.

Exit codes

Code	Meaning
0	Success, no conflicts
1	Error
4	Success, but one or more files still contain conflict markers

Code 4 is what to check for when scripting: the sync itself worked, but a file is waiting for you.

How merge works

Merge mode uses Git’s three-way merge algorithm with three versions of the file:

• Base — the last synced version (stored in .meldoc/cache/base/)
• Ours — your current local version
• Theirs — the current server version

The cached base is used during meldoc pull. During meldoc push, Meldoc has no base to compare against, so a conflict is more likely to fall back to the server version — pull first to merge cleanly.

When changes don’t overlap, Git combines them automatically. When they do, conflict markers are added:

<<<<<<< ours
Your local changes
=======
Server changes
>>>>>>> theirs

Edit the file to remove the markers, then push:

meldoc push

Find files still in conflict

A file left with conflict markers stays marked as conflicted until you resolve it. meldoc validate lists every one of them, so you can check before publishing:

meldoc validate

Keep in mind: Merge mode needs Git in your PATH and a base version in .meldoc/cache/base/. If the merge can’t be completed automatically, Meldoc keeps the server version (the same as --resolve theirs).

Avoid conflicts

The simplest way to avoid conflicts: pull before you start editing, and push when you’re done.

meldoc pull
# edit your files
meldoc push

For team workflows, see Team Workflow.

What’s next?

Team Workflow — Collaborate on documentation with your team.

Workflow — Daily push, pull, and sync workflows.