Sublimerge Pro (2.x) documentation

Custom Comparisons

Sublimerge comes with a few predefined Custom Comparisons for Git, SVN and Mercurial users. Their implementation is stored in Preferences > Package Settings > Sublimerge > Custom Comparisons - Default. Custom Comparisons can be used for various scenarios and are not limited to Version Control Systems only. You can, for example, define one to compare local files with remote ones via (S)FTP.

All user-defined commands should be defined in Custom Comparisons - User file to prevent them from being overridden each time Sublimerge is upgraded.
For complete list of available directives, properties and variables, please take a look at Custom Comparisons - Default file.

Predefined

  • Show Uncommited Changes... - Git, Subversion and Mercurial
  • Compare to Other Branch... - Git only
  • Compare to Named Branch... - Mercurial only
  • Show Unpushed Changes... - Git only
  • Show Changes Between Current and Remote... - Git only

For their description, please take a look at Tutorial/Comparing Versioned Files.

Example

The code below is a working example from predefined ones.

{
    //Comparison name
    "name": "Show Uncommited Changes...",
    //What VCS does it require. Currently 'git', 'svn', 'hg' or null (if doesn't require any of VCS)
    "requires": "git",
    //Comparison is divided into steps. You can define more steps when needed.
    "steps": [
        {
            //Displays a Quick Panel (list) with given items
            "quick_panel": {
                //Quick Panel name. Used to populate a variable 'modified_file' with seleted item value
                "name": "modified_file",
                //Data source
                "source": {
                    //Execute a shell command
                    "execute": {
                        //Command/shell script to be executed
                        "command": "{git} status --porcelain --untracked-files=no",
                        //Set working directory
                        "directory": "{sublimerge:repo_root}"
                    },
                    //Single item extractor
                    "item": {
                        //Regular expression to parse each output line
                        "regexp": "^\\s+M\\s+(.*)$",
                        //Caption can be an array or string.
                        //@n - placeholder for regular expression matching group
                        "caption": ["@1"],
                        //Value must be a single string
                        "value": "@1"
                    },
                    //Message to be displayed when data source is empty (when no items were created)
                    "empty_message": "There are no uncommited changes."
                }
            }
        },
        {
            //Define variables for later use
            "define": {
                "head_file": "{sublimerge:temp_dir}/{modified_file|basename}@HEAD",
                "local_file": "{sublimerge:repo_root}/{modified_file}"
            }
        },
        {
            //Compare files
            "compare": {
                //Execute a shell command.
                //Please note the 'modified_file' variable which we defined in previous step
                "execute": {
                    //Command/shell script to be executed - prints output to file
                    "command": "{git} show HEAD:\"./{modified_file}\" > \"{head_file}\",
                    //Set working directory
                    "directory": "{sublimerge:repo_root}"
                },
                //Left file
                "left": {
                    //Full path to file generated in `execute` block
                    "file": "{head_file}",
                    //Mark the file as temporary to be removed after use
                    "temporary": true
                },
                //Right file
                "right": {
                    //Full file path
                    "file": "{local_file}",
                    //This file is our working copy, so is not temporary - don't delete it after use
                    "temporary": false
                }
            }
        }
    ]
}
I serve cookies to improve your experience on this website. If you continue without changing your browser settings, I will assume that you accept the cookies. You can change your browser settings at any time.