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
Entries
Available Menus
Adding to Submenus
Customization

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 and Variables

Sublime Merge has 14 menus that may be customized. Menus have context variables that may be used in in the "caption" and "args" fields.

Available Variables

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

Available Menus

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 Section.sublime-menu

Context menu for the Branches header in the Locations tab

Branch Folder.sublime-menu

Context menu for branch folders in the Locations tab

Context variables:

$branch: The branch folder name
$ref: The partial branch folder ref

Branch.sublime-menu

Context menu for branches in the Locations and Commits tab

Context variables:

$branch: The branch name
$ref: The branch ref

Commit.sublime-menu

Context menu for commits in the Commits tab

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

Hunk.sublime-menu

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

Context variables:

$path: Repo-relative file path for the hunk

Unmerged File.sublime-menu

Context menu for an unmerged file in the Files tab

$path: Repo-relative file path

Untracked File.sublime-menu

Context menu for an untracked in the Files tab

$path: Repo-relative file path

Modified File.sublime-menu

Context menu for a modified file in the Files tab

$path: Repo-relative file path

Index File.sublime-menu

Context menu for a staged file in the Files tab

$path: Repo-relative file path

Remote Section.sublime-menu

Context menu for the Remotes header in the Locations tab

Remote.sublime-menu

Context menu for remotes in the Locations tab

Context variables:

$remote: The remote name

Remote Branch Folder.sublime-menu

Context menu for remote branch folders in the Locations tab

Context variables:

$branch: The remote branch folder name
$ref: The partial remote branch folder ref

Remote Branch.sublime-menu

Context menu for remote branches in the Locations and Commits tab

Context variables:

$branch: The remote branch name
$ref: The remote branch ref

Stash Section.sublime-menu

Context menu for the Stashes header in the Locations tab

Stash.sublime-menu

Context menu for stashes in the Locations and Commits tab

Context variables:

$stash: The stash index

Submodule Section.sublime-menu

Menu for gear icon to the right of the Submodules header in the Locations tab

Submodule.sublime-menu

Context menu for submodules in the Locations tab

Context variables:

$submodule_name: The submodule name
$submodule_path: The submodule path

Tag Section.sublime-menu

Context menu for the Tags header in the Locations tab

Tag.sublime-menu

Context menu for tags in the Locations tab

Context variables:

$tag_name: The tag name
$ref: The tag ref

Remote Tag.sublime-menu

Context menu for tags dedicated to remote commands. This menu is enabled for each remote, regardless of if the tag is present on the remote.

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.

If you're unsure where the Packages/User/ directory is, you can easily access it in Sublime Merge via Preferences Browse Packages…

Example

To customize the context menu for remotes in the Locations tab, 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"]}
    }
]