feat: add Git merge driver support and refactor merge logic

- Add Git merge driver mode with 3-way merge support (%A %O %B)
- Extract common merge logic into reusable processMerge utility
- Replace StrategyStatus enum with const object for better minification
- Add comprehensive unit tests for merge-processor module
- Maintain backward compatibility with existing CLI workflows
- Auto-detect Git merge mode vs standard conflict resolution mode

BREAKING: None - fully backward compatible

Author: mayank1513

.changeset/git-merge-driver.md

@@ -0,0 +1,21 @@
+---
+"git-json-resolver": minor
+---
+
+Add Git merge driver support and improve architecture
+
+- **New feature**: CLI now supports Git merge driver mode when called with 3 positional arguments (%A %O %B)
+- **Refactored**: Extracted common merge logic into reusable `processMerge` utility (DRY principle)
+- **Testing**: Added comprehensive unit tests for merge-processor module
+- **Backward compatible**: Existing CLI workflows continue to work unchanged
+- **Auto-detection**: Automatically detects Git merge mode vs. standard conflict resolution mode
+- **Full configuration**: All existing config options (rules, strategies, matchers) work in Git merge mode
+- **Exit codes**: Proper Git merge driver exit codes (0 for success, 1 for conflicts)
+
+Usage:
+
+```bash
+git config merge.json-resolver.driver "npx git-json-resolver %A %O %B"
+```
+
+This enables automatic JSON conflict resolution during Git merges using the same powerful rule-based strategies.

README.md

@@ -19,12 +19,15 @@ A Git-aware conflict resolver for **JSON-first structured data**.
 ## Features
 
 - ⚡ **Primary focus on JSON** (first-class support)
-- 🔄 **YAML, XML, TOML** supported via conversion
-- 🧩 **Rule-based strategies** (per path/pattern)
-- 🗂️ Handles small configs to **huge repos** (optimizations built-in)
-- 🔌 **Pluggable matcher** abstraction (picomatch, micromatch supported out of the box with peerDependency)
-- 🛠️ Configurable trade-offs for **speed vs. memory**
-- 🗃️ **Planned**: extend configuration to use **different strategies per file** (ideas and edge cases welcome!)
+- 🔄 **YAML, XML, TOML, JSON5** supported via conversion
+- 🧩 **Rule-based strategies** with path/pattern matching
+- 📁 **Multiple file parallel processing** with include/exclude patterns
+- 🔌 **Pluggable matcher** abstraction (picomatch, micromatch, or custom)
+- 🛠️ **CLI and programmatic API** support
+- 📝 **Conflict sidecar files** for unresolved conflicts
+- 🔄 **Backup and restore** functionality
+- 📊 **Configurable logging** (memory or file-based)
+- 🔀 **Git merge driver** support for seamless Git integration
 
 ## Installation
 
@@ -46,6 +49,24 @@ yarn add git-json-resolver
 
 ## Quick Start
 
+### CLI Usage
+
+```bash
+# Initialize config file
+npx git-json-resolver --init
+
+# Run with default config
+npx git-json-resolver
+
+# Run with options
+npx git-json-resolver --include "**/*.json" --debug --sidecar
+
+# Restore from backups
+npx git-json-resolver --restore .merge-backups
+```
+
+### Git Integration
+
 Add a custom merge driver to your Git config:
 
 ```bash
@@ -57,73 +78,172 @@ Update `.gitattributes` to use it for JSON files:
 
 ```gitattributes
 *.json merge=json-resolver
+*.yaml merge=json-resolver
+*.yml merge=json-resolver
+*.toml merge=json-resolver
+*.xml merge=json-resolver
 ```
 
-## Example Config
+**How it works:**
+
+- Git automatically calls the merge driver during conflicts
+- Uses same configuration and strategies as CLI mode
+- Supports 3-way merge (ours, base, theirs)
+- Returns proper exit codes (0 = success, 1 = conflicts)
+
+## Configuration
+
+### Programmatic API
 
 ```ts
 import { resolveConflicts } from "git-json-resolver";
 
