# How to Sync a Forked Version with Upstream Updates from the Original Repository

> Sync your ayghri/i-have-adhd fork with upstream updates. Learn to add an upstream remote, fetch, merge or rebase, and resolve duplicate skill files for seamless synchronization.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-05

---

**Keep your fork of `ayghri/i-have-adhd` in perfect sync by adding an upstream remote, fetching updates, merging or rebasing, and reconciling the duplicated skill files.**

The `i-have-adhd` repository is a coding assistant plugin with a unique dual-file structure that requires special attention during synchronization. When you fork the repository, your copy points to a static snapshot. To benefit from bug fixes, feature updates, and skill improvements in the original project, you must actively sync your fork with upstream changes.

## Understanding the Repository Structure

The `i-have-adhd` plugin organizes its core logic in two locations that must stay identical:

- **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** — The canonical skill definition
- **[`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md)** — A duplicated copy for IDE integration

The GitHub Actions workflow in [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml) enforces this synchronization. If these files diverge, your pull requests and pushes will fail CI checks, blocking your contribution workflow.

## Step-by-Step: Syncing Forked Versions with Upstream Updates

### 1. Add the Upstream Remote

First, configure Git to recognize the original repository as a source of truth.

```bash

# Navigate to your local fork

cd i-have-adhd

# Add the upstream remote

git remote add upstream https://github.com/ayghri/i-have-adhd.git

# Verify the remotes are configured

git remote -v

# origin    https://github.com/<your-username>/i-have-adhd.git (fetch)

# origin    https://github.com/<your-username>/i-have-adhd.git (push)

# upstream  https://github.com/ayghri/i-have-adhd.git (fetch)

# upstream  https://github.com/ayghri/i-have-adhd.git (push)

```

### 2. Fetch Upstream Changes

Download the latest commits without modifying your working directory.

```bash
git fetch upstream

```

This retrieves all branches from `ayghri/i-have-adhd` into remote-tracking references.

### 3. Integrate Upstream Updates

Choose between **merge** (preserves complete history) or **rebase** (creates linear history).

**Merge approach (recommended for most users):**

```bash
git checkout main
git merge upstream/main

```

**Rebase approach (cleaner commit history, requires force push):**

```bash
git checkout main
git rebase upstream/main
git push origin main --force-with-lease

```

### 4. Resolve Skill File Conflicts

After integrating upstream changes, check if the `.cursor` copy needs manual alignment. The [`cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/cursor-skill-sync.yml) workflow validates file parity using a simple comparison check.

If the CI job fails or you see divergence locally, execute:

```bash

# Copy the canonical skill file to the .cursor location

cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md

# Stage and commit if changed

git add .cursor/skills/i-have-adhd/SKILL.md
git commit -m "Sync .cursor copy with canonical SKILL.md"

```

### 5. Push Synchronized State to Your Fork

```bash
git push origin main

```

Your fork now reflects the upstream state, and the sync workflow will pass on subsequent pull requests.

## Automating Sync with Git Aliases

For frequent synchronization, add these shortcuts to your Git configuration:

```bash
git config --global alias.sync-upstream '!git fetch upstream && git checkout main && git merge upstream/main'
git config --global alias.sync-skill '!cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md && git add .cursor/skills/i-have-adhd/SKILL.md && git commit -m "Sync .cursor copy with canonical SKILL.md"'

```

## Key Files Involved in Synchronization

| File | Purpose |
|------|---------|
| [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) | Canonical skill definition; treat as source of truth |
| [`.cursor/skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/.cursor/skills/i-have-adhd/SKILL.md) | IDE-specific copy; must match canonical exactly |
| [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml) | CI enforcement preventing drift between copies |
| [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) | Plugin metadata; rarely changes during sync |
| [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md) | Instructions dependent on synchronized file structure |

## Summary

- **Add `upstream` remote** pointing to `https://github.com/ayghri/i-have-adhd.git`
- **Fetch and integrate** using `git merge upstream/main` or `git rebase upstream/main`
- **Reconcile duplicated files** with `cp skills/i-have-adhd/SKILL.md .cursor/skills/i-have-adhd/SKILL.md` when the sync workflow flags discrepancies
- **Push to your fork** to complete the synchronization cycle

Regular synchronization ensures your fork benefits from upstream improvements while maintaining the dual-file integrity required by the Cursor IDE integration.

## Frequently Asked Questions

### How often should I sync my fork with upstream?

Sync your fork before starting any new work and after significant upstream releases. Weekly synchronization is sufficient for active development; monthly works for casual users. The [`cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/cursor-skill-sync.yml) workflow will block contributions if you're significantly behind upstream changes that modified [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md).

### What happens if I forget to sync the `.cursor` copy with [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md)?

The GitHub Actions workflow defined in [`.github/workflows/cursor-skill-sync.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/cursor-skill-sync.yml) compares the two files on every push and pull request. If they differ, the check fails with an error message directing you to run the copy command. Your contribution cannot merge until both files match.

### Can I automate the entire sync process?

Partial automation is possible. Configure a GitHub Actions workflow in your own fork to periodically create pull requests from upstream. However, the `.cursor` copy reconciliation requires manual intervention or a custom script since automated merges cannot predict which file version takes precedence during conflicts.

### Should I use merge or rebase when syncing with upstream?

**Merge** preserves the complete history including upstream's commit sequence—ideal when you want traceability. **Rebase** rewrites your local commits atop upstream's tip, creating linear history preferred by maintainers reviewing your pull requests. Never rebase commits already pushed to shared branches unless you coordinate with collaborators.