*gitsigns.txt* Gitsigns
*gitsigns.nvim*

Author:   Lewis Russell <lewis6991@gmail.com>
Version:  {{VERSION}}
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
requires no external dependencies other than git. This is unlike other plugins
that require python, node, etc, which need to communicate with Neovim using
|RPC|.  By default, Gitsigns also uses Neovim's built-in diff library
(`vim.diff`) unlike other similar plugins that need to run `git-diff` as an
external process which is less efficient, has tighter bottlenecks and requires
file IO.

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

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

Configuration can be passed to the setup function. Here is an example with most
of the default settings:
>lua
{{SETUP}}
<

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

Custom mappings can be defined in the `on_attach` callback in the config table
passed to |gitsigns-setup()|. See |gitsigns-config-on_attach|.

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

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

Note functions with the {async} attribute are run asynchronously and accept
an optional {callback} argument.


{{FUNCTIONS}}

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

This section describes the configuration fields which can be passed to
|gitsigns.setup()|. Note fields of type `table` may be marked with extended
meaning the field is merged with the default, with the user value given higher
precedence. This allows only specific sub-fields to be configured without
having to redefine the whole field.

{{CONFIG}}

==============================================================================
HIGHLIGHT GROUPS                                   *gitsigns-highlight-groups*

These are the highlights groups used by Gitsigns.

Note if a highlight is not defined, it will be automatically derived by
searching for other defined highlights in order.

{{HIGHLIGHTS}}

==============================================================================
COMMAND                                                      *gitsigns-command*

                                                                    *:Gitsigns*
:Gitsigns {subcmd} {args}  Run a Gitsigns command. {subcmd} can be any
                           function documented in |gitsigns-functions|.
                           Each argument in {args} will be attempted to be
                           parsed as a Lua value using `loadstring`, however
                           if this fails the argument will remain as the
                           string given by |<f-args>|.

                           Note this command is equivalent to: >vim
                             :lua require('gitsigns').{subcmd}({args})
<
                           Examples: >vim
                             :Gitsigns diffthis HEAD~1
                             :Gitsigns blame_line
                             :Gitsigns toggle_signs
                             :Gitsigns toggle_current_line_blame
                             :Gitsigns change_base ~
                             :Gitsigns reset_buffer
                             :Gitsigns change_base nil true
<

==============================================================================
SPECIFYING OBJECTS                          *gitsigns-object* *gitsigns-revision*

Gitsigns objects are Git revisions as defined in the "SPECIFYING REVISIONS"
section in the gitrevisions(7) man page. For commands that accept an optional
base, the default is the file in the index. Examples:

Additionally, Gitsigns also accepts the value `FILE` to specify the working
version of a file.

Object        Meaning ~
@             Version of file in the commit referenced by @ aka HEAD
main          Version of file in the commit referenced by main
main^         Version of file in the parent of the commit referenced by main
main~         "
main~1        "
main...other  Version of file in the merge base of main and other
@^            Version of file in the parent of HEAD
@~2           Version of file in the grandparent of HEAD
92eb3dd       Version of file in the commit 92eb3dd
:1            The file's common ancestor during a conflict
:2            The alternate file in the target branch during a conflict

==============================================================================
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` - Number of added lines.
        • `changed` - Number of changed lines.
        • `removed` - Number of removed lines.
        • `head` - Name of current HEAD (branch or short commit hash).
        • `root` - Top level directory of the working tree.
        • `gitdir` - .git directory.

Example:
>vim
    set statusline+=%{get(b:,'gitsigns_status','')}
<
                                            *b:gitsigns_head* *g:gitsigns_head*
Use `g:gitsigns_head` and `b:gitsigns_head` to return the name of the current
HEAD (usually branch name). If the current HEAD is detached then this will be
a short commit hash. `g:gitsigns_head` returns the current HEAD for the
current working directory, whereas `b:gitsigns_head` returns the current HEAD
for each buffer.

                            *b:gitsigns_blame_line* *b:gitsigns_blame_line_dict*
Provided if |gitsigns-config-current_line_blame| is enabled.
`b:gitsigns_blame_line` if formatted using
`config.current_line_blame_formatter`. `b:gitsigns_blame_line_dict` is a
dictionary containing of the blame object for the current line. For complete
list of keys, see the {blame_info} argument from
|gitsigns-config-current_line_blame_formatter|.

==============================================================================
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.select_hunk()|.

==============================================================================
EVENTS                                                       *gitsigns-events*

|User| |autocommands| provided to allow extending behaviors.

Example: >lua
    vim.api.nvim_create_autocmd('User', {
      pattern = 'GitSignsUpdate',
      callback = function(args)
        print(os.time(), ' Gitsigns made an update on ', args.data.buffer)
      end
    })
<
                                                       *User_GitSignsUpdate*
GitSignsUpdate     After Gitsigns updates its knowledge about hunks.
                   Provides `bufnr` in the autocmd user data.

                                                      *User_GitSignsChanged*
GitSignsChanged    After any event in which Gitsigns can potentially change
                   the repository. Provides `file` in the autocmd user data.

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