Pr Reference

title: PR Reference Skill Reference description: XML output format, usage scenarios, output path variations, and semantic invocation patterns author: Microsoft ms.date: 2026-09-21 ms.topic: reference keywords:

• pr-reference

• xml

• git estimated_reading_time: 5

XML Output Format

The PR reference generator produces an XML document with four top-level elements inside a <commit_history> root:

<commit_history>
  <current_branch>
    feature/add-authentication
  </current_branch>

  <base_branch>
    origin/main
  </base_branch>

  <commits>
    <commit hash="f3a21c7" date="2026-02-15">
      <message>
        <subject><![CDATA[feat: add JWT token validation]]></subject>
        <body><![CDATA[Implements token validation middleware with
expiration checks and signature verification.]]></body>
      </message>
    </commit>
    <commit hash="b8c94e2" date="2026-02-14">
      <message>
        <subject><![CDATA[chore: add auth dependency]]></subject>
        <body><![CDATA[]]></body>
      </message>
    </commit>
  </commits>

  <full_diff>
diff --git a/src/middleware/auth.ts b/src/middleware/auth.ts
new file mode 100644
index 0000000..a1b2c3d
--- /dev/null
+++ b/src/middleware/auth.ts
@@ -0,0 +1,25 @@
+import { verify } from 'jsonwebtoken';
+
+export function validateToken(token: string): boolean {
+  // Token validation logic
+}
  </full_diff>
</commit_history>

Element Reference

Each <commit> element has hash and date attributes. The <subject> and <body> elements wrap content in CDATA sections to preserve special characters.

Usage Scenarios

Default PR Reference Generation

Generate a reference comparing the current branch against origin/main with output at the default location:

./scripts/generate.sh

./scripts/generate.ps1

Output: .copilot-tracking/pr/pr-reference.xml

Custom Base Branch Comparison

Compare against a branch other than origin/main, such as a release branch:

./scripts/generate.sh --base-branch origin/release/2.0

./scripts/generate.ps1 -BaseBranch release/2.0

The PowerShell script automatically resolves origin/release/2.0 when a bare branch name is provided.

Automatic Default Branch Detection

Detect the remote default branch instead of naming it, for repositories whose default is not main:

./scripts/generate.sh --base-branch auto

./scripts/generate.ps1 -BaseBranch auto

Both scripts resolve auto from refs/remotes/origin/HEAD and fall back to origin/main when that symbolic ref is unset.

Merge-Base Three-Way Comparison

Compare against the common ancestor of the current branch and the base branch, so commits added to the base branch after you branched stay out of the diff:

./scripts/generate.sh --merge-base

./scripts/generate.ps1 -MergeBase

Markdown Exclusion for PR Descriptions

Exclude documentation changes from the diff when generating PR descriptions, reducing noise in the output:

./scripts/generate.sh --no-md-diff

./scripts/generate.ps1 -ExcludeMarkdownDiff

Extension and Path Exclusion

Exclude file extensions or path prefixes from the diff, for branches that carry generated or vendored changes alongside source edits:

./scripts/generate.sh --exclude-ext yml,yaml,json --exclude-path docs/,generated/

./scripts/generate.ps1 -ExcludeExt yml,yaml,json -ExcludePath docs/,generated/

Both flags take comma-separated values. A leading dot on an extension and a trailing slash on a path are stripped automatically.

Custom Output Path

Write the XML to a branch-specific tracking directory for PR review workflows:

./scripts/generate.sh \
  --output .copilot-tracking/pr/review/feature-auth/pr-reference.xml

./scripts/generate.ps1 `
  -OutputPath .copilot-tracking/pr/review/feature-auth/pr-reference.xml

Work Item Discovery

Use a custom filename for work item discovery workflows that analyze branch changes:

./scripts/generate.sh \
  --base-branch origin/main \
  --output .copilot-tracking/workitems/discovery/sprint-42/git-branch-diff.xml

./scripts/generate.ps1 `
  -BaseBranch main `
  -OutputPath .copilot-tracking/workitems/discovery/sprint-42/git-branch-diff.xml

Output Path Variations

Different workflows use different output paths and filenames:

Utility Script Reference

list-changed-files

Extracts file paths from the PR reference XML diff headers.

read-diff

Reads diff content with chunking and file filtering support.

Semantic Invocation

Callers reference the skill by describing the task intent rather than hardcoding script paths. Copilot matches the task description against the skill's description and loads the skill on-demand.

<!-- Semantic invocation (preferred) -->
Generate the PR reference XML file comparing the current branch against origin/main.

<!-- Semantic invocation with parameters -->
Generate a PR reference XML excluding markdown diffs, saving to the review tracking directory.

Avoid referencing script paths directly in prompts, agents, or instructions. The agent selects the appropriate script based on the current platform.