# Upstream knoe-db Sync Procedure

This repo is an independent fork of the upstream knoe-db project hosted at:

```
git@git.knoe.dev:knoe-dev/knoe-db.git
```

The script `scripts/sync_upstream_knoe_db.sh` automates fetching upstream changes
and staging them in a dedicated review branch so they can be inspected and selectively
merged into `main`.

---

## Quick start

```bash
chmod +x scripts/sync_upstream_knoe_db.sh
./scripts/sync_upstream_knoe_db.sh
```

Use `--dry-run` to preview what the script would do without touching the repo:

```bash
./scripts/sync_upstream_knoe_db.sh --dry-run
```

> **Requires a clean working tree.** The script will exit with an error if
> `git diff` or `git diff --cached` reports any changes. Stash or commit
> your work first:
>
> ```bash
> git stash          # or: git add -A && git commit -m "wip: stash before upstream sync"
> ./scripts/sync_upstream_knoe_db.sh
> git stash pop      # restore your work afterwards
> ```
>
> If you only want to inspect what the script would do without touching the
> repo at all, `--dry-run` bypasses the clean-tree check.

---

## What the script does

1. **Registers the upstream remote** `upstream-knoe-db` (idempotent — safe to re-run).
2. **Fetches** `upstream-knoe-db/main` (no local branches are modified).
3. **Creates a timestamped review branch** `upstream/knoe-db/YYYYMMDD` pointing at the
   tip of the upstream fetch.
4. **Returns you to your previous branch** automatically.
5. **Prints next steps** with ready-to-paste git commands.

---

## Review and merge workflow

### 1. See what changed

```bash
# Commits in upstream not yet in main
git log main..upstream/knoe-db/$(date +%Y%m%d) --oneline

# Full diff scoped to the knoe-db/ directory
git diff main...upstream/knoe-db/$(date +%Y%m%d) -- knoe-db/
```

### 2. Check out the review branch

```bash
git checkout upstream/knoe-db/$(date +%Y%m%d)
```

Browse, test, or cherry-pick individual commits as needed.

### 3. Merge into main

When the changes look good:

```bash
git checkout main
git merge --no-ff upstream/knoe-db/$(date +%Y%m%d) \
  -m "chore(knoe-db): merge upstream $(date +%Y%m%d)"
```

Resolve any conflicts, then:

```bash
git push origin main
```

### 4. Open a PR / MR (recommended)

Push the review branch and open a pull request so the team can review before
merging into `main`:

```bash
git push origin upstream/knoe-db/$(date +%Y%m%d)
# then open a PR targeting main
```

---

## Keeping the upstream remote up to date

The script is idempotent — running it again on a later date will fetch the latest
upstream state and create a new dated branch (e.g. `upstream/knoe-db/20260601`).
Old review branches can be deleted once merged:

```bash
git branch -d upstream/knoe-db/20260523
git push origin --delete upstream/knoe-db/20260523
```

---

## Adjusting the upstream branch name

If the upstream project uses a branch other than `main` (e.g. `master` or `develop`),
edit the `UPSTREAM_BRANCH` variable near the top of `scripts/sync_upstream_knoe_db.sh`:

```bash
UPSTREAM_BRANCH="master"   # ← change as needed
```