# Conflict Resolution Process for Merging Branches with catalog.json or README.md Changes

> Learn the conflict resolution process for merging branches with catalog.json or README.md changes in rohitg00/ai-engineering-from-scratch. Accept main branch changes and regenerate artifacts.

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

---

**To resolve merge conflicts involving auto-generated artifacts in the rohitg00/ai-engineering-from-scratch repository, accept the `main` branch version for [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and regenerate counts using the provided Python scripts, while simply removing legacy [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) files that are now git-ignored.**

When contributing to the `rohitg00/ai-engineering-from-scratch` curriculum repository, pull requests that modify lesson content often trigger merge conflicts in automatically generated files. Understanding the **conflict resolution process for merging branches with catalog.json or README.md changes** ensures that the CI pipeline remains healthy and generated artifacts stay synchronized with the source of truth.

## Why These Conflicts Occur

Generated artifacts in this repository drift out of sync because they are rebuilt automatically on every push to `main`, while feature branches may contain stale versions.

### Legacy catalog.json Tracking

Although [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) is now **git-ignored** and no longer tracked in the repository, older branches may still include this machine-readable curriculum catalog. When these branches merge with `main`, Git flags a conflict that must be resolved by deleting the legacy file.

### README.md Auto-Generation

The [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) contains a summary table with lesson-link rows that include automatically computed counts. The CI job `readme-counts-sync` rewrites these counts on every push to `main`. Consequently, any branch that manually modifies the table will conflict with the automated version.

## Step-by-Step Conflict Resolution Process

The official procedure documented in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) follows a specific workflow to ensure consistency across generated files.

### 1. Sync with the Latest main Branch

Always begin by fetching the most recent changes from the upstream repository to establish a clean merge base.

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

```

### 2. Handle catalog.json Conflicts (Legacy Only)

If Git reports a conflict in [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json), treat it as a legacy artifact that should be removed rather than merged.

```bash

# The file is git-ignored; simply drop it from the branch

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

```

### 3. Resolve README.md Conflicts

For conflicts in the README table, discard the branch version and regenerate the counts using the maintenance scripts.

Accept the version from `main`:

```bash
git checkout --theirs README.md

```

Recompute the lesson totals and fix the table:

```bash
python3 scripts/build_catalog.py          # Rebuilds the hidden catalog (optional)

python3 scripts/check_readme_counts.py --fix

```

Stage the corrected file:

```bash
git add README.md && git commit --no-edit

```

### 4. Handle site/data.js Conflicts (Optional)

If the generated site map conflicts, apply the same pattern: accept the `main` version and regenerate.

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

```

### 5. Push the Resolved Branch

Once all generated files are reconciled, push the clean branch to origin.

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

```

## Key Scripts and Automation

The repository provides specific utilities to maintain generated file consistency:

- **[`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py)**: Validates and fixes lesson-link row counts in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md). The `--fix` flag automatically corrects discrepancies.
- **[`scripts/build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_catalog.py)**: Rebuilds the machine-readable curriculum catalog (optional step for [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) conflicts).
- **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)**: Regenerates [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) from the README and ROADMAP sources.

These scripts are referenced in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) under the conflict resolution section, which serves as the central policy guide for handling generated-file conflicts.

## Summary

- **Generated artifacts** like [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) tables and [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) drift automatically when the `main` branch updates.
- **Legacy [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) conflicts** are resolved by running `git rm catalog.json` since the file is git-ignored.
- **README.md conflicts** require checking out the `main` version with `git checkout --theirs README.md` and regenerating counts via `python3 scripts/check_readme_counts.py --fix`.
- **Site data conflicts** follow the same pattern using `git checkout --theirs site/data.js` followed by `node site/build.js`.
- Always reference [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) in the repository root for the authoritative conflict resolution policy.

## Frequently Asked Questions

### Why does catalog.json cause conflicts if it is git-ignored?

Legacy branches created before [`catalog.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/catalog.json) was added to `.gitignore` may still track the file. When these branches attempt to merge with modern `main`, Git detects the file presence as a conflict even though the current specification ignores it. The resolution is to explicitly remove the file from the branch index using `git rm catalog.json`.

### What does the check_readme_counts.py script do?

The [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py) utility validates that the lesson counts in the [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) summary table match the actual number of lesson files in the repository. When invoked with the `--fix` flag, it automatically recalculates and updates the table rows to reflect the current curriculum state, ensuring the documentation remains accurate without manual editing.

### Can I manually edit the README.md table instead of using the script?

Manual editing is discouraged because the CI job `readme-counts-sync` will overwrite your changes on the next push to `main`. Using `python3 scripts/check_readme_counts.py --fix` ensures your counts match the automated logic used by the pipeline, preventing future conflicts and maintaining consistency with the generated site data.

### Where is the official conflict resolution policy documented?

The definitive guide resides in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) at the repository root, specifically within the conflict resolution section. This document outlines the exact commands for handling [`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) conflicts, and serves as the source of truth for contributors and automation agents alike.