plugins.gitgutter.settings

The configuration options for gitgutter without the gitgutter_ prefix.

For example, the following settings are equivialent to these :setglobal commands:

  • foo_bar = 1 -> :setglobal gitgutter_foo_bar=1
  • hello = "world" -> :setglobal gitgutter_hello="world"
  • some_toggle = true -> :setglobal gitgutter_some_toggle
  • other_toggle = false -> :setglobal nogitgutter_other_toggle

Type: attribute set of anything

Default: { }

Example:

{
  preview_win_floating = true;
  set_sign_backgrounds = true;
  sign_modified_removed = "*";
  sign_priority = 20;
}

Declared by:

plugins.gitgutter.settings.enabled

Controls whether or not the plugin is on at startup.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.gitgutter.settings.async

Controls whether or not diffs are run in the background.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.gitgutter.settings.close_preview_on_escape

Whether pressing <Esc> in a preview window closes it.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

plugins.gitgutter.settings.diff_args

Use this option to pass any extra arguments to git-diff.

Type: null or string or raw lua code

Default: null

Plugin default: ""

Example: "-w"

Declared by:

plugins.gitgutter.settings.diff_base

By default buffers are diffed against the index. Use this option to diff against a revision instead.

If you are looking at a previous version of a file with Fugitive (e.g. via :0Gclog), gitgutter sets the diff base to the parent of the current revision.

This setting is ignore when the diff is relative to the working tree (diff_relative_to).

Type: null or string or raw lua code

Default: null

Plugin default: ""

Example: ""

Declared by:

plugins.gitgutter.settings.diff_relative_to

By default buffers are diffed against the index. Use this option to diff against the working tree.

Type: null or string or raw lua code

Default: null

Plugin default: "index"

Example: "working_tree"

Declared by:

plugins.gitgutter.settings.floating_window_options

This dictionary is passed directly to |nvim_open_win()|.

Type: null or (attribute set of (anything or raw lua code))

Default: null

Plugin default:

{
  col = 0;
  height = "&previewheight";
  relative = "cursor";
  row = 1;
  style = "minimal";
  width = 42;
}

Declared by:

plugins.gitgutter.settings.git_args

Use this option to pass any extra arguments to git when running git-diff.

Type: null or string or raw lua code

Default: null

Plugin default: ""

Example: "--gitdir=\"\""

Declared by:

plugins.gitgutter.settings.git_executable

This option determines what git binary to use. Set this if git is not on your path.

Type: null or string or raw lua code

Default: null

Plugin default: "git"

Example: lib.getExe pkgs.git

Declared by:

plugins.gitgutter.settings.grep

The plugin pipes the output of git-diff into grep to minimise the amount of data vim has to process. Set this option if grep is not on your path.

grep must produce plain-text output without any ANSI escape codes or colours. Use this option to turn off colours if necessary (grep --color=never for example).

If you do not want to use grep at all (perhaps to debug why signs are not showing), set this option to an empty string.

Type: null or string or raw lua code

Default: null

Plugin default: "grep"

Example: "grep --color=never"

Declared by:

plugins.gitgutter.settings.highlight_linenrs

Determines whether or not to show line number highlights.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

plugins.gitgutter.settings.highlight_lines

Determines whether or not to show line highlights.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

plugins.gitgutter.settings.log

When switched on, the plugin logs to gitgutter.log in the directory where it is installed. Additionally it logs channel activity to channel.log.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

plugins.gitgutter.settings.map_keys

Controls whether or not the plugin provides mappings. See |gitgutter-mappings|.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.gitgutter.settings.max_signs

Sets the maximum number of signs to show in a buffer.

To avoid slowing down the GUI the number of signs can be capped. When the number of changed lines exceeds this value, the plugin removes all signs and displays a warning message.

When set to -1 the limit is not applied.

Type: null or signed integer or floating point number or raw lua code

Default: null

Plugin default: -1

Declared by:

plugins.gitgutter.settings.preview_win_floating

Whether to use floating/popup windows for hunk previews.

Note that if you use popup windows on Vim you will not be able to stage partial hunks via the preview window.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.gitgutter.settings.preview_win_location

This option determines where the preview window pops up as a result of the :GitGutterPreviewHunk command.

See the end of the |opening-window| docs.

Type: null or one of “bo”, “to”, “bel”, “abo” or raw lua code

Default: null

Plugin default: "bo"

Declared by:

plugins.gitgutter.settings.set_sign_backgrounds

Only applies to existing GitGutter* highlight groups. See |gitgutter-highlights|.

Controls whether to override the signs’ background colours to match the |hl-SignColumn|.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

plugins.gitgutter.settings.show_msg_on_hunk_jumping

When switched on, a message like “Hunk 4 of 11” is shown on hunk jumping.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.gitgutter.settings.sign_added

Icon for the added sign.

You can use unicode characters but not images. Signs must not take up more than 2 columns.

Type: null or string or raw lua code

Default: null

Plugin default: "+"

Declared by:

plugins.gitgutter.settings.sign_allow_clobber

Determines whether gitgutter preserves non-gitgutter signs. When true, gitgutter will not preserve non-gitgutter signs.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.gitgutter.settings.sign_modified

Icon for the modified sign.

You can use unicode characters but not images. Signs must not take up more than 2 columns.

Type: null or string or raw lua code

Default: null

Plugin default: "~"

Declared by:

plugins.gitgutter.settings.sign_modified_removed

Icon for the modified_removed sign.

You can use unicode characters but not images. Signs must not take up more than 2 columns.

Type: null or string or raw lua code

Default: null

Plugin default: "~_"

Declared by:

plugins.gitgutter.settings.sign_priority

Sets the |sign-priority| gitgutter assigns to its signs.

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Plugin default: 10

Declared by:

plugins.gitgutter.settings.sign_removed

Icon for the removed sign.

You can use unicode characters but not images. Signs must not take up more than 2 columns.

Type: null or string or raw lua code

Default: null

Plugin default: "_"

Declared by:

plugins.gitgutter.settings.sign_removed_above_and_below

Icon for the removed_above_and_below sign.

You can use unicode characters but not images. Signs must not take up more than 2 columns.

Type: null or string or raw lua code

Default: null

Plugin default: "_¯"

Declared by:

plugins.gitgutter.settings.sign_removed_first_line

Icon for the removed_first_line sign.

You can use unicode characters but not images. Signs must not take up more than 2 columns.

Type: null or string or raw lua code

Default: null

Plugin default: "‾"

Declared by:

plugins.gitgutter.settings.signs

Determines whether or not to show signs.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.gitgutter.settings.terminal_reports_focus

Normally the plugin uses |FocusGained| to force-update all buffers when Vim receives focus. However some terminals do not report focus events and so the |FocusGained| autocommand never fires.

If this applies to you, either install something like Terminus to make |FocusGained| work or set this option to false.

If you use tmux, try this in your tmux.conf:

set -g focus-events on

When this option is false, the plugin force-updates the buffer on |BufEnter| (instead of only updating if the buffer’s contents has changed since the last update).

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.gitgutter.settings.use_location_list

When switched on, the :GitGutterQuickFix command populates the location list of the current window instead of the global quickfix list.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by: