OpenParable
Skip to content
← Back to skills

Resolve Refcache Conflicts

Development
resolve-refcache-conflicts

Resolve Refcache Conflicts is an Agent Skill for development published in the open-telemetry/opentelemetry.io repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Skill for resolving static/refcache.json merge or rebase conflicts in the current branch or a specified PR.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/open-telemetry/opentelemetry.io/blob/HEAD/.claude/skills/resolve-refcache-conflicts/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/resolve-refcache-conflicts, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

static/refcache.json is an auto-generated file. Resolving conflicts requires first taking the integration branch's side, finishing the merge/rebase, then running npm run fix:refcache to restore any URLs unique to the active branch.

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:

  1. 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.
  2. 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.

  3. If there are no conflicts: stop, we are done.

  4. Conflicts other than static/refcache.json: resolve them with the user.

  5. If no static/refcache.json conflict remains: stop, we are done. Otherwise, proceed to Resolve.

Resolve

  1. Check out the $BASE_BRANCH version of static/refcache.json. Assumes the active branch is being rebased/merged from $BASE_BRANCH, not the other way around:

    OperationCommand
    Rebase of active branch onto $BASE_BRANCHgit checkout --ours static/refcache.json
    Merge of $BASE_BRANCH into active branchgit checkout --theirs static/refcache.json
  2. Stage the resolved files, then continue:

    • Rebase: git add static/refcache.json && git rebase --continue
    • Merge: git add static/refcache.json && git commit --no-edit
    • If other files were resolved in Preparation step 4, git add those too before continuing.
  3. Rebase only: for each subsequent rebase stop that conflicts on static/refcache.json, repeat Resolve steps 1–2. If other paths are also conflicted on that stop, run Preparation step 4 first.

  4. Run npm run fix:refcache once, after the entire rebase/merge completes. Note: this runs a full Hugo build and link check — requires network, installed npm dependencies, and populated submodules; can take several minutes.

  5. Commit the changes, if any:

    git add static/refcache.json
    git diff --cached --quiet static/refcache.json || \
       git commit -m "Refresh refcache after resolving conflicts"
    
  6. Push:

    • Merge: git push
    • Rebase: git push --force-with-lease