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

To resolve merge conflicts in the rohitg00/ai-engineering-from-scratch repository, delete the auto-generated catalog.json, checkout the incoming versions of README.md and 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 (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 – 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 lines 36-38).
• site/data.js – A generated JavaScript artifact produced by site/build.js that drives the lesson index on the website (see AGENTS.md lines 24-26). It is rebuilt from the markdown links found in README.md.
• 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 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:

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

At this stage, Git will pause and mark catalog.json, README.md, and site/data.js as conflicted if they contain divergent changes.

2. Resolve the catalog.json Conflict

Since catalog.json is git-ignored and regenerated on demand, the correct resolution is to remove the conflicted version entirely and let CI recreate it:

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:

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 helper assembles the lesson catalogue, while scripts/check_readme_counts.py --fix ensures the lesson-count badges in 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:

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

The site/build.js script parses the markdown links in README.md to generate the final 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:

git push origin <your-branch>

Why Prefer the Incoming Branch ("Theirs")

The repository’s architecture distinguishes between source-driven and generated artifacts. README.md serves as the single source of truth for lesson metadata, while site/data.js and 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, check_readme_counts.py, and build.js) then recalculates counts and rebuilds indices, eliminating any stale or malformed entries that may have existed in either branch.

Summary

• catalog.json conflicts are resolved by removing the file with git rm; CI regenerates it automatically.
• 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 conflicts require git checkout --theirs followed by node site/build.js to regenerate the site index.
• Always reference 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 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 or scripts/check_readme_counts.py --fix, the 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 and 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}