gitsigns.nvim/doc/gitsigns.txt

*gitsigns.txt* Gitsigns
*gitsigns.nvim*

Author:   Lewis Russell <lewis6991@gmail.com>
Homepage: <https://github.com/lewis6991/gitsigns.nvim>
License:  MIT license

==============================================================================
INTRODUCTION                                                        *gitsigns*

Gitsigns is a plugin for Neovim that provides integration with Git via a
feature set which includes (but not limited to):
  • Provides signs in the |signcolumn| to show changed/added/removed lines.
  • Mappings to operate on hunks to stage, undo or reset against Git's index.

Gitsigns is implemented entirely in Lua which is built into Neovim and because
of this requires no external dependencies. This is unlike other plugins that
require python, node, etc, which need to communicate with Neovim using |RPC|.

==============================================================================
USAGE                                                         *gitsigns-usage*

For basic setup with all batteries included:
>
    require('gitsigns').setup()
<

Configuration can be passed to the setup function. Here is an example with all
the default settings:
>
    require('gitsigns').setup {
      signs = {
        add          = {hl = 'DiffAdd'   , text = '│', numhl='GitSignsAddNr'},
        change       = {hl = 'DiffChange', text = '│', numhl='GitSignsChangeNr'},
        delete       = {hl = 'DiffDelete', text = '_', numhl='GitSignsDeleteNr'},
        topdelete    = {hl = 'DiffDelete', text = '‾', numhl='GitSignsDeleteNr'},
        changedelete = {hl = 'DiffChange', text = '~', numhl='GitSignsChangeNr'},
      },
      numhl = false,
      keymaps = {
        -- Default keymap options
        noremap = true,
        buffer = true,

        ['n ]c'] = { expr = true, "&diff ? ']c' : '<cmd>lua require\"gitsigns\".next_hunk()<CR>'"},
        ['n [c'] = { expr = true, "&diff ? '[c' : '<cmd>lua require\"gitsigns\".prev_hunk()<CR>'"},

        ['n <leader>hs'] = '<cmd>lua require"gitsigns".stage_hunk()<CR>',
        ['n <leader>hu'] = '<cmd>lua require"gitsigns".undo_stage_hunk()<CR>',
        ['n <leader>hr'] = '<cmd>lua require"gitsigns".reset_hunk()<CR>',
        ['n <leader>hp'] = '<cmd>lua require"gitsigns".preview_hunk()<CR>',
        ['n <leader>hb'] = '<cmd>lua require"gitsigns".blame_line()<CR>',
      },
      watch_index = {
        interval = 1000
      },
      sign_priority = 6,
      status_formatter = nil -- Use default
    }
<

==============================================================================
MAPPINGS                                                   *gitsigns-mappings*

All mappings are configurable via |gitsigns-setup()|.

Most actions can be repeated with `.` if you have |vim-repeat| installed.

