A Sublime Text 2/3 plug-in to show information about files in a git repository.
- Gutter Icons indicating inserted, modified or deleted lines
- Diff Popup with details about modified lines
- Status Bar Text with information about file and repository
- Goto Change to easily navigate between modified lines
Icon | Description |
---|---|
![]() |
inserted line |
![]() |
modified line |
![]() |
deleted region borders |
![]() |
ignored file |
![]() |
untracked file |
It is highly recommended to install GitGutter with Package Control as it automatically installs required dependencies and keeps all packages up to date.
- Install Package Control if you haven't yet.
- Open the command palette (Ctrl+Shift+P for Windows/Linux, Cmd+Shift+P for Mac OS)
- Search for Package Control: Install Package and hit Enter.
- Type
GitGutter
and press Enter to install it.
If you are interested in testing bleeding edge features you can set up Package Control to install pre-releases by adding GitGutter to install_prereleases
key in the Package Control.sublime-settings
.
"install_prereleases":
[
"GitGutter"
],
The GitGutter-Edge package is replaced by Pre-Releases.
This change was made ...
- to avoid issues with functions which depend on the package name.
- because branch based packages are deprecated by Package Control.
- to have more control about when to publish new features for testing.
๐ If you don't want to wait for Pre-Releases you can pull from master branch directly.
You can clone this repository into your Sublime Text x/Packages
cd ~/Library/Application\ Support/Sublime\ Text\ 2/Packages/
git clone git://github.com/jisaacks/GitGutter.git
cd ~/.config/sublime-text-2/Packages
git clone git://github.com/jisaacks/GitGutter.git
cd "%APPDATA%\Sublime Text 2\Packages"
git clone git://github.com/jisaacks/GitGutter.git
๐ The git
command must be available on the command line.
๐ You may need to add the directory containing git.exe
to your PATH
environment variable.
Some functions of GitGutter depend on the following external libraries to work properly. They are installed automatically for you by Package Control, so normally don't need to care about. But on setups without Package Control you need to make sure they are installed and available in the global namespace of Sublime Text's python interpreter on your own.
๐ On Mac OS you might need to install the package SublimeFixMacPath.
๐ To manually install pull from the linked repos into ST's Packages folder.
The most common reasons for the icons to not show up are:
- GitGutter can't find the
git
executable on PATH. - On Mac OS the "Xcode/iOS license" needs to be aggreed to make git work.
To check, whether git is found and working properly ...
- Open the command palette (Ctrl+Shift+P for Windows/Linux, Cmd+Shift+P for Mac OS)
- Search for GitGutter: Support Info and hit Enter.
An dialog is displayed with version information of Sublime Text and all packages being used by GitGutter.
If git was found on PATH and is working properly, the dialog contains a line like git version 2.10.0.windows.1. Otherwise some more detailed information about the reason for git not to work may be found in the console window, then. If not try again with "debug": true
added to the GitGutter settings.
Some operating systems (especially Mac OS) may not run Sublime Text within the login shell. As a result Sublime Text and all its packages don't have access to some of the user's environment variables including the PATH to git.
In some cases the package providing git, simply required some user confirmation due to license changes and thus simply refuses to run git.
With SublimeFixMacPath package Sublime Text loads the PATH environment from the login shell. If git is working there, it will be found by GitGutter, too, then.
GitGutter can work with a certain binary, too. Please read the section on the git_binary setting.
Please check if GitGutter works after restarting Sublime Text.
All modules of GitGutter were moved to modules
sub directory to present them to Sublime Text as one package to avoid creating multiple instances of some modules and objects and reduce package loading time by about 50%.
GitGutter handles Package Control's post_upgrade
event to reload all its submodules once after upgrading. In rare cases some modules might not be recovered properly and thus require a restart of ST to make GitGutter work again.
GitGutter is installed and loads properly without any error messages printed to Sublime Text's console, but keeps completely disabled in some or all repositories. Neither gutter icons nor messages are displayed in the status bar.
GitGutter is designed to keep quiet in the following situations when evaluation is expected useless:
- disabled in Preferences.sublime-settings, project settings or view settings (
"git_gutter_enabled": false
) - disabled in GitGutter.sublime-settings (
"enabled": false
) - the current view
- shows a file which is not part of a git working tree
- is not attached to a window
- is read only
- is a scratch view
- is a widget (
"is_widget": true
) - is a REPL view (
"repl": true
) - has "Hexadecimal" encoding
Please check if one of those states was applied to your view by one of your packages.
๐ With "debug": true
the reason for GitGutter to keep quite is printed to console.
๐ ConvertToUTF8 package is known to mark views as scratch during conversion without reverting that state reliably.
git 2.5+ allows configurations with .git directory not being located in the working tree root. You may also checkout multiple working trees from one repository. No matter which configuration is used, GitGutter expects a .git
directory or a .git
file in the root of a working tree to recognize it as such.
If the .git
directory is not located in the working tree root the following steps are required.
-
Configure the repository to point to the custom working tree by calling
git config --add core.worktree <path_to_worktree>
This step is required to let git use the custom working tree.
-
Create a
.git
file in the root of the working tree which points to the repository's database.โ The
.git
file must contain the linegitdir: <path_to_git_dir>
.The file can be created using the following shell commands.
Linux / Mac OS
echo "gitdir: $(git rev-parse --git-dir)" > .git
Windows
for /f %i in ('git rev-parse --git-dir') do set gitdir=%i echo gitdir: %gitdir% > .git
The diff popup appears by hovering the mouse over the gutter changes on Sublime Text 3 or can be called from command palette by GitGutter: Show Diff Popup
or via a key binding.
โ requires Sublime Text 3 Build 3124+ and mdpopups 2.0.0+
symbol | meaning of the symbol |
---|---|
ร | close the popup |
โค | goto to first change |
โ | goto to previous change |
โ | goto to next change |
โ, โ | enable/disable difference highlighting |
โ | copy the content of the git state |
โฒ | revert changes to the state in git |
The commands are used to quickly navigate between modifications. The default key bindings for these commands are:
OS X | Windows / Linux | Description |
---|---|---|
Cmd+Shift+Option+k | Ctrl+Shift+Alt+k | Goto Previous Change |
Cmd+Shift+Option+j | Ctrl+Shift+Alt+j | Goto Next Change |
The commands use "next_prev_change_wrap"
setting by default to decide whether to continue at document boundaries. This behavior and the step size can be customized by command arguments with values other then None
.
{ "command": "git_gutter_prev_change", "args": {"count": 2, "wrap": False} },
{ "command": "git_gutter_next_change", "args": {"count": 2, "wrap": False} }
arg | valid range | description |
---|---|---|
count | None, >=1 | number of iterations to find destination hunk |
wrap | None, False, True | enable/disable wrapping at document boundaries |
The command copies the committed content of the changed hunk under the first cursor to the clipboard. The default key binding for this command is:
OS X | Windows / Linux | Description |
---|---|---|
Cmd+Shift+c | Ctrl+Shift+c | Copy Content |
The command reverts the text under the first cursor to the state in git. The default key binding for this command is:
Mac OS | Windows / Linux | Description |
---|---|---|
Cmd+Shift+Option+z | Ctrl+Shift+Alt+z | Revert Change to Commit |
GitGutter compares the working copy against the HEAD by default.
To change the compare option:
- Open the command palette (Ctrl+Shift+P for Windows/Linux, Cmd+Shift+P for Mac OS)
- Start typing
GitGutter: Compare against
- Select one of the 6 options with the keyboard and press Enter.
- Choose the branch/tag/commit to compare against.
or just use one of the following key bindings:
Mac OS | Windows / Linux | Description |
---|---|---|
Cmd+Shift+Option+c, h | Ctrl+Shift+Alt+c, h | Compare against HEAD |
Cmd+Shift+Option+c, b | Ctrl+Shift+Alt+c, b | Compare against particular branch |
Cmd+Shift+Option+c, t | Ctrl+Shift+Alt+c, t | Compare against particular tag |
Cmd+Shift+Option+c, c | Ctrl+Shift+Alt+c, c | Compare against particular commit |
Cmd+Shift+Option+c, f | Ctrl+Shift+Alt+c, f | Compare against particular file commit (current file's history) |
Cmd+Shift+Option+c, o | Ctrl+Shift+Alt+c, o | Compare against particular origin (@{upstream}) |
๐ The changes apply temporarily to the whole repository.
Settings are accessed via the Preferences > Package Settings > GitGutter menu.
Default settings should not be modified, as they are overwritten when GitGutter updates. Copy the relevant settings into GitGutter's user settings file instead.
"enable": true
GitGutter evaluates changes every time the file is loaded, saved, activated or modified by default. Set false
to disable evaluation and hide all gutter icons, status message and minimap markers.
"debounce_delay": 1000
Delays update of gutter icons by the following amount (in milliseconds). Useful for performance issues. Default 1000 (1 second).
"focus_change_mode": true
GitGutter evaluates changes every time a view gets the focus by default. Set false
to disable evaluation when changing views.
๐ This setting has effect with "live_mode": false
only.
๐ GitGutter always evaluates changes after loading and saving a document.
"live_mode": true
GitGutter evaluates changes every time the file is modified by default. Set false
to disable evaluation after each input.
๐ GitGutter always evaluates changes after loading and saving a document.
"enable_hover_diff_popup": true
โ requires Sublime Text 3 Build 3124+ and mdpopups 2.0.0+
GitGutter shows a diff popup, when hovering over changes in the gutter. Set false
to disable this popup. You can still open it with a key binding and from the command palette.
"diff_popup_default_mode": "default"
โ requires Sublime Text 3 Build 3124+ and mdpopups 2.0.0+
The popup displays the previous state of the content under the cursor by "default"
but can be set to "diff"
to highlight the differences between the git state and the editor state.
โ requires Sublime Text 3 Build 3124+ and mdpopups 2.0.0+
The popup uses the mdpopups library and the corresponding settings are global and not only for GitGutter. Syntax highlighting can be set to match the active color scheme by adding "mdpopups.use_sublime_highlighter": true
to the User settings.
๐ Other settings can be found at mdpopups settings homepage.
๐ User style settings by adding a gitgutter_popup.css
the User directory.
๐ User style settings are accessible via the settings menu.
"diff_popup_protected_regions": [
"sublime_linter.protected_regions"
],
To avoid GitGutter's diff popup from figting with other popups while hovering the gutter a list of protected regions can be created. If the line under the mouse cursor is occupied by one of these regions, no diff popup is displayed.
๐ You will need to figure out the names of the regions to protect.
๐ You can still open the diff popup via key binding or command pallet.
"show_markers_on_untracked_file": true
GitGutter shows icons on each line for untracked and ignored files by default. Set to false
to hide those icons.
You may need to add scopes (markup.ignored.git_gutter
and markup.untracked.git_gutter
) to your color scheme to color the icons.
"show_in_minimap": 1
GitGutter shows diffs in the minimap on Sublime Text 3 by default. Change show_in_minimap
to one of the following values to disable this feature or change the width of the markers.
value | description |
---|---|
=0 | hide markers |
>1 | width of markers |
-1 | highlight full line |
"git_binary": ""
If git
is not found on PATH by GitGutter the git_binary
setting can be set to the location of the git binary. The value may be either a direct string to a git binary:
"git_binary": "E:\\Portable\\git\\bin\\git.exe"
or it may be a dictionary keyed off what sublime.platform() returns, so it may be customized on a per-platform basis:
"git_binary": {
"default": "",
"linux": "/usr/bin/git",
"windows": "C:/Program Files/Git/cmd/git.exe"
}
It is valid to use environment variables in the setting value, and they will be expanded appropriately.
In a POSIX environment you can run which git
to find the path to git if it is in your path. On Windows, you can use where git
to do the equivalent.
"env": {
"GIT_OPTIONAL_LOCKS": 0
}
With the "env"
dictionary custom environment variables can be passed to git. The values overwrite the global environment variables Sublime Text is running with.
๐ Keys with value None
are removed from the local environment.
๐ The "git_gutter_env"
defined per view or project hides the global "env"
dictionary.
๐ Make sure to use the correct separator characters of your OS, if you manipulate the $PATH
.
"diff_algorithm": "patience"
Set diff_algorithm
to one of the following values to change this behavior.
value | description |
---|---|
"default" | The basic greedy diff algorithm. Currently, this is the default. |
"minimal" | Spend extra time to make sure the smallest possible diff is produced. |
"patience" | Use "patience diff" algorithm when generating patches. |
"histogram" | This algorithm extends the patience algorithm to "support low-occurrence common elements". |
๐ The value determines which command line argument to pass to git diff
.
"ignore_whitespace": "none"
GitGutter includes all whitespace when evaluating modifications by default. Set ignore_whitespace
to one of the following values to change this behavior.
value | description |
---|---|
"none" | don't ignore any whitespace changes |
"eol" | ignore whitespace changes at the end of line |
"space" | ignore changed amount of whitespace |
"all" | ignore all whitespace |
๐ The value determines which command line argument to pass to git diff
.
"protected_regions": [
"sublimelinter-warning-gutter-marks",
"sublimelinter-error-gutter-marks",
"bookmarks"
],
To avoid GitGutter from overriding more important gutter icons a list of protected regions can be created, which GitGutter won't add gutter icons to.
๐ You will need to figure out the names of the regions to protect.
"show_status_bar_text": true
GitGutter displays status information about open files in the status bar by default. Set to false
to hide the information.
"status_bar_text": [
"In {{repo}} on {{branch}}",
"{% if compare != 'HEAD' %}, Comparing against {{compare}}{% endif %}",
", File is {{state}}",
"{% if deleted != 0 %}, {{deleted}}-{% endif %}",
"{% if inserted != 0 %}, {{inserted}}+{% endif %}",
"{% if modified != 0 %}, {{modified}}โ {% endif %}"
]
The Status Bar Text is rendered using a fully customizable template from status_bar_text
. The setting is organized as an array of strings for better readability. It is joined and then passed to jinja2.
GitGutter provides the following variables to be used in the template.
Variable | Description |
---|---|
{{repo}} | repository name / folder name containing the .git directory |
{{branch}} | checked out branch you are working on |
{{remote}} | tracked remote of current branch you are working on or None |
{{ahead}} | number of commits the local branch is ahead of remote |
{{behind}} | number of commits the local branch is behind remote |
{{added_files}} | number of untracked files added to working tree |
{{deleted_files}} | number of files deleted from working tree |
{{modified_files}} | number of modified files in the working tree |
{{staged_files}} | number of files in the staging area |
{{compare}} | commit/branch/HEAD the file is compared to |
{{state}} | One of committed/modified/ignored/untracked |
{{deleted}} | number of deleted regions |
{{inserted}} | number of inserted lines |
{{modified}} | number of modified lines |
"theme": "Default.gitgutter-theme"
GitGutter provides support for custom gutter icons and diff popup style sheets coming with theme packages. Set theme
to a valid theme file name to activate a different icon set.
GitGutter includes following themes:
- Bars.gitgutter-theme
- Bars Thin.gitgutter-theme
- Default.gitgutter-theme
- Default HiDPI.gitgutter-theme
To provide a custom theme developers need to add a folder with all required icons and an optional gitgutter_popup.css
file to their package. An empty JSON file <ThemeName>.gitgutter-theme
must exist to mark this folder a resource for GitGutter icons.
All GitGutter settings can be placed in any of Sublime Text's settings files to provide syntax-, user-, project- or view-specific setups.
The setting keys need to be prefixed using git_gutter_
to do that.
To modify GitGutter settings for an open Project just open Project > Edit Project menu and add the settings
key as shown.
{
"folders":
[
{
"path": "src"
}
],
"settings":
{
// git_binary is the only setting not being prefixed
"git_binary": "/path/to/project/specific/git"
// git_gutter settings
"git_gutter_live_mode": false,
"git_gutter_ignore_whitespace": "space"
}
}
๐ All correctly prefixed settings can be placed into Preferences.sublime-settings
instead of GitGutter.sublime-settings
.
๐ Settings can be modified temporarily per view by calls like view.settings().set("git_gutter_enable", False)
The colors come from your color scheme .tmTheme file.
If your color scheme file does not define the appropriate colors (or you want to edit them) add an entry that looks like this:
<dict>
<key>name</key>
<string>GitGutter deleted</string>
<key>scope</key>
<string>markup.deleted.git_gutter</string>
<key>settings</key>
<dict>
<key>foreground</key>
<string>#F92672</string>
</dict>
</dict>
<dict>
<key>name</key>
<string>GitGutter inserted</string>
<key>scope</key>
<string>markup.inserted.git_gutter</string>
<key>settings</key>
<dict>
<key>foreground</key>
<string>#A6E22E</string>
</dict>
</dict>
<dict>
<key>name</key>
<string>GitGutter changed</string>
<key>scope</key>
<string>markup.changed.git_gutter</string>
<key>settings</key>
<dict>
<key>foreground</key>
<string>#967EFB</string>
</dict>
</dict>
<dict>
<key>name</key>
<string>GitGutter ignored</string>
<key>scope</key>
<string>markup.ignored.git_gutter</string>
<key>settings</key>
<dict>
<key>foreground</key>
<string>#565656</string>
</dict>
</dict>
<dict>
<key>name</key>
<string>GitGutter untracked</string>
<key>scope</key>
<string>markup.untracked.git_gutter</string>
<key>settings</key>
<dict>
<key>foreground</key>
<string>#565656</string>
</dict>
</dict>
Color schemes that already have support for GitGutter include:
- Afterglow
- Baara Dark
- Boxy Theme
- Brackets Color Scheme
- Cobalt2
- Dark Room
- Deep Blue See
- Desert Night
- Flatland
- Fox
- Grandson of Obsidian
- Hitoshi
- Monokai Extended
- Monokai Pro
- Neon Color Scheme
- Neon
- Oblivion
- Perv
- Solarized Colour Theme
- Spacegray
- Specials Board
- Tomorrow Theme
- Underscore Colour Theme
- Wildlife
- Contact me if you want your color scheme listed here. Or do a pull request.
Check out the collection of GitGutter(ish) packages for various editors