Documentation Custom Commands

Before reading this section, take a look at the Command Palette documentation to learn how to add custom entries to the command palette.

Sublime Merge is designed to be customized. You can add your own custom Git commands to menus easily, and create more complex commands using custom selectors.

Basic Example

The following is an example of a basic custom git command that runs git rebase -i master.

{
    "caption": "Interactive rebase onto master",
    "command": "git",
    "args": {"argv": ["rebase", "-i", "master"]}
}

You can see that the args are specified in the "argv" array, each separated by a comma.

Using Selectors

The limitation with the example shown above is that master is hardcoded. What if we want to pick a branch to rebase onto?

This is where selectors come in handy. Selectors allow us to select a ref at runtime, rather than hard-coding a value.

Available Selectors

Sublime Merge supports the following selectors, which may be used with the git command:

$select_branch
Allows the user to select a branch (either local or remote)
$select_local_branch
Allows the user to select a local branch
$select_remote_branch
Allows the user to select a remote branch
$select_commit
Allows the user to select a commit (in the form of a commit hash)
$select_tag
Allows the user to select a tag
$select_stash
Allows the user to select a stash (in the form of a stash index)
$text
Allows the user to supply arbitrary text

If we wanted to update the previous example, we can do the following:

{
    "caption": "Interactive rebase…",
    "command": "git",
    "args": {"argv": ["rebase", "-i", "$select_branch"]}
}

Now the user will be prompted to select a branch to rebase onto.