Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

plugins.gitsigns.settings

Options provided to the require('gitsigns').setup function.

Type: attribute set of anything

Default: { }

Example:

{
  current_line_blame = false;
  current_line_blame_opts = {
    virt_text = true;
    virt_text_pos = "eol";
  };
  signcolumn = true;
  signs = {
    add = {
      text = "│";
    };
    change = {
      text = "│";
    };
    changedelete = {
      text = "~";
    };
    delete = {
      text = "_";
    };
    topdelete = {
      text = "‾";
    };
    untracked = {
      text = "┆";
    };
  };
  watch_gitdir = {
    follow_files = true;
  };
}

Declared by:

plugins.gitsigns.settings.attach_to_untracked

Attach to untracked files.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.gitsigns.settings.auto_attach

Automatically attach to files.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.gitsigns.settings.base

The object/revision to diff against. See |gitsigns-revision|.

Type: null or string

Default: null

Declared by:

plugins.gitsigns.settings.count_chars

The count characters used when signs.*.show_count is enabled. The + entry is used as a fallback. With the default, any count outside of 1-9 uses the > character in the sign.

Possible use cases for this field:

  • to specify unicode characters for the counts instead of 1-9.
  • to define characters to be used for counts greater than 9.

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

Default: null

Plugin default:

{
  "+" = ">";
  __unkeyed_1 = "1";
  __unkeyed_2 = "2";
  __unkeyed_3 = "3";
  __unkeyed_4 = "4";
  __unkeyed_5 = "5";
  __unkeyed_6 = "6";
  __unkeyed_7 = "7";
  __unkeyed_8 = "8";
  __unkeyed_9 = "9";
}

Declared by:

plugins.gitsigns.settings.current_line_blame

Adds an unobtrusive and customisable blame annotation at the end of the current line. The highlight group used for the text is GitSignsCurrentLineBlame.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

plugins.gitsigns.settings.current_line_blame_formatter

String or function used to format the virtual text of current_line_blame.

When a string, accepts the following format specifiers:

  • <abbrev_sha>
  • <orig_lnum>
  • <final_lnum>
  • <author>
  • <author_mail>
  • <author_time> or <author_time:FORMAT>
  • <author_tz>
  • <committer>
  • <committer_mail>
  • <committer_time> or <committer_time:FORMAT>
  • <committer_tz>
  • <summary>
  • <previous>
  • <filename>

For <author_time:FORMAT> and <committer_time:FORMAT>, FORMAT can be any valid date format that is accepted by os.date() with the addition of %R (defaults to %Y-%m-%d):

  • %a abbreviated weekday name (e.g., Wed)
  • %A full weekday name (e.g., Wednesday)
  • %b abbreviated month name (e.g., Sep)
  • %B full month name (e.g., September)
  • %c date and time (e.g., 09/16/98 23:48:10)
  • %d day of the month (16) [01-31]
  • %H hour, using a 24-hour clock (23) [00-23]
  • %I hour, using a 12-hour clock (11) [01-12]
  • %M minute (48) [00-59]
  • %m month (09) [01-12]
  • %p either “am” or “pm” (pm)
  • %S second (10) [00-61]
  • %w weekday (3) [0-6 = Sunday-Saturday]
  • %x date (e.g., 09/16/98)
  • %X time (e.g., 23:48:10)
  • %Y full year (1998)
  • %y two-digit year (98) [00-99]
  • %% the character `%´
  • %R relative (e.g., 4 months ago)

When a function:

Parameters:

  • {name} Git user name returned from git config user.name

  • {blame_info} Table with the following keys:

    • abbrev_sha: string
    • orig_lnum: integer
    • final_lnum: integer
    • author: string
    • author_mail: string
    • author_time: integer
    • author_tz: string
    • committer: string
    • committer_mail: string
    • committer_time: integer
    • committer_tz: string
    • summary: string
    • previous: string
    • filename: string
    • boundary: true?

Note that the keys map onto the output of: git blame --line-porcelain

Return: The result of this function is passed directly to the opts.virt_text field of |nvim_buf_set_extmark| and thus must be a list of [text, highlight] tuples.

Type: null or string or raw lua code

Default: null

Plugin default: " <author>, <author_time> - <summary> "

Declared by:

plugins.gitsigns.settings.current_line_blame_formatter_nc

String or function used to format the virtual text of |gitsigns-config-current_line_blame| for lines that aren’t committed.

See |gitsigns-config-current_line_blame_formatter| for more information.

Type: null or string or raw lua code

Default: null

Plugin default: " <author>"

Declared by:

plugins.gitsigns.settings.debug_mode

Enables debug logging and makes the following functions available: dump_cache, debug_messages, clear_debug.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

plugins.gitsigns.settings.linehl

Enable/disable line highlights.

When enabled the highlights defined in signs.*.linehl are used. If the highlight group does not exist, then it is automatically defined and linked to the corresponding highlight group in signs.*.hl.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

plugins.gitsigns.settings.max_file_length

Max file length (in lines) to attach to.

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

Default: null

Plugin default: 40000

Declared by:

plugins.gitsigns.settings.numhl

Enable/disable line number highlights.

When enabled the highlights defined in signs.*.numhl are used. If the highlight group does not exist, then it is automatically defined and linked to the corresponding highlight group in signs.*.hl.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

plugins.gitsigns.settings.on_attach

Callback called when attaching to a buffer. Mainly used to setup keymaps when config.keymaps is empty. The buffer number is passed as the first argument.

This callback can return false to prevent attaching to the buffer.

Example:

  function(bufnr)
    if vim.api.nvim_buf_get_name(bufnr):match(<PATTERN>) then
      -- Don't attach to specific buffers whose name matches a pattern
      return false
    end
    -- Setup keymaps
    vim.api.nvim_buf_set_keymap(bufnr, 'n', 'hs', '<cmd>lua require"gitsigns".stage_hunk()<CR>', {})
    ... -- More keymaps
  end

Type: null or lua code string

Default: null

Declared by:

plugins.gitsigns.settings.preview_config

Option overrides for the Gitsigns preview window. Table is passed directly to nvim_open_win.

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

Default: null

Plugin default:

{
  border = "single";
  col = 1;
  relative = "cursor";
  row = 0;
  style = "minimal";
}

Declared by:

plugins.gitsigns.settings.sign_priority

Priority to use for signs.

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

Default: null

Plugin default: 6

Declared by:

plugins.gitsigns.settings.signcolumn

Enable/disable symbols in the sign column.

When enabled the highlights defined in signs.*.hl and symbols defined in signs.*.text are used.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

plugins.gitsigns.settings.status_formatter

Function used to format b:gitsigns_status.

Type: null or lua function string

Default: null

Plugin default:

''
  function(status)
    local added, changed, removed = status.added, status.changed, status.removed
    local status_txt = {}
    if added and added > 0 then
      table.insert(status_txt, '+' .. added)
    end
    if changed and changed > 0 then
      table.insert(status_txt, '~' .. changed)
    end
    if removed and removed > 0 then
      table.insert(status_txt, '-' .. removed)
    end
    return table.concat(status_txt, ' ')
  end
''

Declared by:

plugins.gitsigns.settings.trouble

When using setqflist() or setloclist(), open Trouble instead of the quickfix/location list window.

Default: pcall(require, 'trouble')

Type: null or boolean

Default: null

Declared by:

plugins.gitsigns.settings.update_debounce

Debounce time for updates (in milliseconds).

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

Default: null

Plugin default: 100

Declared by:

plugins.gitsigns.settings.word_diff

Highlight intra-line word differences in the buffer. Requires config.diff_opts.internal = true.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by: