Documentation Menus

Menus in Sublime Merge are defined by files ending in .sublime-menu. Menus use JSON, with the top-level structure being an array. Each binding is a JSON object containing information to define the text of the menu entry and what action it should perform.

Example

The following is an example of the format of a .sublime-menu file.

[
    {
        "caption": "File",
        "mnemonic": "F",
        "id": "file",
        "children":
        [
            { "command": "new_window", "caption": "New Window" },
            { "command": "close_window", "caption": "Close Window" },
            { "caption": "-", "id": "exit" },
            { "command": "exit", "caption": "Exit", "mnemonic": "x", "platform": "Windows" },
            { "command": "exit", "caption": "Quit", "mnemonic": "Q", "platform": "Linux" },
        ]
    }
]

Entries

Each menu entry is a JSON object with one or more keys. The list of supported keys includes:

"caption"
The text of the menu entry
"mnemonic"
The character to use as the key to press to activate the entry. Only applies to Windows and Linux. Must match the case of the character in the "caption".
"command"
A string of the command to execute when the entry is activated
"args"
A JSON object of args to send to the command
"children"
A JSON array of entries to create a submenu from
"id"
A unique string for the menu entry. Used for menu entries with "children" to allow adding additional child entries.
"platform"
One of the strings: "OSX", "!OSX", "Windows", "!Windows", "Linux" or "!Linux". Controls what platforms the entry is shown on.

Each menu entry requires at minimum, the key "caption" for a non-functionality entry, or "command" for an entry that performs an action.

Available Menus

Sublime Merge has 14 menus that may be customized. Menus have context variables that may be used in in the "caption" and "args" fields. The following context variables are available in all menus:

$working_dir
The path to the repo working dir
$git_dir
The path to git dir, i.e. .git/
$commit
The full hash of the selected commit
$short_commit
The short hash of the selected commit
$head
The branch name or commit hash of the head
$head_ref
The branch name or HEAD, when in detached head state

The menus that support customization are:

Main.sublime-menu
Primary menu for the application
Action.sublime-menu
Menu for ... button to the right of Search in the toolbar
Advanced Commit.sublime-menu
Menu for down arrow button to the right of the Commit button
Branch.sublime-menu

Context menu for branches in the Location Bar.

Context variables:

$branch
The branch name
$ref
The branch ref
Commit.sublime-menu

Context menu for commits in the Commit List

Context variables:

$commit
The full commit hash
$short_commit
The short commit hash
Diff Context.sublime-menu

Context menu for diff controls

Context variables:

$path
Repo-relative file path
$line
The line of the selection
$col
The column of the selection
File Mode Context.sublime-menu
Context menu for changes to a file's permissions
File.sublime-menu

Menu for ... button to the right edge of a file header.

Context variables:

$path
Repo-relative file path
Remote Branch.sublime-menu

Context menu for remote branches in the Location Bar

Context variables:

$branch
The remote branch name
$ref
The remote branch ref
Remote.sublime-menu

Context menu for remotes in the Location Bar

Context variables:

$remote
The remote name
Stash.sublime-menu

Additional context menu entries for stashes in the Commit List

Context variables:

$stash
The stash index
Submodule Section.sublime-menu
Menu for gear icon to the right of the Submodules header in the Location Bar
Submodule.sublime-menu

Context menu for submodules in the Location Bar

Context variables:

$submodule_name
The submodule name
$submodule_path
The submodule path
Tag.sublime-menu

Context menu for tags in the Location Bar

Context variables:

$tag_name
The tag name
$ref
The tag ref
Widget Context.sublime-menu
Context menu for text inputs in various panels. Technically this file name can be changed via the "context_menu" setting inside of Widget.sublime-settings.

Adding to Submenus

Using the "id" key of an entry, it is possible to add entries to submenus. When adding submenu entries, specify only the "id" and "children" keys of the parent entry, and set the value of "children" to an array of entries to append to the submenu.

For example, to add an entry to run git gc to the Repository menu, create an entry such as:

[
    {
        "id": "repository",
        "children":
        [
            {
                "caption": "Cleanup Repo",
                "command": "git",
                "args": {"argv": ["gc"]}
            }
        ]
    }
]

To find the "id" of entries, please see the file Main.sublime-menu in the package Default.sublime-package. See the Packages documentation for information on where to find the package and view the contents.

Customization

Users can customize the available menus by creating an appropriately-named file in their Packages/User/ directory.

For example, to customize the context menu for remotes in the Location Bar, create a file named Packages/User/Remote.sublime-menu. Adding the following would create an entry that will prune stale refs.

[
    {
        "caption": "Prune",
        "command": "git",
        "args": {"argv": ["remote", "prune", "$remote"]}
    }
]