WizardMerge/frontends/cli/README.md

WizardMerge CLI Frontend

Command-line interface for WizardMerge merge conflict resolution.

Features

• Simple command-line interface
• Communicates with WizardMerge backend via HTTP API
• Suitable for automation and scripting
• Cross-platform (Linux, Windows, macOS)
• Non-interactive batch processing

Prerequisites

• C++17 compiler (GCC 7+, Clang 6+, MSVC 2017+)
• CMake 3.15+
• libcurl (for HTTP client)

Building

Install Dependencies

Ubuntu/Debian:

sudo apt-get install libcurl4-openssl-dev

macOS (Homebrew):

brew install curl

Windows: libcurl is typically included with MSVC or can be installed via vcpkg.

Build the Application

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make

Or using Ninja:

mkdir build && cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release
ninja

Run

./wizardmerge-cli --help

Usage

Basic Three-Way Merge

wizardmerge-cli merge --base base.txt --ours ours.txt --theirs theirs.txt -o result.txt

Merge with Backend Server

# Use default backend (http://localhost:8080)
wizardmerge-cli merge --base base.txt --ours ours.txt --theirs theirs.txt

# Specify custom backend URL
wizardmerge-cli --backend http://remote-server:8080 merge --base base.txt --ours ours.txt --theirs theirs.txt

Git Integration

# Resolve conflicts in a Git repository
cd /path/to/git/repo
wizardmerge-cli git-resolve

# Resolve a specific file
wizardmerge-cli git-resolve path/to/conflicted/file.txt

Batch Processing

# Process all conflicted files in current directory
wizardmerge-cli batch-resolve .

Command Reference

Global Options

• --backend <url> - Backend server URL (default: http://localhost:8080)
• --verbose, -v - Enable verbose output
• --quiet, -q - Suppress non-error output
• --help, -h - Show help message
• --version - Show version information

Commands

merge

Perform a three-way merge operation.

wizardmerge-cli merge [OPTIONS]

Options:

• --base <file> - Path to base version (required)
• --ours <file> - Path to our version (required)
• --theirs <file> - Path to their version (required)
• -o, --output <file> - Output file path (default: stdout)
• --format <format> - Output format: text, json (default: text)

git-resolve

Resolve Git merge conflicts.

wizardmerge-cli git-resolve [FILE]

Arguments:

• FILE - Specific file to resolve (optional, resolves all if omitted)

batch-resolve

Batch process multiple files.

wizardmerge-cli batch-resolve [DIRECTORY]

Arguments:

• DIRECTORY - Directory to scan for conflicts (default: current directory)

Options:

• --recursive, -r - Process directories recursively
• --pattern <pattern> - File pattern to match (default: *)

Examples

Example 1: Simple Merge

# Create test files
echo -e "line1\nline2\nline3" > base.txt
echo -e "line1\nline2-ours\nline3" > ours.txt
echo -e "line1\nline2-theirs\nline3" > theirs.txt

# Perform merge
wizardmerge-cli merge --base base.txt --ours ours.txt --theirs theirs.txt

Example 2: JSON Output

wizardmerge-cli merge --base base.txt --ours ours.txt --theirs theirs.txt --format json > result.json

Example 3: Git Workflow

# In a Git repository with conflicts
git merge feature-branch
# Conflicts occur...

# Resolve using WizardMerge
wizardmerge-cli git-resolve

# Review and commit
git commit

Exit Codes

• 0 - Success (no conflicts or all conflicts resolved)
• 1 - General error
• 2 - Invalid arguments
• 3 - Backend connection error
• 4 - File I/O error
• 5 - Merge conflicts detected (when running in strict mode)

Configuration

Configuration can be provided via:

1. Command-line arguments (highest priority)
2. Environment variables:
   • WIZARDMERGE_BACKEND - Backend server URL
   • WIZARDMERGE_VERBOSE - Enable verbose output (1/0)
3. Configuration file ~/.wizardmergerc (lowest priority)

Configuration File Format

[backend]
url = http://localhost:8080

[cli]
verbose = false
format = text

Project Structure

cli/
├── CMakeLists.txt       # CMake build configuration
├── README.md            # This file
├── src/                 # C++ source files
│   ├── main.cpp         # Application entry point
│   ├── http_client.cpp  # HTTP client implementation
│   └── file_utils.cpp   # File handling utilities
└── include/             # Header files
    ├── http_client.h
    └── file_utils.h

Development

Architecture

The CLI frontend is a thin client that:

1. Parses command-line arguments
2. Reads input files
3. Sends HTTP requests to backend
4. Formats and displays results

Dependencies

• Standard C++ library
• libcurl (for HTTP client)
• POSIX API (for file operations)

Adding New Commands

1. Add command handler in src/main.cpp
2. Implement command logic
3. Update help text and README
4. Add tests

Troubleshooting

Backend Connection Failed

# Check backend is running
curl http://localhost:8080/api/health

# Start backend if needed
cd ../../backend
./build/wizardmerge-cli

File Not Found

Ensure file paths are correct and files are readable:

ls -la base.txt ours.txt theirs.txt

Permission Denied

Check file permissions:

chmod +r base.txt ours.txt theirs.txt

License

See LICENSE for details.