settings - nixvim docs

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:

<nixvim/plugins/by-name/gitsigns>

plugins.gitsigns.settings.auto_attach

Automatically attach to files.

Type: null or boolean or raw lua code

Default: null

Plugin default: true

Declared by:

<nixvim/plugins/by-name/gitsigns>

plugins.gitsigns.settings.base

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

Type: null or string

Default: null

Declared by:

<nixvim/plugins/by-name/gitsigns>

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))

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:

<nixvim/plugins/by-name/gitsigns>

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:

<nixvim/plugins/by-name/gitsigns>

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:

<nixvim/plugins/by-name/gitsigns>

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:

<nixvim/plugins/by-name/gitsigns>

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:

<nixvim/plugins/by-name/gitsigns>

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:

<nixvim/plugins/by-name/gitsigns>

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:

<nixvim/plugins/by-name/gitsigns>

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:

<nixvim/plugins/by-name/gitsigns>

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:

<nixvim/plugins/by-name/gitsigns>

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))

Default: null

Plugin default:

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

Declared by:

<nixvim/plugins/by-name/gitsigns>

plugins.gitsigns.settings.show_deleted

Show the old version of hunks inline in the buffer (via virtual lines).

Note: Virtual lines currently use the highlight GitSignsDeleteVirtLn.

Type: null or boolean or raw lua code

Default: null

Plugin default: false

Declared by:

<nixvim/plugins/by-name/gitsigns>

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:

<nixvim/plugins/by-name/gitsigns>

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:

<nixvim/plugins/by-name/gitsigns>

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: