Rebase To Main

Rebase Branch to Main

Workflow

1. Fetch and compare

git fetch origin main
git log --oneline FETCH_HEAD..HEAD    # commits to replay
git log --oneline HEAD..FETCH_HEAD | head -10  # what main added

2. Rebase

git rebase FETCH_HEAD

No conflicts → skip to step 5.

3. Resolve conflicts

.deps/EXCLUDED/prod.md or .deps/EXCLUDED/dev.md

Both sides may have added entries. Merge them — keep all of main's entries and re-apply ours:

git checkout --ours .deps/EXCLUDED/prod.md .deps/EXCLUDED/dev.md
git add .deps/EXCLUDED/prod.md .deps/EXCLUDED/dev.md

Then after continuing the rebase, re-run yarn license:generate to restore any entries our branch added.

.deps/prod.md or .deps/dev.md

Always regenerated. Take main's version, then regenerate:

git checkout --ours .deps/prod.md .deps/dev.md
git add .deps/prod.md .deps/dev.md

package.json / yarn.lock

Usually auto-merges. If not, reconcile manually (keep our dep additions alongside main's changes), then:

yarn install

Continue

git add <resolved-files>
git rebase --continue

4. Reinstall and regenerate licenses

yarn install 2>&1 | grep -E "(added|removed|Done|Error)" | head -5
yarn license:generate

If yarn license:generate exits with UNRESOLVED:

Check score:

curl -s --max-time 10 \
  "https://api.clearlydefined.io/definitions/npm/npmjs/-/<package>/<version>" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('scores',{}).get('effective',0))"

Add to EXCLUDED if score = 0:

| `<package>@<version>` | [clearlydefined](https://clearlydefined.io/definitions/npm/npmjs/-/<package>/<version>) |

5. Verify

yarn license:check   # must exit 0
git log --oneline -5
git show --stat HEAD

5.5. Build and test before pushing

MANDATORY — do not skip even for "pure dependency" rebases:

yarn build           # must exit 0; dep upgrades can break TypeScript compilation
yarn test            # must exit 0; dep upgrades can cause test suite failures

If yarn build fails: investigate compilation errors and fix before continuing. If yarn test fails: investigate failures — dep upgrades often introduce breaking API changes or new peer dependency requirements that break tests.

Never force-push with a failing build or failing tests.

6. Strip forbidden trailers

Check for Made-with or Co-authored-by in any replayed commit:

git log FETCH_HEAD..HEAD --format='%H %s' | while read hash rest; do
  git log -1 --format='%B' "$hash" | grep -qiE '^(Made-with|Co-authored-by):' && echo "DIRTY: $hash $rest"
done

If dirty:

FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch -f --msg-filter \
  'sed "/^Made-with:/d; /^Co-authored-by:/d"' \
  -- FETCH_HEAD..HEAD
git update-ref -d refs/original/refs/heads/$(git branch --show-current)

For a single-commit branch, amending is simpler:

git commit --amend -m "$(git log -1 --format='%s')"
# add trailers manually if needed

7. Force push

git push --force origin <branch>

Common .deps/ conflict patterns

Pattern 1 — Both sides added entries, neither is a superset

Merge manually: keep all of main's entries, then append ours below them.

Pattern 2 — Our branch removed a dep entry that main still has

Take main's version and let yarn license:generate clean it up:

git checkout --ours .deps/prod.md
git add .deps/prod.md

Pattern 3 — ClearlyDefined link vs ecd.che reference for the same package

Keep the ClearlyDefined link (more complete, preferred by the tool).