External Merge for Visual Studio Code

A Visual Studio Code extension to launch your favorite external diff/merge tool to compare the active editor's content with your clipboard. It's the perfect companion for reviewing and integrating code snippets generated by AI assistants like Gemini, ChatGPT or Claude.

This project is the original TypeScript/VS Code version of the C# port for Visual Studio.

How It Works

When using an AI code assistant, you often get a large block of code. The standard workflow of copy-pasting overwrites your work and makes it difficult to see what changed.

This extension streamlines the process by letting you use a powerful, dedicated diff tool to see a side-by-side comparison, making it trivial to review, merge, and accept changes with confidence.

Features

• ✅ Launch Any Diff Tool: Configure the extension to use your favorite tool (Beyond Compare, KDiff3, WinMerge, Meld, etc.).
• 🚀 Side-by-Side View: Compares the content of your currently active editor tab with the text in your clipboard.
• ⚡ Optional 3-Way Merge: Configure a true 3-way merge by using the current editor content as the base.
• 💾 Seamless Integration: After you merge and save in the external tool, the changes are instantly applied back to your editor in VS Code.
• ⌨️ Configurable Hotkey: Trigger the merge with a convenient keyboard shortcut (defaults to Ctrl+Alt+M).

Installation

1. Open VS Code.
2. Go to the Extensions view (Ctrl+Shift+X).
3. Search for External Clipboard Merge.
4. Click Install.
5. Restart VS Code.

Configuration

All settings are configured in your VS Code settings.json file (Ctrl+,). Search for "externalMerge".

1. externalMerge.toolPath

The full, absolute path to your merge tool's executable.

• Example: C:\\Program Files\\Beyond Compare 4\\BCompare.exe (note the double backslashes on Windows) or /usr/bin/meld on Linux.

2. externalMerge.toolArguments

The command-line arguments to pass to the tool. The extension substitutes the following placeholders:

• {filePath1}: Path to a temporary file containing the active editor's content.
• {filePath2}: Path to a temporary file containing the clipboard content.
• {outputFilePath}: Path to the temporary file where the merged result should be saved.
• {baseFilePath}: (For 3-way merge) Path to a temp file containing the base content.

Configuration Examples for Popular Tools

Beyond Compare:

"externalMerge.toolArguments": "\"{filePath1}\" \"{filePath2}\" /savetarget=\"{outputFilePath}\""

KDiff3:

"externalMerge.toolArguments": "\"{filePath1}\" \"{filePath2}\" -o \"{outputFilePath}\""

WinMerge:

"externalMerge.toolArguments": "/e /u \"{filePath1}\" \"{filePath2}\" \"{outputFilePath}\""

(/e closes WinMerge on a single Esc key press, /u prevents adding paths to MRU list)

Meld: (Meld typically modifies one of the input files. We can configure it to modify the "editor" temp file.)

"externalMerge.toolArguments": "\"{filePath1}\" \"{filePath2}\""

• Important: If your tool modifies an input file in-place (like Meld), make sure the {outputFilePath} placeholder is NOT present in your toolArguments. The extension will then correctly read the result from the {filePath1} temp file.

3. Advanced: 3-Way Merge

For a more advanced workflow, you can perform a 3-way merge. This is useful when you consider the current editor content as the base against which two different sets of changes are compared.

To enable this, set "externalMerge.useThreeWayMergeIfBaseProvided": true and include the {baseFilePath} placeholder in your arguments.

• {baseFilePath} will be the original editor content.
• {filePath1} will be a copy of the editor content, intended to be modified by the merge tool (often representing "Mine").
• {filePath2} will be the clipboard content (often representing "Theirs").

3-Way Merge Example for JetBrains Rider's Tool:

Rider's command is merge <local> <remote> <base> <output>. You would configure it like this:

"externalMerge.useThreeWayMergeIfBaseProvided": true,
"externalMerge.toolArguments": "merge \"{filePath1}\" \"{filePath2}\" \"{baseFilePath}\" \"{outputFilePath}\""

Usage

1. Open a file in the VS Code editor.
2. Copy the new code you want to merge into your clipboard.
3. In VS Code, press Ctrl+Alt+M (or trigger the command Merge Active File with Clipboard in External Tool from the Command Palette).
4. Your external merge tool will launch.
5. Make your merges in the tool.
6. Save the result and close the tool.
7. The changes will be reflected in your VS Code editor.

Building from Source

If you want to build the extension yourself:

1. Clone this repository.
2. Open a terminal in the root folder.
3. Run npm install.
4. Run npm run vsix to compile and package the extension.
5. The .vsix installer will be created in the root directory, which you can install via the VS Code command palette (Extensions: Install from VSIX...).

Contributing

Contributions are welcome! Please feel free to open an issue to report a bug or suggest a feature, or create a pull request with your improvements.

License

This project is licensed under the MIT License.