Using apply_patch for Multi-File Changes

I often find myself frustrated when trying to update multiple files at once. It is annoying when a single edit fails because the file structure changed slightly or the context shifted between calls. Dealing with multi-file or multi-hunk edits usually feels brittle, and I prefer a more structured way to handle these changes without breaking the workspace.

The apply_patch tool is designed for exactly this. It lets you group file operations—like adding, updating, or deleting files—into a single structured block.

What You’ll Need

• An OpenAI model (this tool is OpenAI-only, including OpenAI Codex).
• The configuration tools.exec.applyPatch.enabled set to true in your settings.

Quick Start

Getting started with apply_patch takes about five minutes. I recommend following these four steps to ensure your edits are applied correctly.

1. Enable the Tool

This tool is experimental and disabled by default. You must enable it in your configuration. Note that all configuration for this tool lives under tools.exec.

// Example config
{
  "tools": {
    "exec": {
      "applyPatch": {
        "enabled": true
      }
    }
  }
}

2. Format Your Patch

The tool requires a specific structure. You must wrap everything between *** Begin Patch and *** End Patch. You can add, update, or delete files within this block.

*** Begin Patch
*** Add File: path/to/file.txt
+line 1
+line 2
*** Update File: src/app.ts
@@
-old line
+new line
*** Delete File: obsolete.txt
*** End Patch

3. Use Special Markers

If you need to rename a file, use *** Move to: inside an *** Update File: hunk. If you need to insert text at the very end of a file, use the *** End of File marker.

4. Execute the Tool Call

When you call the tool, you provide the entire patch as a single input string. Here is how that looks in a JSON request:

{
  "tool": "apply_patch",
  "input": "*** Begin Patch\n*** Update File: src/index.ts\n@@\n-const foo = 1\n+const foo = 2\n*** End Patch"
}

Troubleshooting

If things aren’t working as expected, check these four common areas:

1. Tool is Disabled: The tool will not run unless tools.exec.applyPatch.enabled is explicitly set to true.
2. Model Incompatibility: This tool only works with OpenAI models. If you are using a different provider, the tool will be unavailable.
3. Path Resolution: All file paths are resolved relative to your workspace root. Double-check that your paths don’t include unnecessary leading slashes or incorrect directories.
4. Syntax Errors: Ensure you have included both the *** Begin Patch and *** End Patch markers. The tool will fail if the input string does not follow this exact structure.

If you need help setting up your environment or configuring these flags, check out the AI Setup Assistant.

What’s Next

• Tool Configuration Overview
• Working with Workspace Files