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
• Using Selectors
• Available Selectors
• Using Selectors in Menu Files

Using Selectors

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

This is where selectors come in handy. Selectors allow us to select arguments when the command is run, rather than hard-coding them into the command.

Available Selectors

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

$select_ref

Allows the user to select a ref (either a local branch, a remote branch, or a tag)

$select_branch

Allows the user to select a branch (either a local or remote branch)

$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.

Using Selectors in Menu Files

Note that selectors rely on the command palette to collect input. Any commands placed in the Default.sublime-commands will be visible in the command palette. This is not the case for context menus, which run commands directly.

For any custom commands defined in a context menu file such as Branch.sublime-menu, you'll need to wrap the custom command in a show_command_palette command to collect input. As an example:

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