> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nometria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling Conflicts

> What happens when builder changes and developer changes touch the same files.

Conflicts happen when both your AI builder and a developer edit the same file between syncs. Nometria detects these automatically and brings them to your attention before anything reaches production.

## When conflicts occur

A conflict is possible when:

1. A developer edits `src/components/UserCard.jsx` on `main`
2. You then make a change in your builder that also affects `UserCard.jsx`
3. The extension pushes that builder change to `builder/latest`
4. Nometria attempts to merge `builder/latest` → `main` and finds overlapping changes

If `auto_merge: true` and Nometria can fast-forward without ambiguity (e.g. different lines), it merges automatically. If the same lines changed in both branches — that's a real conflict.

## How Nometria handles a conflict

When a real conflict is detected:

1. Nometria **does not auto-merge** — it stops and creates a GitHub Pull Request
2. The PR is from `builder/latest` → `main` with conflict markers in the affected files
3. You receive a dashboard notification and (optionally) an email
4. The PR stays open until you resolve it — your existing production version stays live and unchanged

## Resolving a conflict

<Steps>
  <Step title="Open the PR">
    Dashboard → **Sync** → click the **Resolve conflict** link, which takes you to the GitHub PR.

    Or navigate directly to your repo on GitHub and find the open PR.
  </Step>

  <Step title="Identify the conflict">
    GitHub shows which files have conflicts with a red marker. Open the file — you'll see standard Git conflict markers:

    ```
    <<<<<<< main
    // Developer's version
    const UserCard = ({ user }) => {
      return <div className="card">{user.name}</div>;
    };
    =======
    // Builder's version
    const UserCard = ({ user, onClick }) => {
      return <div className="card" onClick={onClick}>{user.name}</div>;
    };
    >>>>>>> builder/latest
    ```
  </Step>

  <Step title="Choose or combine the versions">
    **Option A — Use GitHub's web editor:**
    Click **Resolve conflicts** in GitHub's UI. Edit the file directly in the browser, removing the conflict markers and keeping the version you want (or combining both).

    **Option B — Resolve locally:**

    ```bash theme={null}
    git checkout main
    git fetch origin
    git merge origin/builder/latest
    # Edit conflicted files, remove conflict markers
    git add .
    git commit -m "resolve: merge builder changes with user card click handler"
    git push
    ```
  </Step>

  <Step title="Merge the PR">
    Once all conflicts are resolved, merge the PR on GitHub. Nometria detects the merge and triggers a production redeploy automatically.
  </Step>
</Steps>

## Preventing conflicts

The best way to handle conflicts is to avoid them. A few practices that help:

**Work in layers.** Let your builder handle UI and layout. Have developers handle business logic and integrations. These rarely touch the same files.

**Use `.Nometria.yml` to exclude developer-owned files:**

```yaml theme={null}
sync:
  ignored_paths:
    - "src/lib/**"        # Developer-owned utilities
    - "src/api/**"        # Developer-owned API client
    - "src/hooks/**"      # Developer-owned custom hooks
    - "*.config.js"       # Config files
```

Files in `ignored_paths` are never committed by the extension, even if the builder modifies them. This creates a clean division: builder owns `src/components` and `src/pages`; developers own `src/lib`, `src/api`, and `src/hooks`.

**Communicate before large developer changes.** If a developer is refactoring a large part of the codebase, pause auto-merge (Settings → Sync → Pause) until the refactor lands on `main`.

## Conflict notification settings

Dashboard → Settings → **Notifications** to configure:

* Email notification when a conflict PR is opened
* Slack webhook for conflict alerts
* Disable notifications for auto-merged pushes (reduces noise)