Settings

Package settings are accessed via Main Menu or Command Palette.

Syntax, User, Project and View Settings

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 found in the GitGutter.sublime-settings need to be prefixed using git_gutter_ to do that. Each of those settings overrides the value from the GitGutter.sublime-settings.

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

General

Enable or Disable Evaluation

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

Git Binary

"git_binary": ""

GitGutter looks for the git binary in the PATH environment variable by default.

The setting can be used to

1. specify the path to a custom git installation which is not registered to PATH.
2. run git via Windows Subsystem for Linux (WSL) on Windows 10 by setting up a unix like path.

The value may be either a direct string to a git binary:

Windows

"git_binary": "E:\\Portable\\git\\bin\\git.exe"

Linux/OSX/WSL

"git_binary": "/usr/bin/git"

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",
    "osx":  "/usr/bin/git",
    "windows": "C:/Program Files/Git/cmd/git.exe"
}

Environment Variables

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

Compare Against

"compare_against": "HEAD"

GitGutter compares the content of the view against the HEAD of the checked out branch by default. To change this default behaviour the compare_against setting can be changed to any tag, branch or commit hash git understands.

Diff Algorithm

"diff_algorithm": "patience"

Set diff_algorithm to one of the following values to change this behaviour.

Ignore Whitespace

"ignore_whitespace": "none"

GitGutter includes all whitespace when evaluating modifications by default. Set ignore_whitespace to one of the following values to change this behaviour.

Diff Gutter

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.

Live Mode

"live_mode": true

GitGutter evaluates changes every time the file is modified by default. Set false to disable evaluation after each input.

Protected Regions

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.

"protected_regions": [
    "sublimelinter-warning-gutter-marks",
    "sublimelinter-error-gutter-marks",
    "bookmarks"
],

Show Markers on 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.

Show Markers in 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.

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 following themes:

• Bars.gitgutter-theme
• Bars Thin.gitgutter-theme
• Default.gitgutter-theme
• Default HiDPI.gitgutter-theme (for ST2 and old ST3 dev builds)

Diff Popup

ⓘ requires Sublime Text 3 Build 3124+ and mdpopups 2.0.0+

Enable Hover

"enable_hover_diff_popup": true

GitGutter shows a diff popup, when hovering over changes in the gutter. Set false to disable the hovering feature.

Default Mode

"diff_popup_default_mode": "default"

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.

Protected Regions

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

Stylesheet

The default style of the Diff Popup is defined by mdpopups´s default.css and GitGutter´s gitgutter_popup.css. Both try their best to adapt the popup´s apeareance to the active color scheme automatically.

The apeareance can be customized by

1. an embedded stylesheet in the color scheme
2. editing the Packages/User/mdpopups.css
3. editing the Packages/User/gitgutter_popup.css

Syntax Highlighting

The popup uses the mdpopups library to render its content, which includes syntax highlighting.

Please refer to mdpopups settings documentation for settings to change this behaviour.

Line Annotation

The active line of the active view is annotated with information about who changed it when. Its behaviour and the look & feel can be modified with the following settings.

Show Line Annotation

"show_line_annotation": "auto"

ⓘ requires Sublime Text 3 Build 3124+

GitGutter displays information about the author of a change right next to the line using a phantom text if word wrapping is disabled. The behaviour can be modified by setting show_line_annotation to one of the following values:

Line Annotation Template

"line_annotation_text": "{{line_author}} ({{line_author_age}}) · {{line_summary}}"

The Line Annotation is rendered by jinja2 using a fully customizable template from the line_annotation_text setting.

"line_annotation_text": [
    "{{line_author}}",
    " ({{line_author_age}})",
    " · {{line_summary}}"
]

The following variables can be used to customize the template:

Line Annotation Ruler

"line_annotation_ruler": false

The Line Annotation is aligned to the end of a line with a predefined distance by default. To align the Line Annotation to the first ruler instead, you can set line_annotation_ruler to 1. A value of 2 aligns the text to the second ruler if available and so forth.

Line Annotation Ignore Whitespace

"line_annotation_ignore_whitespace": false

Line annotations display any change including whitespace by default. Set to true to ignore whitespace when comparing the parent’s version and the child’s to find where the lines came from.

Status Bar Text

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": [
    "{% if repo and branch %}",
        "{% if not st_git_status %}",
            "{{repo}}/{{branch}}",
            "{% if added_files + deleted_files + modified_files > 0 %}*{% endif %}, ",
        "{% endif %}",
        "{% if compare not in ('HEAD', branch, None) %}Comparing against {{compare}}, {% endif %}",
        "{% if state %}File is {{state}}{% endif %}",
        "{% if deleted > 0 %}, {{deleted}}-{% endif %}",
        "{% if inserted > 0 %}, {{inserted}}+{% endif %}",
        "{% if modified > 0 %}, {{modified}}≠{% endif %}",
        "{% if line_author and line_author_age %}, ⟢ {{line_author}} ({{line_author_age}}){% endif %}",
    "{% 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.

The following variables can be used to customize the template: