@aspruyt/xfg 1.3.1 → 1.5.0

package/PR.md

@@ -1,10 +1,10 @@
 ## Summary
 
-Automated sync of `{{FILE_NAME}}` configuration file.
+Automated sync of configuration files.
 
 ## Changes
 
-- {{ACTION}} `{{FILE_NAME}}` in repository root
+{{FILE_CHANGES}}
 
 ## Source
 

package/README.md

@@ -5,25 +5,9 @@
 [![npm downloads](https://img.shields.io/npm/dw/@aspruyt/xfg.svg)](https://www.npmjs.com/package/@aspruyt/xfg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-A CLI tool that syncs JSON, JSON5, YAML, or text configuration files across multiple GitHub, Azure DevOps, and GitLab repositories by creating pull requests (or merge requests for GitLab). Output format is automatically detected from the target filename extension (`.json` → JSON, `.json5` → JSON5, `.yaml`/`.yml` → YAML, other → text).
+A CLI tool that syncs JSON, JSON5, YAML, or text configuration files across multiple GitHub, Azure DevOps, and GitLab repositories by creating pull requests.
 
-## Table of Contents
-
-- [Quick Start](#quick-start)
-- [Features](#features)
-- [How It Works](#how-it-works)
-- [Installation](#installation)
-- [Prerequisites](#prerequisites)
-- [Usage](#usage)
-- [Configuration Format](#configuration-format)
-- [Examples](#examples)
-- [Supported Git URL Formats](#supported-git-url-formats)
-- [CI/CD Integration](#cicd-integration)
-- [Output Examples](#output-examples)
-- [Troubleshooting](#troubleshooting)
-- [IDE Integration](#ide-integration)
-- [Development](#development)
-- [License](#license)
+**[Full Documentation](https://anthony-spruyt.github.io/xfg/)**
 
 ## Quick Start
 
@@ -45,7 +29,6 @@ files:
       trailingComma: es5
 
 repos:
-  # Multiple repos can share the same config
   - git:
       - git@github.com:your-org/frontend-app.git
       - git@github.com:your-org/backend-api.git
@@ -61,7 +44,7 @@ xfg --config ./config.yaml
 ## Features
 
 - **Multi-File Sync** - Sync multiple config files in a single run
-- **Multi-Format Output** - JSON, YAML, or plain text based on filename extension
+- **Multi-Format Output** - JSON, JSON5, YAML, or plain text based on filename extension
 - **Subdirectory Support** - Sync files to any path (e.g., `.github/workflows/ci.yaml`)
 - **Text Files** - Sync `.gitignore`, `.markdownlintignore`, etc. with string or lines array
 - **File References** - Use `@path/to/file` to load content from external template files
@@ -78,958 +61,13 @@ xfg --config ./config.yaml
 - **Error Resilience** - Continues processing if individual repos fail
 - **Automatic Retries** - Retries transient network errors with exponential backoff
 
-## Installation
-
-### From npm
-
-```bash
-npm install -g @aspruyt/xfg
-```
-
-### From Source
-
-```bash
-git clone https://github.com/anthony-spruyt/xfg.git
-cd xfg
-npm install
-npm run build
-```
-
-### Using Dev Container
-
-Open this repository in VS Code with the Dev Containers extension. The container includes all dependencies pre-installed and the project pre-built.
-
-## Prerequisites
-
-### GitHub Authentication
-
-Before using with GitHub repositories, authenticate with the GitHub CLI:
-
-```bash
-gh auth login
-```
-
-### Azure DevOps Authentication
-
-Before using with Azure DevOps repositories, authenticate with the Azure CLI:
-
-```bash
-az login
-az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT
-```
-
-### GitLab Authentication
-
-Before using with GitLab repositories, authenticate with the GitLab CLI:
-
-```bash
-glab auth login
-```
-
-For self-hosted GitLab instances:
-
-```bash
-glab auth login --hostname gitlab.example.com
-```
-
-## Usage
-
-```bash
-# Basic usage
-xfg --config ./config.yaml
-
-# Dry run (no changes made)
-xfg --config ./config.yaml --dry-run
-
-# Custom work directory
-xfg --config ./config.yaml --work-dir ./my-temp
-
-# Custom branch name
-xfg --config ./config.yaml --branch feature/update-eslint
-```
-
-### Options
-
-| Option             | Alias | Description                                                                    | Required |
-| ------------------ | ----- | ------------------------------------------------------------------------------ | -------- |
-| `--config`         | `-c`  | Path to YAML config file                                                       | Yes      |
-| `--dry-run`        | `-d`  | Show what would be done without making changes                                 | No       |
-| `--work-dir`       | `-w`  | Temporary directory for cloning (default: `./tmp`)                             | No       |
-| `--retries`        | `-r`  | Number of retries for network operations (default: 3)                          | No       |
-| `--branch`         | `-b`  | Override branch name (default: `chore/sync-{filename}` or `chore/sync-config`) | No       |
-| `--merge`          | `-m`  | PR merge mode: `manual`, `auto` (default), `force` (bypass checks)             | No       |
-| `--merge-strategy` |       | Merge strategy: `merge`, `squash` (default), `rebase`                          | No       |
-| `--delete-branch`  |       | Delete source branch after merge                                               | No       |
-
-## Configuration Format
-
-### Basic Structure
-
-```yaml
-files:
-  my.config.json: # Target file (.json outputs JSON, .yaml/.yml outputs YAML)
-    mergeStrategy: replace # Array merge strategy for this file (optional)
-    content: # Base config content
-      key: value
-
-repos: # List of repositories
-  - git: git@github.com:org/repo.git
-    files: # Per-repo file overrides (optional)
-      my.config.json:
-        content:
-          key: override
-```
-
-### Root-Level Fields
-
-| Field       | Description                                          | Required |
-| ----------- | ---------------------------------------------------- | -------- |
-| `files`     | Map of target filenames to configs                   | Yes      |
-| `repos`     | Array of repository configurations                   | Yes      |
-| `prOptions` | Global PR merge options (can be overridden per-repo) | No       |
-
-### Per-File Fields
-
-| Field           | Description                                                                                                                                         | Required |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| `content`       | Base config: object for JSON/YAML files, string or string[] for text files, or `@path/to/file` to load from external template (omit for empty file) | No       |
-| `mergeStrategy` | Merge strategy: `replace`, `append`, `prepend` (for arrays and text lines)                                                                          | No       |
-| `createOnly`    | If `true`, only create file if it doesn't exist                                                                                                     | No       |
-| `executable`    | Mark file as executable. `.sh` files are auto-executable unless set to `false`. Set to `true` for non-.sh files.                                    | No       |
-| `header`        | Comment line(s) at top of YAML files (string or array)                                                                                              | No       |
-| `schemaUrl`     | Adds `# yaml-language-server: $schema=<url>` to YAML files                                                                                          | No       |
-
-### Per-Repo Fields
-
-| Field       | Description                                  | Required |
-| ----------- | -------------------------------------------- | -------- |
-| `git`       | Git URL (string) or array of URLs            | Yes      |
-| `files`     | Per-repo file overrides (optional)           | No       |
-| `prOptions` | Per-repo PR merge options (overrides global) | No       |
-
-### PR Options Fields
-
-| Field           | Description                                                                 | Default  |
-| --------------- | --------------------------------------------------------------------------- | -------- |
-| `merge`         | Merge mode: `manual` (leave open), `auto` (merge when checks pass), `force` | `auto`   |
-| `mergeStrategy` | How to merge: `merge`, `squash`, `rebase`                                   | `squash` |
-| `deleteBranch`  | Delete source branch after merge                                            | `true`   |
-| `bypassReason`  | Reason for bypassing policies (Azure DevOps only, required for `force`)     | -        |
-
-### Per-Repo File Override Fields
-
-| Field        | Description                                             | Required |
-| ------------ | ------------------------------------------------------- | -------- |
-| `content`    | Content overlay merged onto file's base content         | No       |
-| `override`   | If `true`, ignore base content and use only this repo's | No       |
-| `createOnly` | Override root-level `createOnly` for this repo          | No       |
-| `executable` | Override root-level `executable` for this repo          | No       |
-| `header`     | Override root-level `header` for this repo              | No       |
-| `schemaUrl`  | Override root-level `schemaUrl` for this repo           | No       |
-
-**File Exclusion:** Set a file to `false` to exclude it from a specific repo:
-
-```yaml
-repos:
-  - git: git@github.com:org/repo.git
-    files:
-      eslint.json: false # This repo won't receive eslint.json
-```
-
-### Environment Variables
-
-Use `${VAR}` syntax in string values:
-
-```yaml
-files:
-  app.config.json:
-    content:
-      apiUrl: ${API_URL} # Required - errors if not set
-      environment: ${ENV:-development} # With default value
-      secretKey: ${SECRET:?Secret required} # Required with custom error message
-
-repos:
-  - git: git@github.com:org/backend.git
-```
-
-#### Escaping Variable Syntax
-
-If your target file needs literal `${VAR}` syntax (e.g., for devcontainer.json, shell scripts, or other templating systems), use `$$` to escape:
-
-```yaml
-files:
-  .devcontainer/devcontainer.json:
-    content:
-      name: my-dev-container
-      remoteEnv:
-        # Escaped - outputs literal ${localWorkspaceFolder} for VS Code
-        LOCAL_WORKSPACE_FOLDER: "$${localWorkspaceFolder}"
-        CONTAINER_WORKSPACE: "$${containerWorkspaceFolder}"
-        # Interpolated - replaced with actual env value
-        API_KEY: "${API_KEY}"
-```
-
-Output:
-
-```json
-{
-  "name": "my-dev-container",
-  "remoteEnv": {
-    "LOCAL_WORKSPACE_FOLDER": "${localWorkspaceFolder}",
-    "CONTAINER_WORKSPACE": "${containerWorkspaceFolder}",
-    "API_KEY": "actual-api-key-value"
-  }
-}
-```
-
-This follows the same escape convention used by Docker Compose.
-
-### Merge Directives
-
-Control array merging with the `$arrayMerge` directive:
-
-```yaml
-files:
-  config.json:
-    content:
-      features:
-        - core
-        - monitoring
-
-repos:
-  - git: git@github.com:org/repo.git
-    files:
-      config.json:
-        content:
-          features:
-            $arrayMerge: append # append | prepend | replace
-            values:
-              - custom-feature # Results in: [core, monitoring, custom-feature]
-```
-
-## Examples
-
-### Multi-File Sync
-
-Sync multiple configuration files to all repos:
-
-```yaml
-files:
-  .eslintrc.json:
-    content:
-      extends: ["@org/eslint-config"]
-      rules:
-        no-console: warn
-
-  .prettierrc.yaml:
-    content:
-      semi: false
-      singleQuote: true
-
-  tsconfig.json:
-    content:
-      compilerOptions:
-        strict: true
-        target: ES2022
-
-repos:
-  - git:
-      - git@github.com:org/frontend.git
-      - git@github.com:org/backend.git
-      - git@github.com:org/shared-lib.git
-```
-
-### Shared Config Across Teams
-
-Define common settings once, customize per team:
-
-```yaml
-files:
-  service.config.json:
-    content:
-      version: "2.0"
-      logging:
-        level: info
-        format: json
-      features:
-        - health-check
-        - metrics
-
-repos:
-  # Platform team repos - add extra features
-  - git:
-      - git@github.com:org/api-gateway.git
-      - git@github.com:org/auth-service.git
-    files:
-      service.config.json:
-        content:
-          team: platform
-          features:
-            $arrayMerge: append
-            values:
-              - tracing
-              - rate-limiting
-
-  # Data team repos - different logging
-  - git:
-      - git@github.com:org/data-pipeline.git
-      - git@github.com:org/analytics.git
-    files:
-      service.config.json:
-        content:
-          team: data
-          logging:
-            level: debug
-
-  # Legacy service - completely different config
-  - git: git@github.com:org/legacy-api.git
-    files:
-      service.config.json:
-        override: true
-        content:
-          version: "1.0"
-          legacy: true
-```
-
-### Environment-Specific Values
-
-Use environment variables for secrets and environment-specific values:
-
-```yaml
-files:
-  app.config.json:
-    content:
-      database:
-        host: ${DB_HOST:-localhost}
-        port: ${DB_PORT:-5432}
-        password: ${DB_PASSWORD:?Database password required}
-
-      api:
-        baseUrl: ${API_BASE_URL}
-        timeout: 30000
-
-repos:
-  - git: git@github.com:org/backend.git
-```
-
-### Per-File Merge Strategies
-
-Different files can use different array merge strategies:
-
-```yaml
-files:
-  eslint.config.json:
-    mergeStrategy: append # Extends will append
-    content:
-      extends: ["@company/base"]
-
-  tsconfig.json:
-    mergeStrategy: replace # Lib will replace entirely
-    content:
-      compilerOptions:
-        lib: ["ES2022"]
-
-repos:
-  - git: git@github.com:org/frontend.git
-    files:
-      eslint.config.json:
-        content:
-          extends: ["plugin:react/recommended"]
-      # Results in extends: ["@company/base", "plugin:react/recommended"]
-```
-
-### Create-Only Files (Defaults That Can Be Customized)
-
-Some files should only be created once as defaults, allowing repos to maintain their own versions:
-
-```yaml
-files:
-  .trivyignore.yaml:
-    createOnly: true # Only create if doesn't exist
-    content:
-      vulnerabilities: []
-
-  .prettierignore:
-    createOnly: true
-    content:
-      patterns:
-        - "dist/"
-        - "node_modules/"
-
-  eslint.config.json:
-    content: # Always synced (no createOnly)
-      extends: ["@company/base"]
-
-repos:
-  - git: git@github.com:org/repo.git
-    # .trivyignore.yaml and .prettierignore only created if missing
-    # eslint.config.json always updated
-
-  - git: git@github.com:org/special-repo.git
-    files:
-      .trivyignore.yaml:
-        createOnly: false # Override: always sync this file
-```
-
-### YAML Comments and Empty Files
-
-Add schema directives and comments to YAML files, or create empty files:
-
-```yaml
-files:
-  # YAML file with schema directive and header comment
-  trivy.yaml:
-    schemaUrl: https://trivy.dev/latest/docs/references/configuration/config-file/
-    header: "Trivy security scanner configuration"
-    content:
-      exit-code: 1
-      scan:
-        scanners:
-          - vuln
-
-  # Empty file (content omitted)
-  .prettierignore:
-    createOnly: true
-    # No content = empty file
-
-  # YAML with multi-line header
-  config.yaml:
-    header:
-      - "Auto-generated configuration"
-      - "Do not edit manually"
-    content:
-      version: 1
-
-repos:
-  - git: git@github.com:org/repo.git
-```
-
-**Output for trivy.yaml:**
-
-```yaml
-# yaml-language-server: $schema=https://trivy.dev/latest/docs/references/configuration/config-file/
-# Trivy security scanner configuration
-exit-code: 1
-scan:
-  scanners:
-    - vuln
-```
-
-**Note:** `header` and `schemaUrl` only apply to YAML output files (`.yaml`, `.yml`). They are ignored for JSON files.
-
-### Text Files
-
-Sync text files like `.gitignore`, `.markdownlintignore`, or `.env.example` using string or lines array content:
-
-```yaml
-files:
-  # String content (multiline text)
-  .markdownlintignore:
-    createOnly: true
-    content: |-
-      # Claude Code generated files
-      .claude/
-
-  # Lines array with merge strategy
-  .gitignore:
-    mergeStrategy: append
-    content:
-      - "node_modules/"
-      - "dist/"
-
-repos:
-  - git: git@github.com:org/repo.git
-    files:
-      .gitignore:
-        content:
-          - "coverage/" # Appended to base lines
-```
+## Documentation
 
-**Content Types:**
+Visit **[anthony-spruyt.github.io/xfg](https://anthony-spruyt.github.io/xfg/)** for:
 
-- **String content** (`content: |-`) - Direct text output with environment variable interpolation. Merging always replaces the base.
-- **Lines array** (`content: ['line1', 'line2']`) - Each line joined with newlines. Supports merge strategies (`append`, `prepend`, `replace`).
-
-**Validation:** JSON/JSON5/YAML file extensions (`.json`, `.json5`, `.yaml`, `.yml`) require object content. Other extensions require string or string[] content.
-
-### Executable Files
-
-Shell scripts (`.sh` files) are automatically marked as executable using `git update-index --add --chmod=+x`. You can control this behavior:
-
-```yaml
-files:
-  # .sh files are auto-executable (no config needed)
-  deploy.sh:
-    content: |-
-      #!/bin/bash
-      echo "Deploying..."
-
-  # Disable auto-executable for a specific .sh file
-  template.sh:
-    executable: false
-    content: "# This is just a template"
-
-  # Make a non-.sh file executable
-  run:
-    executable: true
-    content: |-
-      #!/usr/bin/env python3
-      print("Hello")
-
-repos:
-  - git: git@github.com:org/repo.git
-    files:
-      # Override executable per-repo
-      deploy.sh:
-        executable: false # Disable for this repo
-```
-
-**Behavior:**
-
-- `.sh` files: Automatically executable unless `executable: false`
-- Other files: Not executable unless `executable: true`
-- Per-repo settings override root-level settings
-
-### Subdirectory Paths
-
-Sync files to any subdirectory path - parent directories are created automatically:
-
-```yaml
-files:
-  # GitHub Actions workflow
-  ".github/workflows/ci.yaml":
-    content:
-      name: CI
-      on: [push, pull_request]
-      jobs:
-        build:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-
-  # Nested config directory
-  "config/settings/app.json":
-    content:
-      environment: production
-      debug: false
-
-repos:
-  - git:
-      - git@github.com:org/frontend.git
-      - git@github.com:org/backend.git
-```
-
-**Note:** Quote file paths containing `/` in YAML keys. Parent directories are created if they don't exist.
-
-### File References
-
-Instead of inline content, you can reference external template files using the `@path/to/file` syntax:
-
-```yaml
-files:
-  .prettierrc.json:
-    content: "@templates/prettierrc.json"
-  .eslintrc.yaml:
-    content: "@templates/eslintrc.yaml"
-    header: "Auto-generated - do not edit"
-    schemaUrl: "https://json.schemastore.org/eslintrc"
-  .gitignore:
-    content: "@templates/gitignore.txt"
-
-repos:
-  - git: git@github.com:org/repo.git
-```
-
-**How it works:**
-
-- File references start with `@` followed by a relative path
-- Paths are resolved relative to the config file's directory
-- JSON/JSON5/YAML files are parsed as objects, other files as strings
-- Metadata fields (`header`, `schemaUrl`, `createOnly`, `mergeStrategy`) remain in the config
-- Per-repo overlays still work - they merge onto the resolved file content
-
-**Example directory structure:**
-
-```
-config/
-  sync-config.yaml         # content: "@templates/prettier.json"
-  templates/
-    prettier.json          # Actual Prettier config
-    eslintrc.yaml          # Actual ESLint config
-    gitignore.txt          # Template .gitignore content
-```
-
-**Security:** File references are restricted to the config file's directory tree. Paths like `@../../../etc/passwd` or `@/etc/passwd` are blocked.
-
-### Auto-Merge PRs
-
-By default, xfg enables auto-merge on PRs when checks pass. You can override this behavior per-repo or via CLI flags:
-
-```yaml
-files:
-  .prettierrc.json:
-    content:
-      semi: false
-      singleQuote: true
-
-# Default behavior (auto-merge with squash, delete branch) - no prOptions needed
-repos:
-  # These repos use defaults (auto-merge with squash, delete branch)
-  - git:
-      - git@github.com:org/frontend.git
-      - git@github.com:org/backend.git
-
-  # This repo overrides to manual (leave PR open for review)
-  - git: git@github.com:org/needs-review.git
-    prOptions:
-      merge: manual
-
-  # This repo overrides to force merge (bypass required reviews)
-  - git: git@github.com:org/internal-tool.git
-    prOptions:
-      merge: force
-      bypassReason: "Automated config sync" # Azure DevOps only
-```
-
-**Merge Modes:**
-
-| Mode     | GitHub Behavior                                      | Azure DevOps Behavior                  | GitLab Behavior                            |
-| -------- | ---------------------------------------------------- | -------------------------------------- | ------------------------------------------ |
-| `manual` | Leave PR open for review                             | Leave PR open for review               | Leave MR open for review                   |
-| `auto`   | Enable auto-merge (requires repo setup, **default**) | Enable auto-complete (**default**)     | Merge when pipeline succeeds (**default**) |
-| `force`  | Merge with `--admin` (bypass checks)                 | Bypass policies with `--bypass-policy` | Merge immediately                          |
-
-**GitHub Auto-Merge Note:** The `auto` mode requires auto-merge to be enabled in the repository settings. If not enabled, the tool will warn and leave the PR open for manual review. Enable it with:
-
-```bash
-gh repo edit org/repo --enable-auto-merge
-```
-
-**CLI Override:** You can override config file settings with CLI flags:
-
-```bash
-# Disable auto-merge, leave PRs open for review
-xfg --config ./config.yaml --merge manual
-
-# Force merge all PRs (useful for urgent updates)
-xfg --config ./config.yaml --merge force
-```
-
-## Supported Git URL Formats
-
-### GitHub
-
-- SSH: `git@github.com:owner/repo.git`
-- HTTPS: `https://github.com/owner/repo.git`
-
-### Azure DevOps
-
-- SSH: `git@ssh.dev.azure.com:v3/organization/project/repo`
-- HTTPS: `https://dev.azure.com/organization/project/_git/repo`
-
-### GitLab
-
-- SSH: `git@gitlab.com:owner/repo.git`
-- HTTPS: `https://gitlab.com/owner/repo.git`
-- Nested groups: `git@gitlab.com:org/group/subgroup/repo.git`
-- Self-hosted SSH: `git@gitlab.example.com:owner/repo.git`
-- Self-hosted HTTPS: `https://gitlab.example.com/owner/repo.git`
-
-## How It Works
-
-```mermaid
-flowchart TB
-    subgraph Input
-        YAML[/"YAML Config File<br/>files{} + repos[]"/]
-    end
-
-    subgraph Normalization
-        EXPAND[Expand git arrays] --> MERGE[Merge base + overlay content<br/>for each file]
-        MERGE --> ENV[Interpolate env vars]
-    end
-
-    subgraph Processing["For Each Repository"]
-        CLONE[Clone Repo] --> DETECT_BRANCH[Detect Default Branch]
-        DETECT_BRANCH --> CLOSE_PR[Close Existing PR<br/>if exists]
-        CLOSE_PR --> BRANCH[Create Fresh Branch]
-        BRANCH --> WRITE[Write Config Files]
-        WRITE --> CHECK{Changes?}
-        CHECK -->|No| SKIP[Skip - No Changes]
-        CHECK -->|Yes| COMMIT[Commit & Push]
-    end
-
-    subgraph Platform["PR Creation"]
-        COMMIT --> PR_DETECT{Platform?}
-        PR_DETECT -->|GitHub| GH_PR[Create PR via gh CLI]
-        PR_DETECT -->|Azure DevOps| AZ_PR[Create PR via az CLI]
-        PR_DETECT -->|GitLab| GL_PR[Create MR via glab CLI]
-        GH_PR --> PR_CREATED[PR/MR Created]
-        AZ_PR --> PR_CREATED
-        GL_PR --> PR_CREATED
-    end
-
-    subgraph AutoMerge["Auto-Merge (default)"]
-        PR_CREATED --> MERGE_MODE{Merge Mode?}
-        MERGE_MODE -->|manual| OPEN[Leave PR Open]
-        MERGE_MODE -->|auto| AUTO[Enable Auto-Merge]
-        MERGE_MODE -->|force| FORCE[Bypass & Merge]
-    end
-
-    YAML --> EXPAND
-    ENV --> CLONE
-```
-
-For each repository in the config, the tool:
-
-1. Expands git URL arrays into individual entries
-2. For each file, merges base content with per-repo overlay
-3. Interpolates environment variables
-4. Cleans the temporary workspace
-5. Clones the repository
-6. Detects the default branch (main/master)
-7. Closes any existing PR on the branch and deletes the remote branch (fresh start)
-8. Creates a fresh branch from the default branch
-9. Writes all config files (JSON, JSON5, YAML, or text based on filename extension)
-10. Checks for changes (skips if no changes)
-11. Commits and pushes changes
-12. Creates a pull request
-13. Handles auto-merge based on configuration (auto by default)
-
-## CI/CD Integration
-
-### GitHub Actions
-
-```yaml
-name: Sync Configs
-on:
-  push:
-    branches: [main]
-    paths: ["config.yaml"]
-
-jobs:
-  sync:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-      - run: npm install -g @aspruyt/xfg
-      - run: xfg --config ./config.yaml
-        env:
-          GH_TOKEN: ${{ secrets.GH_PAT }}
-```
-
-> **Note:** `GH_PAT` must be a Personal Access Token with `repo` scope to create PRs in target repositories.
-
-### Azure Pipelines
-
-```yaml
-trigger:
-  branches:
-    include: [main]
-  paths:
-    include: ["config.yaml"]
-
-pool:
-  vmImage: "ubuntu-latest"
-
-steps:
-  - task: NodeTool@0
-    inputs:
-      versionSpec: "20.x"
-  - script: npm install -g @aspruyt/xfg
-    displayName: "Install xfg"
-  - script: xfg --config ./config.yaml
-    displayName: "Sync configs"
-    env:
-      AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
-```
-
-> **Note:** Ensure the build service account has permission to create PRs in target repositories.
-
-## Output Examples
-
-### Console Output
-
-```
-[1/3] Processing example-org/repo1...
-  ✓ Cloned repository
-  ✓ Created branch chore/sync-config
-  ✓ Wrote .eslintrc.json
-  ✓ Wrote .prettierrc.yaml
-  ✓ Committed changes
-  ✓ Pushed to remote
-  ✓ Created PR: https://github.com/example-org/repo1/pull/42
-
-[2/3] Processing example-org/repo2...
-  ✓ Cloned repository
-  ✓ Checked out existing branch chore/sync-config
-  ✓ Wrote .eslintrc.json
-  ✓ Wrote .prettierrc.yaml
-  ⊘ No changes detected, skipping
-
-[3/3] Processing example-org/repo3...
-  ✓ Cloned repository
-  ✓ Created branch chore/sync-config
-  ✓ Wrote .eslintrc.json
-  ✓ Wrote .prettierrc.yaml
-  ✓ Committed changes
-  ✓ Pushed to remote
-  ✓ PR already exists: https://github.com/example-org/repo3/pull/15
-
-Summary: 2 succeeded, 1 skipped, 0 failed
-```
-
-### Created PR
-
-The tool creates PRs with:
-
-- **Title:** `chore: sync config files` (or lists files if ≤3)
-- **Branch:** `chore/sync-config` (or custom `--branch`)
-- **Body:** Describes the sync action and lists changed files
-
-## Troubleshooting
-
-### Authentication Errors
-
-**GitHub:**
-
-```bash
-# Check authentication status
-gh auth status
-
-# Re-authenticate if needed
-gh auth login
-```
-
-**Azure DevOps:**
-
-```bash
-# Check authentication status
-az account show
-
-# Re-authenticate if needed
-az login
-az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG
-```
-
-**GitLab:**
-
-```bash
-# Check authentication status
-glab auth status
-
-# Re-authenticate if needed
-glab auth login
-
-# For self-hosted instances
-glab auth login --hostname gitlab.example.com
-```
-
-### Permission Denied
-
-- Ensure your token has write access to the target repositories
-- For GitHub, the token needs `repo` scope
-- For Azure DevOps, ensure the user/service account has "Contribute to pull requests" permission
-- For GitLab, ensure the user has at least "Developer" role on the project
-
-### Branch Already Exists
-
-The tool uses a fresh-start approach: it closes any existing PR on the branch and deletes the branch before creating a new one. This ensures each sync attempt is isolated and avoids merge conflicts from stale branches.
-
-If you see issues with stale branches:
-
-```bash
-# Manually delete the remote branch if needed
-git push origin --delete chore/sync-config
-```
-
-### Missing Environment Variables
-
-If you see "Missing required environment variable" errors:
-
-```bash
-# Set the variable before running
-export MY_VAR=value
-xfg --config ./config.yaml
-
-# Or use default values in config
-# ${MY_VAR:-default-value}
-```
-
-### Network/Proxy Issues
-
-If cloning fails behind a corporate proxy:
-
-```bash
-# Configure git proxy
-git config --global http.proxy http://proxy.example.com:8080
-git config --global https.proxy http://proxy.example.com:8080
-```
-
-### Transient Network Errors
-
-The tool automatically retries transient errors (timeouts, connection resets, rate limits) with exponential backoff. By default, it retries 3 times before failing.
-
-```bash
-# Increase retries for unreliable networks
-xfg --config ./config.yaml --retries 5
-
-# Disable retries
-xfg --config ./config.yaml --retries 0
-```
-
-Permanent errors (authentication failures, permission denied, repository not found) are not retried.
-
-## IDE Integration
-
-### VS Code YAML Schema Support
-
-For autocomplete and validation in VS Code, install the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) and add a schema reference to your config file:
-
-**Option 1: Inline comment**
-
-```yaml
-# yaml-language-server: $schema=https://raw.githubusercontent.com/anthony-spruyt/xfg/main/config-schema.json
-files:
-  my.config.json:
-    content:
-      key: value
-
-repos:
-  - git: git@github.com:org/repo.git
-```
-
-**Option 2: VS Code settings** (`.vscode/settings.json`)
-
-```json
-{
-  "yaml.schemas": {
-    "https://raw.githubusercontent.com/anthony-spruyt/xfg/main/config-schema.json": [
-      "**/sync-config.yaml",
-      "**/config-sync.yaml"
-    ]
-  }
-}
-```
-
-This enables:
-
-- Autocomplete for `files`, `repos`, `content`, `mergeStrategy`, `git`, `override`
-- Enum suggestions for `mergeStrategy` values (`replace`, `append`, `prepend`)
-- Validation of required fields
-- Hover documentation for each field
-
-## Development
-
-```bash
-# Run in development mode
-npm run dev -- --config ./fixtures/test-repos-input.yaml --dry-run
-
-# Run tests
-npm test
-
-# Build
-npm run build
-```
+- [Getting Started](https://anthony-spruyt.github.io/xfg/getting-started/) - Installation and prerequisites
+- [Configuration](https://anthony-spruyt.github.io/xfg/configuration/) - Full configuration reference
+- [Examples](https://anthony-spruyt.github.io/xfg/examples/) - Real-world usage examples
+- [Platforms](https://anthony-spruyt.github.io/xfg/platforms/) - GitHub, Azure DevOps, GitLab setup
+- [CI/CD Integration](https://anthony-spruyt.github.io/xfg/ci-cd/) - GitHub Actions, Azure Pipelines
+- [Troubleshooting](https://anthony-spruyt.github.io/xfg/troubleshooting/)

package/dist/config-normalizer.js

@@ -135,5 +135,6 @@ export function normalizeConfig(raw) {
     }
     return {
         repos: expandedRepos,
+        prTemplate: raw.prTemplate,
     };
 }

package/dist/config-validator.js

@@ -108,7 +108,8 @@ export function validateRawConfig(config) {
                     continue;
                 }
                 if (fileOverride.override && !fileOverride.content) {
-                    throw new Error(`Repo ${getGitDisplayName(repo.git)} has override: true for file '${fileName}' but no content defined`);
+                    throw new Error(`Repo ${getGitDisplayName(repo.git)} has override: true for file '${fileName}' but no content defined. ` +
+                        `Use content: "" for an empty text file override, or content: {} for an empty JSON/YAML override.`);
                 }
                 // Validate content type
                 if (fileOverride.content !== undefined) {

package/dist/config.d.ts

@@ -34,6 +34,7 @@ export interface RawConfig {
     files: Record<string, RawFileConfig>;
     repos: RawRepoConfig[];
     prOptions?: PRMergeOptions;
+    prTemplate?: string;
 }
 export interface FileContent {
     fileName: string;
@@ -50,5 +51,6 @@ export interface RepoConfig {
 }
 export interface Config {
     repos: RepoConfig[];
+    prTemplate?: string;
 }
 export declare function loadConfig(filePath: string): Config;

package/dist/file-reference-resolver.js

@@ -99,6 +99,14 @@ export function resolveFileReferencesInConfig(raw, options) {
     const { configDir } = options;
     // Deep clone to avoid mutating input
     const result = JSON.parse(JSON.stringify(raw));
+    // Resolve prTemplate file reference
+    if (result.prTemplate && isFileReference(result.prTemplate)) {
+        const resolved = resolveFileReference(result.prTemplate, configDir);
+        if (typeof resolved !== "string") {
+            throw new Error(`prTemplate file reference "${result.prTemplate}" must resolve to a text file, not JSON/YAML`);
+        }
+        result.prTemplate = resolved;
+    }
     // Resolve root-level file content
     if (result.files) {
         for (const [fileName, fileConfig] of Object.entries(result.files)) {

package/dist/index.js

@@ -131,6 +131,7 @@ async function main() {
                 workDir,
                 dryRun: options.dryRun,
                 retries: options.retries,
+                prTemplate: config.prTemplate,
             });
             if (result.skipped) {
                 logger.skip(current, repoName, result.message);

package/dist/pr-creator.d.ts

@@ -14,6 +14,8 @@ export interface PROptions {
     dryRun?: boolean;
     /** Number of retries for API operations (default: 3) */
     retries?: number;
+    /** Custom PR body template */
+    prTemplate?: string;
 }
 export interface PRResult {
     url?: string;
@@ -21,9 +23,9 @@ export interface PRResult {
     message: string;
 }
 /**
- * Format PR body for multiple files
+ * Format PR body using template with {{FILE_CHANGES}} placeholder
  */
-export declare function formatPRBody(files: FileAction[]): string;
+export declare function formatPRBody(files: FileAction[], customTemplate?: string): string;
 /**
  * Generate PR title based on files changed (excludes skipped files)
  */

package/dist/pr-creator.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import { getPRStrategy, } from "./strategies/index.js";
 // Re-export for backwards compatibility and testing
 export { escapeShellArg } from "./shell-utils.js";
-function loadPRTemplate() {
+function loadDefaultTemplate() {
     // Try to find PR.md in the project root
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = dirname(__filename);
@@ -12,17 +12,21 @@ function loadPRTemplate() {
     if (existsSync(templatePath)) {
         return readFileSync(templatePath, "utf-8");
     }
-    // Fallback template for multi-file support
+    // Fallback template
     return `## Summary
+
 Automated sync of configuration files.
 
 ## Changes
+
 {{FILE_CHANGES}}
 
 ## Source
+
 Configuration synced using [xfg](https://github.com/anthony-spruyt/xfg).
 
 ---
+
 _This PR was automatically generated by [xfg](https://github.com/anthony-spruyt/xfg)_`;
 }
 /**
@@ -38,35 +42,12 @@ function formatFileChanges(files) {
         .join("\n");
 }
 /**
- * Format PR body for multiple files
+ * Format PR body using template with {{FILE_CHANGES}} placeholder
  */
-export function formatPRBody(files) {
-    const template = loadPRTemplate();
+export function formatPRBody(files, customTemplate) {
+    const template = customTemplate ?? loadDefaultTemplate();
     const fileChanges = formatFileChanges(files);
-    // Check if template supports multi-file format
-    if (template.includes("{{FILE_CHANGES}}")) {
-        return template.replace(/\{\{FILE_CHANGES\}\}/g, fileChanges);
-    }
-    // Legacy single-file template - adapt it for multiple files
-    const changedFiles = files.filter((f) => f.action !== "skip");
-    if (changedFiles.length === 1) {
-        const actionText = changedFiles[0].action === "create" ? "Created" : "Updated";
-        return template
-            .replace(/\{\{FILE_NAME\}\}/g, changedFiles[0].fileName)
-            .replace(/\{\{ACTION\}\}/g, actionText);
-    }
-    // Multiple files with legacy template - generate custom body
-    return `## Summary
-Automated sync of configuration files.
-
-## Changes
-${fileChanges}
-
-## Source
-Configuration synced using [xfg](https://github.com/anthony-spruyt/xfg).
-
----
-_This PR was automatically generated by [xfg](https://github.com/anthony-spruyt/xfg)_`;
+    return template.replace(/\{\{FILE_CHANGES\}\}/g, fileChanges);
 }
 /**
  * Generate PR title based on files changed (excludes skipped files)
@@ -83,9 +64,9 @@ export function formatPRTitle(files) {
     return `chore: sync ${changedFiles.length} config files`;
 }
 export async function createPR(options) {
-    const { repoInfo, branchName, baseBranch, files, workDir, dryRun, retries } = options;
+    const { repoInfo, branchName, baseBranch, files, workDir, dryRun, retries, prTemplate, } = options;
     const title = formatPRTitle(files);
-    const body = formatPRBody(files);
+    const body = formatPRBody(files, prTemplate);
     if (dryRun) {
         return {
             success: true,

package/dist/repository-processor.d.ts

@@ -11,6 +11,8 @@ export interface ProcessorOptions {
     retries?: number;
     /** Command executor for shell commands (for testing) */
     executor?: CommandExecutor;
+    /** Custom PR body template */
+    prTemplate?: string;
 }
 /**
  * Factory function type for creating GitOps instances.

package/dist/repository-processor.js

@@ -37,7 +37,7 @@ export class RepositoryProcessor {
     }
     async process(repoConfig, repoInfo, options) {
         const repoName = getRepoDisplayName(repoInfo);
-        const { branchName, workDir, dryRun, retries } = options;
+        const { branchName, workDir, dryRun, retries, prTemplate } = options;
         const executor = options.executor ?? defaultExecutor;
         this.gitOps = this.gitOpsFactory({ workDir, dryRun, retries });
         try {
@@ -207,6 +207,7 @@ export class RepositoryProcessor {
                 workDir,
                 dryRun,
                 retries,
+                prTemplate,
             });
             // Step 10: Handle merge options if configured
             const mergeMode = repoConfig.prOptions?.merge ?? "auto";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "1.3.1",
-  "description": "CLI tool to sync JSON or YAML configuration files across multiple GitHub, Azure DevOps, and GitLab repositories",
+  "version": "1.5.0",
+  "description": "CLI tool to sync JSON, JSON5, YAML, or text configuration files across multiple Git repositories by creating pull requests",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,7 @@
     "type": "git",
     "url": "git+https://github.com/anthony-spruyt/xfg.git"
   },
-  "homepage": "https://github.com/anthony-spruyt/xfg#readme",
+  "homepage": "https://anthony-spruyt.github.io/xfg/",
   "bugs": {
     "url": "https://github.com/anthony-spruyt/xfg/issues"
   },
@@ -36,7 +36,9 @@
     "config",
     "sync",
     "json",
+    "json5",
     "yaml",
+    "text",
     "git",
     "cli",
     "github",