Buffer ~
    ]c         Jump to the next hunk.
    [c         Jump to the previous hunk.
    <leader>hs Stage the hunk at the cursor position.
    <leader>hu Undo the last stage hunk.
    <leader>hr Reset the lines of the hunk to what is in Git's index.
    <leader>hp Preview the hunk in a floating window.

Custom mappings are defined using the `keymaps` table in the config table
passed to |gitsigns-setup()|. See |gitsigns-config-keymaps|.

==============================================================================
FUNCTIONS                                                 *gitsigns-functions*

setup({config})                                             *gitsigns.setup()*
                Setup and start Gitsigns.

                Parameters: ~
                    {config} Table object containing configuration for
                    Gitsigns. See |gitsigns-usage| for more details.

next_hunk({opts})                                           *gitsigns.next_hunk()*
                Jump to the next hunk in the current buffer. Respects
                |wrapscan|.

                Parameters: ~
                    {opts}  table|nil Configuration table. Keys:
                            • {wrap}: (boolean)
                              Whether to loop around file or not. Defaults
                              to the value 'wrapscan'

prev_hunk({opts})                                       *gitsigns.prev_hunk()*
                Jump to the previous hunk in the current buffer. Respects
                |wrapscan|.

                Parameters: ~
                    {opts}  table|nil Configuration table. Keys:
                            • {wrap}: (boolean)
                              Whether to loop around file or not. Defaults
                              to the value 'wrapscan'

stage_hunk()                                           *gitsigns.stage_hunk()*
                Stage the hunk at the cursor position.

undo_stage_hunk()                                 *gitsigns.undo_stage_hunk()*
                Undo the last call of stage_hunk(). Note: only the calls to
                stage_hunk() performed in the current session can be undone.

reset_hunk()                                           *gitsigns.reset_hunk()*
                Reset the lines of the hunk at the cursor position to what
                is in Git's index.

preview_hunk()                                       *gitsigns.preview_hunk()*
                Preview the hunk at the cursor position in a floating
                window.

blame_line()                                           *gitsigns.blame_line()*
                Run git blame on the current line and show the results in a
                floating window.

update()                                                   *gitsigns.update()*
                Update signs for the current buffer.

attach()                                                   *gitsigns.attach()*
                Attach Gitsigns to the current buffer.

detach({bufnr})                                            *gitsigns.detach()*
                Detach Gitsigns from the buffer {bufnr}. If {bufnr} is not
                provided then the current buffer is used.

                Parameters: ~
                    {bufnr}  (number): Buffer number

detach_all()                                           *gitsigns.detach_all()*
                Detach Gitsigns from all buffers it is attached to.

text_object()                                         *gitsigns.text_object()*
                Select the hunk under the cursor.

==============================================================================
CONFIGURATION                                                *gitsigns-config*

signs                                                  *gitsigns-config-signs*
        Type: `table`, Default:
>
        {
          add          = {hl = 'DiffAdd'   , text = '│', numhl='GitSignsAddNr'   , linehl='GitSignsAddLr'    },
          change       = {hl = 'DiffChange', text = '│', numhl='GitSignsChangeNr', linehl='GitSignsChangeLr' },
          delete       = {hl = 'DiffDelete', text = '_', numhl='GitSignsDeleteNr', linehl='GitSignsDeleteLr' },
          topdelete    = {hl = 'DiffDelete', text = '‾', numhl='GitSignsDeleteNr', linehl='GitSignsDeleteLr' },
          changedelete = {hl = 'DiffChange', text = '~', numhl='GitSignsChangeNr', linehl='GitSignsChangeLr' },
        }
<
        Configuration for signs:
          • `hl` specifies the highlight group to use for the sign.
          • `text` specifies the character to use for the sign.
          • `numhl` specifies the highlight group to use for the number column
            (see |gitsigns-config.numhl|).
          • `linehl` specifies the highlight group to use for the line
            (see |gitsigns-config.linehl|).
          • `show_count` to enable showing count of hunk, e.g. number of deleted
            lines.

keymaps                                              *gitsigns-config-keymaps*
        Type: `table`, Default:
>
        {
          -- Default keymap options
          noremap = true,
          buffer = true,

          ['n ]c'] = { expr = true, "&diff ? ']c' : '<cmd>lua require\"gitsigns\".next_hunk()<CR>'"},
          ['n [c'] = { expr = true, "&diff ? '[c' : '<cmd>lua require\"gitsigns\".prev_hunk()<CR>'"},

          ['n <leader>hs'] = '<cmd>lua require"gitsigns".stage_hunk()<CR>',
          ['n <leader>hu'] = '<cmd>lua require"gitsigns".undo_stage_hunk()<CR>',
          ['n <leader>hr'] = '<cmd>lua require"gitsigns".reset_hunk()<CR>',
          ['n <leader>hp'] = '<cmd>lua require"gitsigns".preview_hunk()<CR>',
          ['n <leader>hb'] = '<cmd>lua require"gitsigns".blame_line()<CR>',

          ['o ih'] = ':<C-U>lua require"gitsigns".text_object()<CR>',
          ['x ih'] = ':<C-U>lua require"gitsigns".text_object()<CR>'
        }
<
        Keymaps to set up when attaching to a buffer.

        Each key in the table defines the mode and key (whitespace delimited)
        for the mapping and the value defines what the key maps to. The value
        can be a table which can contain keys matching the options defined in
        |map-arguments| which are: `expr`, `noremap`, `nowait`, `script`,
        `silent`, `unique` and `buffer`.  These options can also be used in
        the top level of the table to define default options for all mappings.

watch_index                                      *gitsigns-config-watch_index*
        Type: `table`, Default:
>
        { interval = 1000 }
<
        When opening a file, a libuv watcher is placed on the respective
        `.git/index` file to detect when changes happen to use as a trigger to
        update signs.

sign_priority                                  *gitsigns-config-sign_priority*
        Type: `number`, Default: `6`

        Priority to use for signs.

numhl                                                  *gitsigns-config-numhl*
        Type: `boolean`, Default: `false`

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

linehl                                                *gitsigns-config-linehl*
        Type: `boolean`, Default: `false`

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

diff_algorithm                                *gitsigns-config-diff_algorithm*
        Type: `string`, Default: taken from 'diffopt'

        Diff algorithm to pass to `git diff` .

count_chars                                      *gitsigns-config-count_chars*
        Type: `table`, Default:
>
        { "1", "2", "3", "4", "5", "6", "7", "8", "9",
          ["+"] = ">"
        }
<
        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.

status_formatter                            *gitsigns-config-status_formatter*
        Type: `function`, 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
<
        Function used to format `b:gitsigns_status`.

max_file_length                              *gitsigns-config-max_file_length*
        Type: `number`, Default: `40000`

      Max file length to attach to.

update_debounce                              *gitsigns-config-update_debounce*
        Type: `number`, Default: `200`

      Debounce time for updates (in milliseconds).

debug_mode                                        *gitsigns-config-debug_mode*
        Type: `boolean`, Default: `false`

        Print diagnostic messages.

==============================================================================
STATUSLINE                                               *gitsigns-statusline*

                                *b:gitsigns_status* *b:gitsigns_status_dict*
The buffer variables `b:gitsigns_status` and `b:gitsigns_status_dict` are
provided. `b:gitsigns_status` is formatted using `config.status_formatter`
. `b:gitsigns_status_dict` is a dictionary with the keys `added`, `removed`,
`changed` and `head`.

Example:
>
    set statusline+=%{get(b:,'gitsigns_status','')}
<
                                                             *b:gitsigns_head*
Use `b:gitsigns_head` to return the name of the current branch. If the current
HEAD is detached then this will be an empty string.

==============================================================================
TEXT OBJECTS                                             *gitsigns-textobject*

Since text objects are defined via keymaps, these are exposed and configurable
via the config, see |gitsigns-config-keymaps|. The lua implementation is
exposed through |gitsigns.text_object()|.

------------------------------------------------------------------------------
vim:tw=78:ts=8:ft=help:norl: