Commands Reference

Creating and Switching Repositories

Git: Init

Initializes a git repository in a specified directory.

An input panel will be shown in the bottom of the Sublime Text window, allowing you to edit the directory which will be initialized as a git repository. After choosing the directory, press enter to complete. To abort, press esc.

If the directory does not already exist, you will be asked if you want to create it. If the path already exists, but it is not a directory, or if it is a directory and already contains git repository, the command will exit with an error message.

Note

The initial suggestion for the directory is calculated in the following way:

  1. The first open folder, if any.
  2. The directory name of the currently active file, if any.
  3. The directory name of the first open file which has a filename, if any.
  4. The user directory of the currently logged in user.
Git: Switch Repo

Switch the active repository for the current Sublime Text window.

In SublimeGit, each window has an active repository. The first time you execute a git command, SublimeGit will try to find out which repository should be the active one for the current window. If there are multiple possible repositories, you will be presented with a list to choose from. Your selection will then be set as the active repository for the window.

If you generally only have one folder open per window in Sublime Text and don’t use git submodules, then you probably won’t have to switch repositories manually. However, there are some situations where it can be necessary to do so:

Nested git repositories
If you are using git submodules, or some kind of package manager which uses git checkouts in a subfolder of your project to hold packages (such as Composer for PHP), and you want to explicitly specify that you are working inside the nested repository.
Multiple folders or files
If you have multiple folders or multiple files, which are managed with git, open in the same Sublime Text window, and you want to switch the repository that you are currently working on.

Note

How does SublimeGit find my repositories?

Excellent question. SublimeGit will try it’s best to guess which repository you are working on. In general it works something like this:

  • Find the currently active file.
    • Is it a git view? Use that repository.
    • Is any of the parents a git repository? Use that.
  • If that fails, find the currently active window.
    • Find a list of all possible directories:
      • The directories of any open folders.
      • The directories of any open files.
    • Generate a list of all of the parents of these directories.
    • Check to see if any of the directories or their parents are git repositories.
  • Select a repository:
    • If there is only one repository then use that.
    • If there are more than one repository, present a list to choose from.

Status

Git: Status

Documentation coming soon.

Git: Quick Status

Show an abbreviated status in the quick bar.

As an alternative to the full status window, a list of changed files is presented the quick bar. Next to each filename there is an abbreviation, denoting the files status.

This status contains 2 characters, X and Y. For paths with merge conflicts, X and Y show the modification states of each side of the merge. For paths that do not have merge conflicts, X shows the status of the index, and Y shows the status of the work tree.

The statuses are as follows:

  • ‘ ‘ = unmodified
  • M = modified
  • A = added
  • D = deleted
  • R = renamed
  • C = copied
  • U = updated but unmerged
  • ? = untracked

Selecting an entry in the list will bring up a diff view of the file.

Diffs

Git: Diff

Shows a diff of the entire repository in a diff view.

This diff is between the worktree and the index. Thus, these are the changes that you could ask git to add to the next commit.

For diff on a single file, either use the Git: Quick Status command, or press d when the cursor is on a file in the status view.

Git: Diff Cached

Shows the cached diff for the entire repository in a diff view.

The difference between this command and the Git: Diff command is that this command shows the difference between the staged changes (the changes in the index), and the HEAD. I.e. these are changes which you could tell git to unstage.

For diff on a single file, either use the Git: Quick Status command, or press d when the cursor is on a file in the status view.

Blame

Git: Blame

Run git blame on the current file.

This will bring up a new window with the blame information to the left of the file contents, on a per-line basis. Lines which are selected when executing the commands will be marked with a dot in the gutter. When placing the cursor on a line, the summary of the commit will be shown in the status bar.

If the file has not been saved to the filesystem, or the file is not tracked by git, it’s not possible to blame, and an error will be shown.

To navigate further into the blame information, a couple of keyboard shortcuts are available:

  • enter: Show the commit in a new window (like Git: Show).
  • b: Open a new blame starting at the given commit.

Note

