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

package/README.md

@@ -1,65 +1,144 @@
 # Salesforce Metadata Git Merge Driver
 
-[![License](https://img.shields.io/badge/License-MIT-blue)]()
-[![Compatibility](https://img.shields.io/badge/Windows%20%7C%20Mac%20%7C%20Linux-Supported-success)]()
+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.
 
-An intelligent Git merge driver specifically designed for Salesforce metadata files. **Eliminates hours** of manual merge conflicts resolution.
+## Features
 
-![Demo GIF](./docs/media/demo-sf-git-merge-driver.gif)
+- 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
 
-## Why use this plugin?
+## Installation
 
-- **Saves time**: No more manual XML conflict resolution
-- **Zero-config**: Works immediately after installation
-- **Reliable**: Understands Salesforce metadata structure
-- **Transparent**: Seamless Git workflow integration
+```bash
+sf plugins install sf-git-merge-driver
+```
+
+## Usage
 
-## How it works
+<!-- 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)
 
-```mermaid
-sequenceDiagram
-    participant Dev
-    participant Git
-    participant MergeDriver
+## `sf git merge driver install`
+
+Installs a local git merge driver for the given org and branch.
 
-    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)
 ```
+USAGE
+  $ sf git merge driver install [--json] [--flags-dir <value>]
 
-## Installation (30 seconds)
+GLOBAL FLAGS
+  --flags-dir=<value>  Import flag values from a directory.
+  --json               Format output as json.
 
-```bash
-# Install plugin (one time, global)
-sf plugins install sf-git-merge-driver
+DESCRIPTION
+  Installs a local git merge driver for the given org and branch.
+
+  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.
 
-# Configure merge driver in your project (one time, local per project)
-cd my/sf/project
-sf git merge driver install
+EXAMPLES
+  Install the driver for a given project:
+
+    $ sf git merge driver install
 ```
 
-## Usage
+_See code: [src/commands/git/merge/driver/install.ts](https://github.com/scolladon/sf-git-merge-driver/blob/v1.2.1/src/commands/git/merge/driver/install.ts)_
 
-The merge driver activates **automatically** for conflicts on:
-- [Full list of supported metadata](#configuration)
+## `sf git merge driver run`
 
-**No additional steps required!** Works during normal Git operations:
-```bash
-git pull  # Conflicts resolved automatically
-git merge # Same here
+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
 ```
 
+_See code: [src/commands/git/merge/driver/run.ts](https://github.com/scolladon/sf-git-merge-driver/blob/v1.2.1/src/commands/git/merge/driver/run.ts)_
+
+## `sf git merge driver uninstall`
+
+Uninstalls the local git merge driver for the given org and branch.
+
+```
+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.
+
+EXAMPLES
+  Uninstall the driver for a given project:
+
+    $ sf git merge driver uninstall
+```
+
+_See code: [src/commands/git/merge/driver/uninstall.ts](https://github.com/scolladon/sf-git-merge-driver/blob/v1.2.1/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
 
-Configured for these metadata files by default:
-```gitattributes
-*.profile-meta.xml merge=salesforce-source
-*.permissionset-meta.xml merge=salesforce-source
+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
+*.profile-meta.xml merge=salesforce-source
+*.permissionset-meta.xml merge=salesforce-source
 *.applicationVisibility-meta.xml merge=salesforce-source
 *.classAccess-meta.xml merge=salesforce-source
 *.customMetadataTypeAccess-meta.xml merge=salesforce-source
@@ -105,7 +184,7 @@ Configured for these metadata files by default:
 *.objectTranslation-meta.xml merge=salesforce-source
 ```
 
-## Troubleshooting
+## Debugging
 
 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.
@@ -125,6 +204,7 @@ GIT_TRACE=true
 git merge ...
 ```
 
+
 ## Changelog
 
 [changelog.md](CHANGELOG.md) is available for consultation.
@@ -140,7 +220,7 @@ Versioning follows [SemVer](http://semver.org/) specification.
 
 ## Contributing
 
-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**.
+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**.
 
 See [contributing.md](CONTRIBUTING.md) for sgd contribution principles.