--- title: PR Reference Skill Reference description: XML output format, usage scenarios, output path variations, and semantic invocation patterns author: Microsoft ms.date: 2026-05-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 `` root: ```xml feature/add-authentication origin/main 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 +} ``` ### Element Reference | Element | Description | |--------------------|----------------------------------------------------------------| | `` | Active git branch name or `detached@` in CI environments | | `` | Comparison branch provided via `--base-branch` / `-BaseBranch` | | `` | Ordered commit entries with hash, date, subject, and body | | `` | Unified diff output from `git diff` | Each `` element has `hash` and `date` attributes. The `` and `` 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: ```bash ./scripts/generate.sh ``` ```powershell ./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: ```bash ./scripts/generate.sh --base-branch origin/release/2.0 ``` ```powershell ./scripts/generate.ps1 -BaseBranch release/2.0 ``` The PowerShell script automatically resolves `origin/release/2.0` when a bare branch name is provided. ### Markdown Exclusion for PR Descriptions Exclude documentation changes from the diff when generating PR descriptions, reducing noise in the output: ```bash ./scripts/generate.sh --no-md-diff ``` ```powershell ./scripts/generate.ps1 -ExcludeMarkdownDiff ``` ### Custom Output Path Write the XML to a branch-specific tracking directory for PR review workflows: ```bash ./scripts/generate.sh \ --output .copilot-tracking/pr/review/feature-auth/pr-reference.xml ``` ```powershell ./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: ```bash ./scripts/generate.sh \ --base-branch origin/main \ --output .copilot-tracking/workitems/discovery/sprint-42/git-branch-diff.xml ``` ```powershell ./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: | Workflow | Output Filename | Output Path | |-----------------------|-----------------------|------------------------------------------------------------------------| | Default PR generation | `pr-reference.xml` | `.copilot-tracking/pr/pr-reference.xml` | | PR review | `pr-reference.xml` | `.copilot-tracking/pr/review/{{branch}}/pr-reference.xml` | | New PR creation | `pr-reference.xml` | `.copilot-tracking/pr/new/{{branch}}/pr-reference.xml` | | Work item discovery | `git-branch-diff.xml` | `.copilot-tracking/workitems/discovery/{{folder}}/git-branch-diff.xml` | ## Utility Script Reference ### list-changed-files Extracts file paths from the PR reference XML diff headers. | Parameter | Flag (bash) | Flag (PowerShell) | Default | Description | |---------------|----------------|-------------------|-----------------------------------------|------------------------------------------------| | Input path | `--input, -i` | `-InputPath` | `.copilot-tracking/pr/pr-reference.xml` | Path to the PR reference XML | | Change type | `--type, -t` | `-Type` | `all` | Filter: all, added, deleted, modified, renamed | | Output format | `--format, -f` | `-Format` | `plain` | Output: plain, json, or markdown | ### read-diff Reads diff content with chunking and file filtering support. | Parameter | Flag (bash) | Flag (PowerShell) | Default | Description | |--------------|--------------------|-------------------|-----------------------------------------|--------------------------------------| | Input path | `--input, -i` | `-InputPath` | `.copilot-tracking/pr/pr-reference.xml` | Path to the PR reference XML | | Chunk number | `--chunk, -c` | `-Chunk` | - | 1-based chunk number to read | | Chunk size | `--chunk-size, -s` | `-ChunkSize` | 500 | Lines per chunk | | Line range | `--lines, -l` | `-Lines` | - | Range format: START,END or START-END | | File path | `--file, -f` | `-File` | - | Extract diff for specific file | | Summary | `--summary` | `-Summary` | - | Show file list with change stats | | Info | `--info` | `-Info` | - | Show chunk breakdown without content | ## 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. ```markdown Generate the PR reference XML file comparing the current branch against origin/main. 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.