These keyboard shortcuts support multiple selection, so you can potentially open a lot of tabs. If your action will open more than 5 tabs, you will get a warning asking if you want to continue. You can turn this warning off with the git_blame_warn_multiple_tabs setting.

Settings:
  • git_blame_warn_multiple_tabs – If set to true, SublimeGit will give you a warning when your action from a blame view will open more than 5 tabs. Set to false to turn this warning off.

Adding files

Git: Quick Add

Adds one or more files to the staging area by selecting them from the quick bar.

A list of modified files are presented in the quickbar. Each file is marked with a letter, indicating it’s status:

  • M = modified
  • A = added
  • D = deleted
  • R = renamed
  • C = copied
  • ? = untracked

To add a file from the list, either click the file with the mouse, or use arrow up/arrow down or searching until you have the file you are looking for, and then press enter. After adding a file, the status list will update, allowing you to select another file to add. To dismiss the status list, press esc.

When there are no more files to add, the status list will show the usual git message for a clean working dir. To dismiss the list press enter or esc.

There are two special options at the bottom of the status list. To go to them quickly, press arrow up which will select the bottom-most option. These options are:

+ All unstaged files
This option will add all changes to files git already knows about (all the files not marked with ?).
+ All files
This option will add all changes to files git already knows about, as well as all new files (files marked with ?).
Git: Add Current File

This command adds the currently open file to the git staging area. It the –force switch, so the file will be added even if it matches a repository .gitignore pattern, or a global .gitignore pattern.

The file must have already been saved, otherwise it won’t exist on the filesystem, and can’t be added to git.

If the command completes successfully, no output will be given.

Checking out files

Git: Checkout Current File

Documentation coming soon.

Committing

Git: Quick Commit

Quickly commit changes with a one-line commit message.

If there are any staged changes, only those changes will be added. If there are no staged changes, any changed files that git know about will be added in the commit.

If the working directory is clean, an error will be shown indicating it.

After entering the commit message, press enter to commit, or esc to cancel. An empty commit message will also result in the commit being cancelled.

Git: Quick Commit Current File

Documentation coming soon.

Git: Commit

Documentation coming soon.

Git: Amend Commit

Documentation coming soon.

Logs

Git: Log

Documentation coming soon.

Git: Quick Log

Documentation coming soon.

Git: Quick Log Current File

Documentation coming soon.

Git: Show

Documentation coming soon.

Branching and Merging

Git: Checkout

Check out an existing branch.

This command allows you to select a branch from the quick bar to check out. The currently active branch (if any) is marked with an asterisk (*) to the left of its name.

Git: Checkout Commit

Check out a specific commit.

This command allows you to check out a specific commit. The list of commits will be presented in the quick bar, containing the first line of the commit message, the abbreviated sha1, as well as a relative and absolute date in the local timezone.

After checkout, you will be in a detached head state.

Git: Checkout New Branch

Create a new branch from the current HEAD and switch to it.

This command will show an input panel allowing you to name your new branch. After giving the branch a name, pressing enter will create the new branch and check it out. Pressing esc will cancel.

If a branch with the given name already exists, you will be asked if you want to overwrite the branch. Selecting cancel will exit silently, without making any changes.

Git: Merge

Documentation coming soon.

Working with Remotes

Git: Add Remote

Add a named git remote at a given URL

You will be asked to provide the name and url of the remote (see below). Press enter to select the value. If you want to cancel, press esc.

After completion, the Git: Remote command will be run, to allow for further management of remotes.

Name:
The name of the remote. By convention, the name origin is used for the “main” remote. Therefore, if your repository does not have any remotes, the initial suggestion for the name will be origin.
Url:
The git url of the remote repository, in any format that git understands.
Git: Remote

Manage git remotes

Presents s list of remotes, including their push and pull urls. Select the remote to perform an action on it. After an action has been performed, the list will show up again to allow for further editing of remotes. To cancel, press esc.

Available actions:

Show

Show information about the remote. This includes the push and pull urls, the current HEAD, the branches tracked, and the local branches which are set up for push and pull.

