# How to Resolve Git Conflicts in README.md, site/data.js, and catalog.json

> Learn to resolve Git conflicts in README.md, site/data.js, and catalog.json for the ai-engineering-from-scratch repository. Delete catalog.json and checkout incoming files.

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

---

**To resolve merge conflicts in the `rohitg00/ai-engineering-from-scratch` repository, delete the auto-generated [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json), checkout the incoming versions of [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), then run the respective Python and Node.js build scripts to regenerate the files before committing.**

The `rohitg00/ai-engineering-from-scratch` repository relies on a **CI-driven automation contract** that treats three specific files as managed artifacts. When Git encounters divergent changes during a merge, you must follow the canonical conflict-resolution workflow documented in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 52-71) to restore a clean state without corrupting the lesson index or automated lesson counts.

## Understanding the Three Critical Files

Each file serves a distinct role in the repository’s automation pipeline, as defined in the project’s agent configuration:

- **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)** – Stores the human-readable lesson index containing markdown link rows (`[Title](phases/NN-…/)`). The CI pipeline auto-fixes lesson counts in this file using the `readme-counts-sync` logic (see [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 36-38).
- **[`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)** – A generated JavaScript artifact produced by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) that drives the lesson index on the website (see [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 24-26). It is rebuilt from the markdown links found in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md).
- **[`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json)** – A generated catalogue that is git-ignored and rebuilt on every CI run. This file should never be manually edited or preserved during conflict resolution (see [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 36-37).

## Step-by-Step Conflict Resolution

Follow this exact sequence to resolve conflicts in all three files. The workflow prioritizes the **incoming branch** (`theirs`) for source-driven files and removes generated artifacts entirely.

### 1. Fetch the Latest Main and Start the Merge

Begin by pulling the latest changes from the upstream main branch and initiating the merge:

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

```

At this stage, Git will pause and mark [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json), [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), and [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) as conflicted if they contain divergent changes.

### 2. Resolve the catalog.json Conflict

Since [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) is git-ignored and regenerated on demand, the correct resolution is to remove the conflicted version entirely and let CI recreate it:

```bash
git rm catalog.json
git commit --no-edit

```

No further action is required for this file; the next CI run will rebuild it from the source markdown links.

### 3. Resolve the README.md Conflict

Prefer the incoming branch’s version to ensure the lesson-link rows remain correctly formatted, then regenerate the catalogue and fix lesson counts using the provided helper scripts:

```bash
git checkout --theirs README.md
python3 scripts/build_catalog.py
python3 scripts/check_readme_counts.py --fix
git add README.md
git commit --no-edit

```

The [`scripts/build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_catalog.py) helper assembles the lesson catalogue, while `scripts/check_readme_counts.py --fix` ensures the lesson-count badges in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) match the actual content.

### 4. Resolve the site/data.js Conflict

Again prefer the incoming version to capture the correct markdown link structure, then regenerate the pristine JavaScript index:

```bash
git checkout --theirs site/data.js
node site/build.js
git add site/data.js
git commit --no-edit

```

The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script parses the markdown links in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) to generate the final [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) file used by the website.

### 5. Push the Resolved Branch

Once all conflicts are resolved and the generated files are rebuilt, push the clean branch to the remote:

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

```

## Why Prefer the Incoming Branch ("Theirs")

The repository’s architecture distinguishes between **source-driven** and **generated** artifacts. [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) serves as the single source of truth for lesson metadata, while [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) and [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) are derived outputs. By checking out the `theirs` version of the source files, you preserve the authoritative markdown links from the incoming branch. Running the helper scripts ([`build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/build_catalog.py), [`check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/check_readme_counts.py), and [`build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/build.js)) then recalculates counts and rebuilds indices, eliminating any stale or malformed entries that may have existed in either branch.

## Summary

- **[`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json)** conflicts are resolved by removing the file with `git rm`; CI regenerates it automatically.
- **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)** conflicts require `git checkout --theirs` followed by `python3 scripts/build_catalog.py` and `python3 scripts/check_readme_counts.py --fix`.
- **[`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)** conflicts require `git checkout --theirs` followed by `node site/build.js` to regenerate the site index.
- Always reference [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 52-71) for the canonical conflict-resolution recipe specific to this repository.

## Frequently Asked Questions

### Why should I delete catalog.json instead of merging the changes manually?

[`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) is listed in `.gitignore` and is regenerated on every CI run by the automation pipeline. Since it is a transient build artifact and not a source file, merging divergent versions creates unnecessary noise. Removing it with `git rm` signals Git to ignore the conflict and allows the CI system to generate a fresh, consistent catalogue on the next build.

### What happens if I skip the Python scripts after resolving README.md conflicts?

If you omit [`scripts/build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_catalog.py) or `scripts/check_readme_counts.py --fix`, the [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) may contain stale lesson counts or broken catalogue entries. The CI pipeline expects these counts to be synchronized with the actual lesson files; unsynchronized counts will cause the `readme-counts-sync` check to fail, blocking your pull request.

### Can I use git checkout --ours instead of --theirs for these files?

You should use `git checkout --theirs` (the incoming branch version) rather than `git checkout --ours` (the current branch version). Because [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) are source-driven artifacts that may have been updated with new lesson links in the incoming branch, preferring `theirs` ensures you capture the most recent authoritative metadata before regenerating the derived files.

### Where is the official conflict resolution documentation located?

The official workflow is documented in the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file within the repository root, specifically in the "Conflict resolution" section between lines 52 and 71. This file serves as the central operating manual for agents and contributors interacting with the repository’s automation.