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, pressesc
.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:
- The first open folder, if any.
- The directory name of the currently active file, if any.
- The directory name of the first open file which has a filename, if any.
- 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.
- Find a list of all possible directories:
- 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 tofalse
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, pressesc
.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
oresc
.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.
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, pressesc
.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.
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, executeview.settings().get('syntax')
from the console.
- syntax: If output is set to
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 tofalse
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_help_fancy_list – If set to
-
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.