patch-resolve

name	patch-resolve
description	CLI tool for patching files and resolving file includes - useful when working with LLMs

patch-resolve

Use patch-resolve to batch-apply file changes or resolve file includes. Designed to streamline working with LLMs that need to modify or reference multiple files.

Agent Rule

• When an LLM (including yourself) needs to modify multiple files, use patch with separator format instead of individual file edits
• When an LLM needs to reference multiple file contents in context, use resolve with include patterns
• Prefer patch-resolve over manual file operations for batch changes

Quick Reference

# Install globally
npm install -g patch-resolve
# or
bun add -g patch-resolve

# Patch multiple files from one patch file
patch-resolve patch my-changes.txt

# Resolve file includes and copy to clipboard
patch-resolve resolve template.ts

---

patch Command

Apply file contents from a patch file with special marker separators to their respective files.

Format: --- <path>:

patch-resolve patch <file>

Example patch file:

--- src/index.ts:
export const foo = 'bar';

--- src/utils.ts:
export function helper() {
  return 'hello';
}

Result: Creates/overwrites src/index.ts and src/utils.ts with the specified contents. Parent directories are created automatically.

---

resolve Command

Resolve file includes and copy to clipboard, also write to temp file.

Format: {{path/to/file}}

patch-resolve resolve <file> [options]

Options:

• -p, --pattern <pattern> - Custom include pattern (default: {{(.+?)}})
• -o, --output <path> - Custom output path (default: auto-generated temp file)
• --no-clipboard - Skip copying to clipboard

Example resolve file:

// Main application code
{{shared/config.ts}}
{{api/endpoints.ts}}

Result: Replaces {{...}} patterns with actual file contents, writes to temp file, and copies to clipboard.

---

Use Cases

LLM File Modification Workflow

1. LLM generates patch file with --- <path>: separators
2. Run patch-resolve patch <file> to apply all changes
3. Review changes with git diff or other tools

LLM Context Aggregation Workflow

1. Create template file with {{path/to/file}} includes
2. Run patch-resolve resolve <file> to get all content
3. Content is automatically copied to clipboard for easy sharing

Batch File Operations

• Apply multiple related changes at once
• Maintain atomicity (all changes succeed or fail together)
• Track changes in version control via patch file

---

Advanced Usage

Custom Include Patterns

patch-resolve resolve main.ts -p "<include (.+?) />"

With custom pattern in resolve file:

<include shared/config.ts />
<include api/routes.ts />

Explicit Output Path

patch-resolve resolve template.ts -o ./output/resolved.ts --no-clipboard

---

Platform Support

• Windows: Uses PowerShell Set-Clipboard for clipboard
• macOS: Uses pbcopy for clipboard
• Linux: Uses xclip -selection clipboard for clipboard

Clipboard operations are optional via --no-clipboard flag.

---

Error Handling

• Missing referenced file (resolve): Error with file path that couldn't be found
• Invalid patch format (patch): Error if separator format is incorrect
• Invalid pattern: Regex error if custom pattern is malformed

---

License

MIT