-const result = resolveConflicts({
-  filePath: "package.json",
-  rules: [
-    { pattern: "dependencies.*", strategy: "ours" },
-    { pattern: "version", strategy: "theirs", important: true },
-    { pattern: "scripts.build", strategy: "manual" },
-  ],
-  matcher: "picomatch", // default
-  optimize: {
-    cacheMatchers: true,
-    streamMode: false, // set true for very large repos
+await resolveConflicts({
+  defaultStrategy: ["merge", "ours"],
+  rules: {
+    "dependencies.*": ["ours"],
+    version: ["theirs!"], // ! marks as important
+    "scripts.build": ["skip"],
   },
+  include: ["**/*.json", "**/*.yaml"],
+  exclude: ["**/node_modules/**"],
+  matcher: "picomatch",
+  debug: true,
+  writeConflictSidecar: true,
+  backupDir: ".merge-backups",
 });
 ```
 
-### Upcoming: File-Specific Strategies
-
-We are exploring the ability to define **per-file strategy sets** in config, e.g.:
-
-```ts
-rulesByFile: {
-  "package.json": { version: ["theirs"], dependencies: ["ours"] },
-  "*.config.json": { "*": ["merge"] },
-},
+### Config File (`git-json-resolver.config.js`)
+
+```js
+module.exports = {
+  defaultStrategy: ["merge", "ours"],
+  rules: {
+    // Exact path matching
+    "package.json": {
+      version: ["theirs!"],
+      dependencies: ["ours"],
+    },
+    // Pattern matching
+    "*.config.json": {
+      "*": ["merge"],
+    },
+  },
+  // Alternative: byStrategy format
+  byStrategy: {
+    ours: ["dependencies.*", "devDependencies.*"],
+    "theirs!": ["version", "name"],
+  },
+  include: ["**/*.json", "**/*.yaml", "**/*.yml"],
+  exclude: ["**/node_modules/**", "**/dist/**"],
+  matcher: "picomatch",
+  debug: false,
+  writeConflictSidecar: false,
+  loggerConfig: {
+    mode: "memory", // or "stream"
+    logDir: "logs",
+    levels: {
+      stdout: ["warn", "error"],
+      file: ["info", "warn", "error"],
+    },
+  },
+};
 ```
 
-This raises interesting questions/edge cases:
-
-- How to merge file-level vs. global rules?
-- Should `include/exclude` still apply if a file is explicitly listed?
-- Should conflicting rules between file + global fall back to default strategy or error?
-
-We welcome ideas & edge cases here!
-
 ## Supported Strategies
 
+- **merge** → deep merge objects/arrays where possible
 - **ours** → take current branch value
 - **theirs** → take incoming branch value
-- **manual** → mark for human resolution
-- **drop** → remove the key entirely
-- **custom** → user-defined resolver function
+- **base** → revert to common ancestor
+- **skip** → leave unresolved (creates conflict entry)
+- **drop** → remove the field entirely
+- **non-empty** → prefer non-empty value (ours > theirs > base)
+- **update** → update with theirs if field exists in ours
+- **concat** → concatenate arrays from both sides
+- **unique** → merge arrays and remove duplicates
+- **custom** → user-defined resolver functions
+
+### Strategy Priority
+
+- Strategies marked with `!` (important) are applied first
+- Multiple strategies can be specified as fallbacks
+- Custom strategies can be defined via `customStrategies` config
 
 ## Supported Formats
 
 - **JSON** (native)
-- **YAML, XML, TOML** → converted to JSON → resolved → converted back
+- **JSON5** → via `json5` peer dependency
+- **YAML** → via `yaml` peer dependency
+- **TOML** → via `smol-toml` peer dependency
+- **XML** → via `fast-xml-parser` peer dependency
+
+All non-JSON formats are converted to JSON → resolved → converted back to original format.
+
+## CLI Options
+
+```bash
+# File patterns
+--include "**/*.json,**/*.yaml"  # Comma-separated patterns
+--exclude "**/node_modules/**"   # Exclusion patterns
+
+# Matcher selection
+--matcher picomatch              # picomatch, micromatch, or custom
+
+# Debug and logging
+--debug                          # Enable verbose logging
+--sidecar                        # Write conflict sidecar files
+
+# Utilities
+--init                           # Create starter config file
+--restore .merge-backups         # Restore from backup directory
+```
 
-## Performance & Optimization
+## Architecture
 
-- **Matcher caching** for repeated patterns
-- **Streaming mode** for very large repos (low memory footprint)
-- Trade-offs are configurable via `optimize` field
+- **Modular design**: Separate concerns (parsing, merging, serialization)
+- **Reusable utilities**: Common merge logic extracted for maintainability
+- **Optimized bundle**: Constants over enums for better minification
+- **Comprehensive testing**: Full test coverage with vitest
+- **Type-safe**: Full TypeScript support with proper type inference
+
+## Advanced Features
+
+### Pattern Matching
+
+- **Exact paths**: `"package.json"`, `"src.config.database.host"`
+- **Field matching**: `"[version]"` → matches any `version` field
+- **Glob patterns**: `"dependencies.*"`, `"**.config.**"`
+- **Wildcards**: `"*.json"`, `"src/**/*.config.js"`
+
+### Custom Strategies
+
+```ts
+import { StrategyStatus } from "git-json-resolver";
+
+const config = {
+  customStrategies: {
+    "semantic-version": ({ ours, theirs }) => {
+      // Custom logic for semantic version resolution
+      if (isNewerVersion(theirs, ours)) {
+        return { status: StrategyStatus.OK, value: theirs };
+      }
+      return { status: StrategyStatus.CONTINUE };
+    },
+  },
+  rules: {
+    version: ["semantic-version", "theirs"],
+  },
+};
+```
 
-## Roadmap
+### Logging & Debugging
 
-- [ ] Richer strategies via plugins (e.g., semantic version resolver)
-- [ ] CLI UX improvements
-- [ ] Pluggable format converters customizations
-- [ ] VSCode integration for previewing merge resolutions
-- [ ] **Per-file strategies support** (current RFC)
+- **Memory mode**: Fast, in-memory logging
+- **Stream mode**: File-based logging for large operations
+- **Per-file logs**: Separate log files for each processed file
+- **Debug mode**: Detailed conflict information and strategy traces
 
 ## Contributing
 

lib/src/cli.ts

@@ -7,6 +7,7 @@ import { resolveConflicts } from "./index";
 import type { Config } from "./types";
 import { DEFAULT_CONFIG } from "./normalizer";
 import { restoreBackups } from "./utils";
+import { resolveGitMergeFiles } from "./merge-processor";
 
 const CONFIG_FILENAME = "git-json-resolver.config.js";
 
@@ -66,15 +67,32 @@ module.exports = ${JSON.stringify(DEFAULT_CONFIG, null, 2)};
  */
 export const parseArgs = (
   argv: string[],
-): { overrides: Partial<Config>; init?: boolean; restore?: string } => {
+): {
+  overrides: Partial<Config>;
+  init?: boolean;
+  restore?: string;
+  gitMergeFiles?: [string, string, string];
+} => {
   const overrides: Partial<Config> = {};
   let init = false;
   let restore: string | undefined;
+  let gitMergeFiles: [string, string, string] | undefined;
+
+  // Check for Git merge driver mode (3 positional arguments)
+  const positionalArgs = argv.slice(2).filter(arg => !arg.startsWith("--"));
+  if (positionalArgs.length === 3) {
+    gitMergeFiles = [positionalArgs[0], positionalArgs[1], positionalArgs[2]];
+  }
 
   for (let i = 2; i < argv.length; i++) {
     const arg = argv[i];
     const next = argv[i + 1];
 
+    // Skip positional arguments in Git merge mode
+    if (gitMergeFiles && !arg.startsWith("--")) {
+      continue;
+    }
+
     switch (arg) {
       case "--include":
         overrides.include = next?.split(",") ?? [];
@@ -107,12 +125,12 @@ export const parseArgs = (
         }
     }
   }
-  return { overrides, init, restore };
+  return { overrides, init, restore, gitMergeFiles };
 };
 
 (async () => {
   try {
-    const { overrides, init, restore } = parseArgs(process.argv);
+    const { overrides, init, restore, gitMergeFiles } = parseArgs(process.argv);
 
     if (init) {
       initConfig(process.cwd());
@@ -131,6 +149,14 @@ export const parseArgs = (
       process.exit(0);
     }
 
+    // Git merge driver mode: handle 3-way merge
+    if (gitMergeFiles) {
+      const [oursPath, basePath, theirsPath] = gitMergeFiles;
+      await resolveGitMergeFiles(oursPath, basePath, theirsPath, finalConfig);
+      return; // resolveGitMergeFiles handles process.exit
+    }
+
+    // Standard mode: process files with conflict markers
     await resolveConflicts(finalConfig);
   } catch (err) {
     console.error("Failed:", err);

lib/src/conflict-helper.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from "vitest";
-import { DROP } from "./merger";
 import { reconstructConflict } from "./conflict-helper";
+import { DROP } from "./utils";
 
 // Mock serializer to keep things deterministic
 vi.mock("./file-serializer", () => ({

lib/src/conflict-helper.ts

@@ -1,5 +1,5 @@
 import { serialize } from "./file-serializer";
-import { DROP } from "./merger";
+import { DROP } from "./utils";
 
 /** Remove DROP, replace undefined with conflict markers */
 const preprocessForConflicts = (node: any, path: string, conflicts: string[] = []): any => {