Skip to main content

Handling Merge Conflicts in NX

Koodisi does not resolve merge conflicts. Pull integrates remote changes into the branch you have checked out and can merge cleanly, but a merge that conflicts stops with Merges with conflicts are not supported yet. and leaves your files unchanged. Resolution happens in your Git provider; Koodisi pulls the resolved result back.

The recovery path depends on whether your work is committed. Both paths below are recovery procedures, not the normal way to work — see Parallel Development with Multiple Developers for how to make conflicts rare.

Why a pull conflicts​

A conflict means your local branch has diverged from its remote counterpart, which is to say the local branch holds something the remote does not.

Being behind the remote is not enough on its own. If your local branch has no commits of its own and no uncommitted changes, Pull fast-forwards and cannot conflict, however many pull requests your team merged while you were away. When a pull does conflict, one of two things is true:

  • You have uncommitted changes. Anything you built on the canvas lives in the local datastore against the branch that was checked out at the time. This is the most common cause. See Managing the Local Datastore.
  • You have local commits. Commits made on the branch that were never pushed.

Which one it is decides which recovery path below applies, so check the Changes tab before you discard anything.

Conflict while pulling, with uncommitted changes​

You need the latest remote changes, but you have local work that is not committed.

  1. Stage your changes on the Changes tab and create a stash. See Using Git with Applications.
  2. Check out your main or target branch.
  3. Delete the local copy of the branch that conflicted.
  4. Check out that branch again from Remote, which gives you a fresh copy matching the remote.
  5. On the Stash tab, select Apply to reapply your work on top of the fresh branch.
  6. Review the result, then commit.

For example: you are working on Branch A. Stash your changes, delete local Branch A, check out Branch A again from the remote, then apply your stash.

How you know it worked​

The branch matches the remote — Pull shows no badge — and your stashed changes are back in the staging area, ready to commit.

Conflict while pulling your main branch​

Teammates merge their pull requests, you check out main or master, select Pull, and the pull conflicts. Your local main has diverged. Find out how before discarding anything, because the two causes have different fixes.

  1. Open the Changes tab and look at what is listed.
  2. If changes are listed and you need them, they belong on a feature branch rather than on main. Stash them, or commit them to a new branch and push that branch. Then return to main.
  3. If changes are listed and you do not need them, select Discard all changes on the Changes heading and confirm at Discard Changes. Select Pull again — it now fast-forwards.
  4. If the Changes tab is empty, local main carries unpushed commits. Check out another branch, right-click local main and select Delete Branch, then check out main again from Remote.
  5. Select More > Fetch & Prune so the branch list drops the branches your team deleted when their pull requests merged.
warning

Delete Branch removes anything on that branch that is not on the remote, and discarding is not recoverable either. Check the Changes tab first, and stash or push anything you still need.

How you know it worked​

The Version Control panel shows main checked out with no Pull badge, and the Changes tab is empty. The merged work from your teammates is present in the application.

Preventing it​

Treat main as a mirror of the remote. Check it out, pull it, and branch from it, but never build on it. Do the work on a feature branch, as described in Parallel Development with Multiple Developers. Main then never diverges, every pull fast-forwards, and this recovery is never needed.

Conflict while pushing, with committed work​

You committed locally, but the remote branch moved ahead. The push is rejected with Push rejected because it was not a simple fast-forward. Your commits are safe; this path preserves them.

On a feature branch you own, this should be rare. When it keeps happening, the cause is one of two working habits rather than bad luck:

  • Several people are committing to one branch. Branches are cheap and pull requests are the review gate, so give each person their own branch.
  • The branch was left to drift. It was created weeks ago and never synced, so the remote moved a long way ahead. Sync at natural pauses instead.
  1. On the Branches tab, create a temporary branch from your current branch. Use a naming convention your team recognizes, such as temp/branch-b-resync-20260904.
  2. Select Push to push the temporary branch to the remote.
  3. In your Git provider, raise a pull request from the temporary branch into the original branch.
  4. Resolve the conflicts in the provider's merge editor, then complete the merge.
  5. Back in Koodisi, check out the original branch and select Pull.
  6. Delete the temporary branch once the merge is complete.

For example: you are working on Branch B. Create Branch B-temp, push it, and raise a pull request from Branch B-temp into Branch B. Resolve and merge there, then return to Koodisi, check out Branch B, and pull.

How you know it worked​

Pull and Push show no badges on the original branch, and the resolved commits appear on the Commits tab. See Reviewing Commit History.

Resolving in the provider's merge editor​

When you resolve a conflict in a pull request, you are choosing the correct final artifact — not mechanically picking one side.

Koodisi workflows, schemas, and resources are serialized files, so a conflict in one is a conflict in a structured document. Two branches that both added required fields to the same schema produce a conflict where the right answer is usually both sets of fields, which is neither "current" nor "incoming". Read the resolved file before completing the merge, and confirm the fields, mappings, and references you expect are all present.

Three limits to plan around:

  • A provider's online merge editor resolves only conflicts it can render inline. Binary files, renames, and some structural conflicts still need a local clone and push.
  • Freeze the branch while the pull request is open. New commits make the resolved state stale and force a second pass.
  • Choosing a side discards the whole artifact, not the conflicting lines. A workflow or schema is one serialized file, so "take current" or "take incoming" keeps that version of the entire artifact and drops everything the other branch did to it. When you do pick a side, treat the other side's changes as work to rebuild deliberately, and check them off against its pull request before completing the merge.

Restoring the target branch to a known-good state​

When work that should not have shipped reaches develop, and an urgent fix has to move, put the shared branch back to its last approved state before anything else. The Git provider is the source of truth for this. Koodisi is refreshed from the corrected result afterwards.

  1. In your Git provider, find the merge commit that introduced the unwanted change.
  2. Revert that merge commit, and let the provider raise the revert as its own pull request. Keep it a single clean revert rather than a hand-edited rollback, so the history says plainly what happened and the change can be reapplied later.
  3. Review and complete the revert pull request. develop is now back at the approved state.
  4. Create or update the hotfix branch from the corrected develop, validate the fix, and merge it through a pull request as normal.
  5. Tell the team the shared branch moved. Anyone holding a branch cut from the bad state needs to sync before they continue.
  6. In Koodisi, check out the corrected branch and select Pull. If the pull conflicts because your local copy diverged, follow Conflict while pulling your main branch.
  7. Validate the corrected branch in Development before publishing anything from it.

Keep the reverted feature's branch. Deleting it throws away the work you are about to restore.

Recovering a feature after its merge was reverted​

Your feature was merged, then reverted so a hotfix could go out, and you need the work back. It cannot be restored from inside Koodisi, which moves whole branches rather than individual commits. Rebuild it in your Git provider against the corrected target branch:

  1. Create a recovery branch from the current target branch, which now carries the revert and the hotfix.
  2. Raise your original feature branch as a pull request into the recovery branch.
  3. Resolve any conflicts in the provider's merge editor and complete the pull request. The recovery branch now holds your feature resolved against the corrected target branch.
  4. Merge the recovery branch back into your original feature branch so it is current and conflict-free.
  5. In Koodisi, check out the feature branch and select Pull. Re-run validation. Its base has changed, so the validation you did before the revert no longer holds.
  6. Delete the recovery branch, and merge the feature into the target branch as normal.

Why this approach works​

You never attempt to fix a conflict inside Koodisi, because Koodisi has no merge editor. Temporary branches and pull requests move resolution to the tool built for it, and stashing protects uncommitted work while you get back to a clean branch state. Your commits are preserved throughout, and the branch you eventually publish from is one your team reviewed.