.lycheecache is auto-generated and union-merged (policy: Link cache), so
merges and rebases usually complete without conflict but can leave residue that
fails the CACHE updates committed? check. Either way, recover with the
procedure below.
Prerequisites
If the current branch has a merge or rebase in progress, then skip the rest of
this section and jump to Preparation.
The current branch must be clean (git status --short). If not clean, offer to
run git stash or git commit to clean it up, or stop.
If $ARGUMENTS is a PR number, then check out the PR branch with:
gh pr checkout $ARGUMENTS.
Preparation
At this point, we are ready to resolve the conflicts in the active branch:
Determine the integration reference ($BASE_BRANCH) and fetch it:
- If an
upstream remote exists: git fetch upstream, use upstream/main.
- Otherwise:
git fetch origin, use origin/main.
If merge or rebase is in progress (git status), skip this step. Otherwise,
ask the user whether to run git merge $BASE_BRANCH or
git rebase $BASE_BRANCH, then run it. For a branch created before
.gitattributes gained the .lycheecache union rule, prefer rebase: merge
attributes resolve against the current checkout's tree, which during a rebase
is the updated base.
If there are no conflicts, the operation completes on its own. Run the
residue test, then stop: we are done.
Conflicts other than .lycheecache: resolve them with the user.
If a .lycheecache conflict remains, proceed to Resolve. Otherwise,
conclude the operation per Resolve steps 2-3, then run the
residue test.
Residue test
A conflict-free union merge can still leave residue that fails the
CACHE updates committed? check: duplicate URLs or out-of-order lines.
cut -d, -f1 .lycheecache | sort | uniq -d # any output: duplicate URLs
sort -c .lycheecache # any error: out-of-order lines
If either check trips, run Resolve steps 4-6 to regenerate, commit, and push
the cache.
Resolve
Check out the $BASE_BRANCH version of .lycheecache. Assumes the active
branch is being rebased/merged from $BASE_BRANCH, not the other way around:
| Operation |
Command |
Rebase of active branch onto $BASE_BRANCH |
git checkout --ours .lycheecache |
Merge of $BASE_BRANCH into active branch |
git checkout --theirs .lycheecache |
Stage the resolved files, then continue:
- Rebase:
git add .lycheecache && git rebase --continue
- Merge:
git add .lycheecache && git commit --no-edit
- If other files were resolved in Preparation step 4,
git add those too
before continuing.
Rebase only: for each subsequent rebase stop that conflicts on
.lycheecache, repeat Resolve steps 1–2. If other paths are also conflicted
on that stop, run Preparation step 4 first.
Run npm run fix:link-cache once, after the entire rebase/merge completes.
Note: this runs a Hugo build (lean by default) and link check — requires
network, installed npm dependencies, and populated submodules; can take
several minutes.
Commit the changes, if any:
git add .lycheecache
git diff --cached --quiet .lycheecache || \
git commit -m "Refresh link cache after resolving conflicts"
Push:
- Merge:
git push
- Rebase:
git push --force-with-lease
1---2name: resolve-link-cache-conflicts3description: Skill for recovering .lycheecache after a merge or rebase, whether from residual conflicts or union-merge residue, in the current branch or a specified PR.4---56`.lycheecache` is auto-generated and union-merged (policy: [Link cache][]), so7merges and rebases usually complete without conflict but can leave residue that8fails the `CACHE updates committed?` check. Either way, recover with the9procedure below.1011## Prerequisites1213If the current branch has a merge or rebase in progress, then skip the rest of14this section and jump to **Preparation**.1516The current branch must be clean (`git status --short`). If not clean, offer to17run `git stash` or `git commit` to clean it up, or stop.1819If `$ARGUMENTS` is a PR number, then check out the PR branch with:20`gh pr checkout $ARGUMENTS`.2122## Preparation2324At this point, we are ready to resolve the conflicts in the active branch:25261. Determine the integration reference (`$BASE_BRANCH`) and fetch it:27 - If an `upstream` remote exists: `git fetch upstream`, use `upstream/main`.28 - Otherwise: `git fetch origin`, use `origin/main`.29302. If merge or rebase is in progress (`git status`), skip this step. Otherwise,31 ask the user whether to run `git merge $BASE_BRANCH` or32 `git rebase $BASE_BRANCH`, then run it. For a branch created before33 `.gitattributes` gained the `.lycheecache` union rule, prefer rebase: merge34 attributes resolve against the current checkout's tree, which during a rebase35 is the updated base.36373. If there are no conflicts, the operation completes on its own. Run the38 [residue test](#residue-test), then stop: we are done.39404. Conflicts other than `.lycheecache`: resolve them with the user.41425. If a `.lycheecache` conflict remains, proceed to **Resolve**. Otherwise,43 conclude the operation per **Resolve** steps 2-3, then run the44 [residue test](#residue-test).4546## Residue test4748A conflict-free union merge can still leave residue that fails the49`CACHE updates committed?` check: duplicate URLs or out-of-order lines.5051```sh52cut -d, -f1 .lycheecache | sort | uniq -d # any output: duplicate URLs53sort -c .lycheecache # any error: out-of-order lines54```5556If either check trips, run **Resolve** steps 4-6 to regenerate, commit, and push57the cache.5859## Resolve60611. Check out the `$BASE_BRANCH` version of `.lycheecache`. Assumes the active62 branch is being rebased/merged from `$BASE_BRANCH`, not the other way around:6364 | Operation | Command |65 | ------------------------------------------- | ------------------------------------ |66 | Rebase of active branch onto `$BASE_BRANCH` | `git checkout --ours .lycheecache` |67 | Merge of `$BASE_BRANCH` into active branch | `git checkout --theirs .lycheecache` |68692. Stage the resolved files, then continue:70 - Rebase: `git add .lycheecache && git rebase --continue`71 - Merge: `git add .lycheecache && git commit --no-edit`72 - If other files were resolved in Preparation step 4, `git add` those too73 before continuing.74753. Rebase only: for each subsequent rebase stop that conflicts on76 `.lycheecache`, repeat Resolve steps 1–2. If other paths are also conflicted77 on that stop, run Preparation step 4 first.78794. Run `npm run fix:link-cache` once, after the entire rebase/merge completes.80 Note: this runs a Hugo build (lean by default) and link check — requires81 network, installed npm dependencies, and populated submodules; can take82 several minutes.83845. Commit the changes, if any:8586 ```sh87 git add .lycheecache88 git diff --cached --quiet .lycheecache || \89 git commit -m "Refresh link cache after resolving conflicts"90 ```91926. Push:93 - Merge: `git push`94 - Rebase: `git push --force-with-lease`9596<!-- prettier-ignore-start -->97[Link cache]: https://opentelemetry.io/site/build/link-checking/#link-cache98<!-- prettier-ignore-end -->
open-telemetry