# How to Resolve Merge Conflicts in the AI Engineering from Scratch Repository

> Learn to resolve merge conflicts in the AI Engineering from Scratch repository. Fetch main, fix conflicts, commit atomically, validate, and push for CI rebuild.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-06-07

---

**To resolve merge conflicts in the AI Engineering from Scratch repository, fetch the latest `main` branch, reconcile conflicts in lesson directories and metadata files while keeping each lesson limited to one atomic commit, run the validation scripts to sync badge counts, and push to let CI rebuild the site catalog.**

The `rohitg00/ai-engineering-from-scratch` repo is structured as a curriculum where each lesson is isolated in its own folder and tracked by exactly one dedicated commit. Because lesson paths, [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) link rows, [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) status tables, and the generated [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) catalog are tightly coupled, pull requests frequently overlap in the same files. The repository documents the official resolution process in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), and the steps below align with that source to keep the curriculum intact.

## Where Merge Conflicts Typically Appear

Conflicts in this codebase cluster in four tightly-coupled areas.

- **Lesson directories** under `phases/` — When two contributors edit files in the same lesson’s `code/`, `docs/`, or `outputs/` folders, Git cannot auto-merge the content. Combine the changes manually, then re-run the lesson’s tests to confirm everything still works.
- **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)** — The lesson-link table uses a strict markdown row format. Adding or renaming lessons on the same table row causes overlapping edits.
- **[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)** — The phase and lesson status table is updated in parallel by different feature branches.
- **[`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)** — This file is generated by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) from the README links; mismatched or missing rows after a merge break the site catalog until CI rebuilds it.

## Step-by-Step Merge Conflict Resolution Workflow

The following process is the standard workflow defined in the repository's [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file.

### 1. Pull the Latest `main` and Start the Merge

From your feature branch, synchronize with upstream before attempting any resolution.

```bash
git fetch origin main
git merge --no-edit origin/main

```

If Git reports conflicts, the merge pauses and marks the affected files for manual review.

### 2. Locate the Conflicted Files

Use `git status` to surface every file that still contains conflict markers.

```bash
git status

```

Typical conflicted paths include [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), and lesson content under `phases/*/docs/en.md` or `phases/*/code/*`.

### 3. Resolve Conflicts Manually

Open each conflicted file in your editor. For every `<<<<<<<` / `=======` / `>>>>>>>` block:

1. Identify the intended final content. If a lesson was renamed, keep the new path and update the corresponding [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) link.
2. If two contributors added different lessons on adjacent rows, insert both rows in the correct alphabetical or numerical order.
3. Delete all conflict markers and save the file.

The [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) rows must match the exact markdown link format expected by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js). Any deviation in path or punctuation produces a blank catalog entry on the website. The correct row format looks like this:

```markdown
| 01 | [Linear Algebra Intuition](phases/01-math-foundations/01-linear-algebra-intuition/) | Learn | Python, Julia |

```

### 4. Re-run the Repository Maintenance Scripts

After manual editing, use the provided helper scripts to synchronize counts and structure.

Verify and auto-fix the lesson-count badges in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md):

```bash
python3 scripts/check_readme_counts.py --fix

```

Audit lesson directories to enforce the one-commit-per-lesson rule:

```bash
python3 scripts/audit_lessons.py

```

Both scripts run in the CI pipeline defined in [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml), so passing them locally prevents later build failures.

### 5. Commit the Resolved Changes

Stage the files you edited and commit the resolution separately from your original feature work.

```bash
git add README.md ROADMAP.md phases/
git commit -m "fix: resolve merge conflicts in <lesson-or-doc>"

```

Do **not** squash this resolution commit with the original lesson commit. The curriculum invariant requires each lesson to remain an atomic, isolated commit.

### 6. Push and Let CI Finish

Push the branch and allow the automated curriculum pipeline to validate the fix.

```bash
git push origin <your-branch>

```

The [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) workflow will re-run [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py), rebuild the site using [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js), update [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) on `main`, and auto-correct any remaining README count drift. If CI still reports errors, repeat steps 2 through 5 until the pipeline passes.

### 7. Optional: Manual Site Rebuild

For an immediate local preview after merging, regenerate the site catalog manually:

```bash
cd site
node build.js

```

This updates [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) with the correct lesson URLs derived from the current [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) links.

## Automated Cleanup Script for Large Pull Requests

When a large pull request touches many lessons, you can use the following bash snippet to strip conflict markers from [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) while preserving both sides of the conflict. Run this before committing the final fix.

```bash
#!/usr/bin/env bash

# remove conflict markers from README.md while preserving both sides

awk '
  /^\<\<\<\<\</ {conflict=1; next}
  /^\=\=\=\=\=/ {next}
  /^\>\>\>\>\>/ {conflict=0; next}
  !conflict
' README.md > README.fixed.md && mv README.fixed.md README.md

```

After running the script, review the file to ensure each row follows the required markdown link format, then execute `python3 scripts/check_readme_counts.py --fix` to realign the badge totals.

## Summary

- Merge conflicts in `rohitg00/ai-engineering-from-scratch` most often appear in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), lesson directories under `phases/`, and the generated [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) catalog.
- Always preserve the **one-commit-per-lesson** rule when resolving conflicts; never squash the resolution commit into a lesson commit.
- Use `git fetch origin main` and `git merge --no-edit origin/main` to start resolution, then edit out all `<<<<<<<` / `=======` / `>>>>>>>` markers.
- Run `python3 scripts/check_readme_counts.py --fix` and `python3 scripts/audit_lessons.py` locally to validate structure before pushing.
- Let the [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) CI pipeline rebuild [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) and auto-fix counts automatically after your push.

## Frequently Asked Questions

### What causes most merge conflicts in the AI Engineering from Scratch repository?

Most conflicts arise because the curriculum tightly couples lesson folders under `phases/` with the [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) link table and the [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) status table. When two pull requests add, rename, or reorder lessons simultaneously, they edit the same metadata rows and collide during merge.

### How do I fix a conflict in the README.md lesson table?

Open [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), locate every `<<<<<<<` block, keep the correct lesson links in the exact markdown row format, remove the conflict markers, and save. Afterward, run `python3 scripts/check_readme_counts.py --fix` to update badge totals and ensure [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) can still parse the catalog.

### Why should I avoid squashing the merge-conflict resolution commit?

The repository enforces a strict invariant where each lesson maps to exactly one dedicated commit. Squashing the resolution into a lesson commit violates that rule and breaks the atomic history expected by [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) and the CI pipeline in [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml).

### How do I rebuild the site catalog after resolving conflicts?

The easiest path is to push your branch and let the CI workflow rebuild [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) automatically. If you need an immediate local preview, run `node site/build.js` from the repository root; this regenerates the catalog from the current [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) links so you can verify the site renders correctly before pushing.