Conflicts and merging

There are two kinds of conflict in Wiele. A push conflict happens when you push to a branch someone else just changed. A merge conflict happens when you merge a copy into main and both sides changed the same file. Wiele never picks a winner for you: it stops, keeps both versions and asks.

Push conflicts

Two people working in checkouts of the same branch can push at any time. When the pushes touch different files, Wiele applies both. When another push already changed the same files since your last pull, yours fails with PUSH_CONFLICT, lists the paths and publishes nothing.

To fix it:

wiele pull --keep-local

--keep-local applies the other remote changes, keeps your version of each conflicting file and saves the remote version as a recovery file. Your kept file doesn't contain the other person's edits. Compare the two, fold their changes into yours, then push:

wiele status                    # shows the conflicting files and recovery copies
wiele push -m "Merge Anna's budget changes"

HEAD_MOVED means the branch moved while your push ran. Your local files are unchanged. Run wiele pull, then wiele push again.

Work on a copy

A copy (branch) keeps bigger changes away from main until someone approves them. Anyone who can read the files can make one.

cd acme                              # a checkout of main
wiele copy create acme-rewrite
wiele copy switch acme-rewrite
# edit, or let an agent edit
wiele push -m "Rewrite proposal"

copy create doesn't move your checkout; copy switch does. Switching needs a clean checkout, with sync paused and live uploads off.

Compare the copy with main:

wiele copy compare acme-rewrite --to main
wiele copy merge-plan acme-rewrite --into main

The merge plan lists every change and every conflict, and says whether you can merge. Merging needs write access on every changed path in main, and admin to delete a whole folder.

Merge

The merge flow works on a draft file that pins both copies' heads:

Save a draft:

wiele conflict list acme-rewrite --into main --save merge.json

If it lists conflicts, look at each one by its workspace path, as conflict list prints it, or its resource ID. show prints a text diff; export downloads the base, main and copy versions so you can open them in their own apps:
```
wiele conflict show acme/proposal.md --plan merge.json
wiele conflict export acme/budget.xlsx --plan merge.json --output ./budget-conflict
```

Resolve each conflict by taking one side, deleting the file, or publishing a file you combined yourself:

wiele conflict resolve acme/proposal.md --plan merge.json --take source
wiele conflict resolve acme/notes.md --plan merge.json --take target
wiele conflict resolve acme/budget.xlsx --plan merge.json --file ./budget-combined.xlsx

source is the copy and target is main. --file pushes your combined file to the copy and takes it.

Approve the merge with the draft:

wiele copy merge approve --workspace WORKSPACE_ID --approval merge.json

Pull main in your other checkouts.

If either copy moves after you save the draft, approval fails with HEAD_MOVED or POLICY_CHANGED. Save a new draft to a new file and review it again.

Word documents, spreadsheets and other binary files merge as whole files. Wiele doesn't combine their contents; you or an agent produce the combined file and resolve with --file.

Agents and merges

The wiele-conflicts skill teaches an agent this flow. Agents should ask about business choices, such as amounts or contract terms, rather than pick a side themselves, and should never approve a merge they weren't asked to make.