sf-git-merge-driver 1.2.0 → 1.2.1-dev-137.18569178375-1

package/README.md

@@ -1,144 +1,65 @@
 # Salesforce Metadata Git Merge Driver
 
-A custom Git merge driver designed specifically for Salesforce metadata files. This tool helps resolve merge conflicts in Salesforce XML metadata files by understanding their structure and intelligently merging changes.
+[![License](https://img.shields.io/badge/License-MIT-blue)]()
+[![Compatibility](https://img.shields.io/badge/Windows%20%7C%20Mac%20%7C%20Linux-Supported-success)]()
 
-## Features
+An intelligent Git merge driver specifically designed for Salesforce metadata files. **Eliminates hours** of manual merge conflicts resolution.
 
-- Intelligent merging of Salesforce XML metadata files
-- Handles complex metadata structures like arrays with unique identifiers
-- Supports both local and global installation
-- Easy to use with SFDX CLI plugin commands
-- Warning: as of now it does not preserve the order of items that are order dependant like valuesets
+![Demo GIF](./docs/media/demo-sf-git-merge-driver.gif)
 
-## Installation
+## Why use this plugin?
 
-```bash
-sf plugins install sf-git-merge-driver
-```
-
-## Usage
-
-<!-- commands -->
-* [`sf git merge driver install`](#sf-git-merge-driver-install)
-* [`sf git merge driver run`](#sf-git-merge-driver-run)
-* [`sf git merge driver uninstall`](#sf-git-merge-driver-uninstall)
-
-## `sf git merge driver install`
-
-Installs a local git merge driver for the given org and branch.
-
-```
-USAGE
-  $ sf git merge driver install [--json] [--flags-dir <value>]
-
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
-
-DESCRIPTION
-  Installs a local git merge driver for the given org and branch.
+- **Saves time**: No more manual XML conflict resolution
+- **Zero-config**: Works immediately after installation
+- **Reliable**: Understands Salesforce metadata structure
+- **Transparent**: Seamless Git workflow integration
 
-  Installs a local git merge driver for the given org and branch, by updating the `.git/info/attributes` files in the
-  project, creating a new merge driver configuration in the `.git/config` of the project, and installing the binary in
-  the node_modules/.bin directory.
+## How it works
 
-EXAMPLES
-  Install the driver for a given project:
-
-    $ sf git merge driver install
-```
+```mermaid
+sequenceDiagram
+    participant Dev
+    participant Git
+    participant MergeDriver
 
-_See code: [src/commands/git/merge/driver/install.ts](https://github.com/scolladon/sf-git-merge-driver/blob/v1.2.0/src/commands/git/merge/driver/install.ts)_
-
-## `sf git merge driver run`
-
-Runs the merge driver for the specified files.
-
-```
-USAGE
-  $ sf git merge driver run -O <value> -A <value> -B <value> -P <value> [--json] [--flags-dir <value>] [-L <value>] [-S
-    <value>] [-X <value>] [-Y <value>]
-
-FLAGS
-  -A, --local-file=<value>             (required) path to our version of the file
-  -B, --other-file=<value>             (required) path to their version of the file
-  -L, --conflict-marker-size=<value>   [default: 7] number of characters to show for conflict markers
-  -O, --ancestor-file=<value>          (required) path to the common ancestor version of the file
-  -P, --output-file=<value>            (required) path to the file where the merged content will be written
-  -S, --ancestor-conflict-tag=<value>  [default: BASE] string used to tag ancestor version in conflicts
-  -X, --local-conflict-tag=<value>     [default: LOCAL] string used to tag local version in conflicts
-  -Y, --other-conflict-tag=<value>     [default: REMOTE] string used to tag other version in conflicts
-
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
-
-DESCRIPTION
-  Runs the merge driver for the specified files.
-
-  Runs the merge driver for the specified files, handling the merge conflict resolution using Salesforce-specific merge
-  strategies. This command is typically called automatically by Git when a merge conflict is detected.
-
-EXAMPLES
-  Run the merge driver for conflicting files:
-
-    $ sf git merge driver run --ancestor-file=<value> --local-file=<value> --other-file=<value> \
-      --output-file=<value>
-
-  Where:
-  - ancestor-file is the path to the common ancestor version of the file
-  - local-file is the path to our version of the file
-  - other-file is the path to their version of the file
-  - output-file is the path to the file where the merged content will be written
+    Dev->>Git: git merge
+    Git->>MergeDriver: Detects XML conflict
+    MergeDriver->>MergeDriver: Analyzes metadata structure
+    MergeDriver->>MergeDriver: Smart merging
+    MergeDriver->>Git: Returns merged result
+    Git->>Dev: Clean commit (no conflicts)
 ```
 
-_See code: [src/commands/git/merge/driver/run.ts](https://github.com/scolladon/sf-git-merge-driver/blob/v1.2.0/src/commands/git/merge/driver/run.ts)_
+## Installation (30 seconds)
 
-## `sf git merge driver uninstall`
-
-Uninstalls the local git merge driver for the given org and branch.
+```bash
+# Install plugin (one time, global)
+sf plugins install sf-git-merge-driver
 
+# Configure merge driver in your project (one time, local per project)
+cd my/sf/project
+sf git merge driver install
 ```
-USAGE
-  $ sf git merge driver uninstall [--json] [--flags-dir <value>]
-
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
-
-DESCRIPTION
-  Uninstalls the local git merge driver for the given org and branch.
 
-  Uninstalls the local git merge driver for the given org and branch, by removing the merge driver content in the
-  `.git/info/attributes` files in the project, deleting the merge driver configuration from the `.git/config` of the
-  project, and removing the installed binary from the node_modules/.bin directory.
+## Usage
 
-EXAMPLES
-  Uninstall the driver for a given project:
+The merge driver activates **automatically** for conflicts on:
+- [Full list of supported metadata](#configuration)
 
-    $ sf git merge driver uninstall
+**No additional steps required!** Works during normal Git operations:
+```bash
+git pull  # Conflicts resolved automatically
+git merge # Same here
 ```
 
-_See code: [src/commands/git/merge/driver/uninstall.ts](https://github.com/scolladon/sf-git-merge-driver/blob/v1.2.0/src/commands/git/merge/driver/uninstall.ts)_
-<!-- commandsstop -->
-
-## How It Works
-
-The merge driver works by:
-1. Converting XML to JSON for easier processing
-2. Using a specialized three-way merge algorithm that understands Salesforce metadata structures
-3. Intelligently resolving conflicts based on metadata type
-4. Converting the merged result back to properly formatted XML
-
 ## Configuration
 
-The driver is configured to work with `.xml` files by default. The installation adds the following to the `.git/info/attributes` file (so it is discrete for the current repo):
-
-```
-*.labels-meta.xml merge=salesforce-source
-*.label-meta.xml merge=salesforce-source
+Configured for these metadata files by default:
+```gitattributes
 *.profile-meta.xml merge=salesforce-source
 *.permissionset-meta.xml merge=salesforce-source
+*.labels-meta.xml merge=salesforce-source
+*.label-meta.xml merge=salesforce-source
 *.applicationVisibility-meta.xml merge=salesforce-source
 *.classAccess-meta.xml merge=salesforce-source
 *.customMetadataTypeAccess-meta.xml merge=salesforce-source
@@ -184,7 +105,7 @@ The driver is configured to work with `.xml` files by default. The installation
 *.objectTranslation-meta.xml merge=salesforce-source
 ```
 
-## Debugging
+## Troubleshooting
 
 The plugin uses the [Salesforce CLI logging system](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_log_messages.htm) to log information.
 You can control the logging level by setting the `SF_LOG_LEVEL` environment variable.
@@ -204,7 +125,6 @@ GIT_TRACE=true
 git merge ...
 ```
 
-
 ## Changelog
 
 [changelog.md](CHANGELOG.md) is available for consultation.
@@ -220,7 +140,7 @@ Versioning follows [SemVer](http://semver.org/) specification.
 
 ## Contributing
 
-Contributions are what make the trailblazer community such an amazing place. I regard this component as a way to inspire and learn from others. Any contributions you make are **appreciated**.
+Contributions are what make the trailblazer community such an amazing place. We regard this component as a way to inspire and learn from others. Any contributions you make are **appreciated**.
 
 See [contributing.md](CONTRIBUTING.md) for sgd contribution principles.
 

package/lib/service/installService.js

@@ -10,7 +10,6 @@ export class InstallService {
         const git = simpleGit();
         await git.addConfig(`merge.${DRIVER_NAME}.name`, 'Salesforce source merge driver');
         await git.addConfig(`merge.${DRIVER_NAME}.driver`, `sh -c '${RUN_PLUGIN_COMMAND} -O "$1" -A "$2" -B "$3" -P "$4" -L "$5" -X "$6" -Y "$7"' -- %O %A %B %P %L %X %Y`);
-        await git.addConfig(`merge.${DRIVER_NAME}.recursive`, 'true');
         // Configure merge driver for each metadata type pattern
         const patterns = METADATA_TYPES_PATTERNS.map(pattern => `*.${pattern}-meta.xml merge=${DRIVER_NAME}`).join('\n');
         const content = `${patterns}\n`;

package/lib/service/installService.js.map

@@ -1 +1 @@
-{"version":3,"file":"installService.js","sourceRoot":"","sources":["../../src/service/installService.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAA;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,EAAE,GAAG,EAAE,MAAM,8BAA8B,CAAA;AAElD,MAAM,OAAO,cAAc;IAEZ,AAAN,KAAK,CAAC,kBAAkB;QAC7B,MAAM,GAAG,GAAG,SAAS,EAAE,CAAA;QACvB,MAAM,GAAG,CAAC,SAAS,CACjB,SAAS,WAAW,OAAO,EAC3B,gCAAgC,CACjC,CAAA;QACD,MAAM,GAAG,CAAC,SAAS,CACjB,SAAS,WAAW,SAAS,EAC7B,UAAU,kBAAkB,mFAAmF,CAChH,CAAA;QACD,MAAM,GAAG,CAAC,SAAS,CAAC,SAAS,WAAW,YAAY,EAAE,MAAM,CAAC,CAAA;QAE7D,wDAAwD;QACxD,MAAM,QAAQ,GAAG,uBAAuB,CAAC,GAAG,CAC1C,OAAO,CAAC,EAAE,CAAC,KAAK,OAAO,mBAAmB,WAAW,EAAE,CACxD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACZ,MAAM,OAAO,GAAG,GAAG,QAAQ,IAAI,CAAA;QAE/B,MAAM,iBAAiB,GAAG,MAAM,oBAAoB,EAAE,CAAA;QAEtD,MAAM,UAAU,CAAC,iBAAiB,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAA;IAC7D,CAAC;CACF;AAtBc;IADZ,GAAG;wDAsBH"}
+{"version":3,"file":"installService.js","sourceRoot":"","sources":["../../src/service/installService.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAA;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,EAAE,GAAG,EAAE,MAAM,8BAA8B,CAAA;AAElD,MAAM,OAAO,cAAc;IAEZ,AAAN,KAAK,CAAC,kBAAkB;QAC7B,MAAM,GAAG,GAAG,SAAS,EAAE,CAAA;QACvB,MAAM,GAAG,CAAC,SAAS,CACjB,SAAS,WAAW,OAAO,EAC3B,gCAAgC,CACjC,CAAA;QACD,MAAM,GAAG,CAAC,SAAS,CACjB,SAAS,WAAW,SAAS,EAC7B,UAAU,kBAAkB,mFAAmF,CAChH,CAAA;QAED,wDAAwD;QACxD,MAAM,QAAQ,GAAG,uBAAuB,CAAC,GAAG,CAC1C,OAAO,CAAC,EAAE,CAAC,KAAK,OAAO,mBAAmB,WAAW,EAAE,CACxD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACZ,MAAM,OAAO,GAAG,GAAG,QAAQ,IAAI,CAAA;QAE/B,MAAM,iBAAiB,GAAG,MAAM,oBAAoB,EAAE,CAAA;QAEtD,MAAM,UAAU,CAAC,iBAAiB,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAA;IAC7D,CAAC;CACF;AArBc;IADZ,GAAG;wDAqBH"}