ctrl+shift+p filters: :st2 :st3 :win :osx :linux
Browse

Git​Gutter

by jisaacks ST2/ST3 Top 25

A Sublime Text 2/3 plugin to see git diff in gutter

Details

Installs

  • Total 451K
  • Win 148K
  • OS X 186K
  • Linux 117K
Mar 23 Mar 22 Mar 21 Mar 20 Mar 19 Mar 18 Mar 17 Mar 16 Mar 15 Mar 14 Mar 13 Mar 12 Mar 11 Mar 10 Mar 9 Mar 8 Mar 7 Mar 6 Mar 5 Mar 4 Mar 3 Mar 2 Mar 1 Feb 28 Feb 27 Feb 26 Feb 25 Feb 24 Feb 23 Feb 22 Feb 21 Feb 20 Feb 19 Feb 18 Feb 17 Feb 16 Feb 15 Feb 14 Feb 13 Feb 12 Feb 11 Feb 10 Feb 9 Feb 8 Feb 7 Feb 6
Windows 138 249 227 200 140 146 225 207 212 254 239 137 136 257 235 260 277 266 155 156 223 246 264 223 172 140 151 221 236 256 246 264 155 159 203 250 235 244 232 145 158 251 256 221 259 255
OS X 139 238 213 223 103 97 214 246 212 243 283 101 136 189 232 257 239 268 113 130 226 247 258 238 234 128 129 195 247 208 221 194 128 134 218 230 204 245 266 134 116 190 215 242 257 237
Linux 90 188 161 167 88 111 163 172 176 173 166 119 90 177 159 193 183 201 92 82 153 170 158 126 188 102 97 144 125 177 155 177 104 93 159 165 209 187 172 107 107 157 188 189 202 184

Readme

Source
raw.​githubusercontent.​com

Git Gutter

A Sublime Text 2/3 plug-in to show information about files in a git repository.

Main Features
  1. Gutter Icons indicating inserted, modified or deleted lines
  2. Diff Popup with details about modified lines
  3. Status Bar Text with information about file and repository
  4. Jumping Between Changes to easily navigate between modified lines

screenshot

Icon Description
inserted inserted line
changed modified line
deleted deleted region borders
ignored ignored file
untracked untracked file

💾 Installation

Package Control

It is highly recommended to install GitGutter with Package Control as it automatically installs required dependencies and keeps all packages up to date.

  1. Install Package Control if you haven't yet.
  2. Open the command palette (Ctrl+Shift+P for Windows/Linux, Cmd+Shift+P for Mac)
  3. Search for Package Control: Install Package and hit Enter.
  4. Type GitGutter and press Enter to install it.
Pre-Releases

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"
],
GitGutter-Edge

The GitGutter-Edge package is replaced by Pre-Releases.

This change was made …

  1. to avoid issues with functions which depend on the package name.
  2. because branch based packages are deprecated by Package Control.
  3. 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.

Manual Installation

You can clone this repository into your Sublime Text x/Packages

OSX
cd ~/Library/Application\ Support/Sublime\ Text\ 2/Packages/
git clone git://github.com/jisaacks/GitGutter.git
Linux
cd ~/.config/sublime-text-2/Packages
git clone git://github.com/jisaacks/GitGutter.git
Windows
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.

Dependencies

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 OSX you might need to install the package SublimeFixMacPath.

👉 To manually install pull from the linked repos into ST's Packages folder.

🔫 Troubleshooting

The most common reason for the icons to not show up is likely a problem with GitGutter finding the git executable on your PATH). Please read the section on the git_binary setting for how to fix that.

🚀 Advanced Features

Diff Popup

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.

popups require Sublime Text 3 Build 3070+

mouse hover feature requires Sublime Text 3 Build 3116+

diff_popup_screenshot

symbol meaning of the symbol
× close the popup
jump to first change
jump to previous change
jump to next change
≈, ≉ enable/disable difference highlighting
copy the content of the git state
revert changes to the state in git

Comparing against different commits/branches/tags

GitGutter compares the working copy against the HEAD by default. This behavior can be changed through the command palette.

The following options are available:

  • Compare against HEAD
  • Compare against particular branch
  • Compare against particular tag
  • Compare against specific commit
  • Compare against specific file commit (current file's history)
  • Compare against origin

To change the compare option:

  1. Open the command palette (Ctrl+Shift+P for Windows/Linux, Cmd+Shift+P for Mac)
  2. Start typing GitGutter: Compare against
  3. You'll see the 5 options listed above, select one with the keyboard and press Enter.
  4. Choose the branch/tag/commit to compare against.

👉 The changes apply temporarily to the whole repository.

Jumping Between Changes

There are commands to jump between modifications. The default key bindings for these commands are:

OS X Windows / Linux Description
Cmd+Shift+Option+k Ctrl+Shift+Alt+k Previous
Cmd+Shift+Option+j Ctrl+Shift+Alt+j Next

⚙ Settings

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.

Debounce Delay

"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

"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

"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.

Hover Diff Popup

"enable_hover_diff_popup": true

requires Sublime Text 3 Build 3116+

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

"diff_popup_default_mode": "default"

requires Sublime Text 3 Build 3070+

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.

Diff Popup Appearance

requires Sublime Text 3 Build 3070+

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.

Untracked Files

"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.

Minimap

"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 path

"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.

Protected Regions

"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

"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 Template

"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
{{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

Themes

"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 2 themes:

  • 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 <ThemName>.gitgutter-theme must exist to mark this folder a resource for GitGutter icons.

Per-project Settings

Sublime Text supports project-specific settings, allowing live_mode to be enabled or disabled for certain repositories. To make use of this feature just open Project > Edit Project menu and add the settings key as shown.

{
    "folders":
    [
        {
            "path": "src"
        }
    ],
    "settings":
    {
        "live_mode": false
    }
}

🖌 Icon Coloring

The colors come from your color scheme .tmTheme file.

Required Color Scheme Entries

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>

Supported Color Schemes

Color schemes that already have support for GitGutter include:

⮱ Alternatives

Check out the collection of GitGutter(ish) packages for various editors