The result will be displayed in a panel in the bottom of the Sublime Text window.

Rename
Rename the selected remote. An input field will appear allowing you to write a new name for the remote. If a new name is not provided, or esc is pressed, the action will be aborted.
Remove
Remove the selected remote. All remote-tracking branches, and configuration for the remote is removed. You will be asked for confirmation before removing the remote.
Set URL
Change the URL for the selected remote. An input fiels will appear allowing you to specify a new URL. The given URL will be used for both the push and pull URL. If a new URL isn’t specified, or esc is pressed, the URL will not be updated.
Prune
Delete all stale remote-tracking branches for the selected remote. Any remote-tracking branches in the local repository which are no longer in the remote repository will be removed.

Fetching and Pulling

Git: Fetch

Fetches git objects from the remote repository

If there is only one remote configured, this remove will be used for fetching. If there are multiple remotes, you will be asked to select the remote to fetch from.

Git: Pull

Documentation coming soon.

Git: Pull Current Branch

Documentation coming soon.

Pushing

Git: Push

Documentation coming soon.

Git: Push Current Branch

Push the current branch to a remote

This is the command to use if you are pushing a branch to a remote for the first time, or to a different remote than the configured upstream. Will push the current branch to a specified branch on the selected remote, creating the remote branch if it doesn’t already exist.

If there is only one remote configured, that will be used, otherwise you will be asked to select a remote. If there are no remotes, you will be asked to add one.

You will be asked to supply a name to use for the branch on the remote. By default, the current branch name will be suggested.

Warning

Trying to push when in a detached head state will give an error message. This is not generally something you want to do.

Note

This command shares a lot of similarities with the excellent git-publish command, which can be found at https://github.com/gavinbeatty/git-publish.

Stashing

Git: Stash

Documentation coming soon.

Git: Pop Stash

Documentation coming soon.

Git: Apply Stash

Documentation coming soon.

Git: Snapshot

Documentation coming soon.

Tags

Git: Tag

Documentation coming soon.

Git: Add Tag

Documentation coming soon.

Custom Commands

Git: Custom Command

Execute a custom git command.

By default, this command will be run synchronously, and the output will be presented in a new view, with a title corresponding to the command.

However, it’s also possible to use this command to build your own SublimeGit commands.

It takes 3 arguments:

  • cmd: The command to execute (without the initial “git”)
  • async: true to run asynchronously, false otherwise. Default: false
  • output: "view" for a new buffer, "panel" for an output panel, null for no output. Default: "view"
  • syntax: If output is set to "view", the new buffer will get this syntax file. Should be a name along the
    lines of Packages/Python/Python.tmLanguage. To see the current syntax for a view, execute view.settings().get('syntax') from the console.

Note

See Custom Commands for more information on how to create your own SublimeGit commands.

Browsing Documentation

Git: Help

Search through installed Git documentation.

Every standard install of git contains a full set of manual pages in both text and html formats. This commands presents a list of available documentation in a quick bar to allow for easy access.

When a document has been selected, a webbrowser will be opened to show the help file. To abort the list without opening the document, press esc.

Settings:
  • git_help_fancy_list – If set to true, SublimeGit will try to parse the help document to show a nicer list containing a small excerpt from each document. This has a small performance cost the first time the list is generated. Set to false to fall back to simple format. Default: true
  • git_help_html_path – If set to a directory, SublimeGit will look in the given directory for git help files. Set to null to make SublimeGit auto-detect the location of the help files.

Note

To find the location the installed documentation, you can execute:

$ git --html-path
/usr/local/Cellar/git/1.7.11.3/share/doc/git-doc
Git: Version

Shows the version of git which is installed

This corresponds to running:

$ git --version
git version 1.7.11.3

SublimeGit

SublimeGit: Version

Show the currently installed version of SublimeGit.

SublimeGit: Documentation

Open a webbrowser to the online SublimeGit documentation.

Gitk

Gitk

Documentation coming soon.