gitsigns.nvim: Git hunks, blame and staging inside Neovim buffers

The problem gitsigns.nvim solves for Neovim users

The README describes the project as "Deep buffer integration for Git". That phrase is the whole pitch. The unit of work is the buffer you are editing, not the repository. A normal Git workflow makes you leave the editor to see what changed, then come back to fix it. gitsigns.nvim puts the change information in the sign column, in virtual text, in a popup or in a quickfix list, and gives you commands that operate on the hunk under the cursor.

The audience is narrow and specific: people who already run Neovim as their editor and want Git awareness attached to the file they have open. It is not a Git client. The README's feature list covers signs for added, changed and deleted lines, separate signs for staged changes, hunk staging and resetting, inline and popup hunk previews, blame in three forms, revision switching, intra-line word diff, quickfix and location list output, a hunk text object, and status line variables. There is no commit dialog, no branch manager and no merge conflict resolver in that list.

If your editing happens in another editor or an IDE, this plugin has nothing to offer you.

How the signs, hunks and blame are wired into a buffer

The plugin attaches to a buffer and compares it against a revision. By default that revision is the index, which is why staged and unstaged changes can be shown with different signs. `:Gitsigns change_base <REVISION>` moves the comparison point, and `:Gitsigns diffthis <REVISION>` opens a diff of the current buffer against the index or any revision you name. `:Gitsigns show <REVISION>` edits the current buffer at that revision instead.

The buffer is watched rather than polled on every keystroke. The setup table exposes `watch_gitdir = { follow_files = true }` and an `update_debounce` of 100 by default, so sign updates are coalesced after edits. Two keys control what gets attached at all: `auto_attach = true` and `attach_to_untracked = false`. Untracked files therefore do not get signs unless you change that flag, which is a deliberate default rather than an oversight.

Blame has its own path. `:Gitsigns blame` shows blame for the whole buffer, `:Gitsigns blame_line` shows it in a popup, and `current_line_blame = true` puts it in virtual text for the line under the cursor. The virtual text version has a `delay` of 1000 milliseconds by default, a position chosen from `'eol'`, `'overlay'` or `'right_align'`, and a formatter string of `'<author>, <author_time:%R> - <summary>'`. That delay exists because running blame on every cursor move is expensive; the default trades immediacy for not hammering Git.

Status line integration is exposed through buffer variables rather than a function call: `b:gitsigns_status` is a formatted string, `b:gitsigns_status_dict` is a dictionary with the keys `added`, `removed`, `changed` and `head`, and `b:gitsigns_head` gives the current branch. The README's example is a single statusline expression, which means any status line plugin that can read a buffer variable works without an adapter.

Installing gitsigns.nvim and staging your first hunk

The README says to install with your package manager of choice and that no setup is required. It does not name a specific manager, so the exact install line depends on which one you use. What the README does specify is the requirement: Neovim >= 0.11.0, plus a reasonably new Git. It also warns that on a development build of Neovim, breakage may occur if your build is behind master, and points users on older Neovim at a past release.

The configuration table is passed to the plugin's setup function. The README's example shows most of the defaults, and the comment next to each key names the command that toggles it at runtime:

require('gitsigns').setup {
  signcolumn = true,  -- Toggle with `:Gitsigns toggle_signs`
  numhl      = false, -- Toggle with `:Gitsigns toggle_numhl`
  linehl     = false, -- Toggle with `:Gitsigns toggle_linehl`
  word_diff  = false, -- Toggle with `:Gitsigns toggle_word_diff`
  current_line_blame = false, -- Toggle with `:Gitsigns toggle_current_line_blame`
  update_debounce = 100,
  max_file_length = 40000, -- Disable if file is longer than this (in lines)
}

After that, open a tracked file in a Git repository. You should see signs in the sign column for added, changed and deleted lines. With `signs_staged_enable = true`, which is the default, staged changes use the separate `signs_staged` table.

The first real use is staging without leaving the buffer. Put the cursor on a changed hunk and run the command from the README:

:Gitsigns stage_hunk

To move between hunks, the README documents `:Gitsigns nav_hunk next/prev`. To undo the staging decision, `:Gitsigns reset_hunk` resets the hunk. Both work on partial hunks when you make a visual selection first, which is the reason to use this over `git add -p` in a terminal: the selection is made with Neovim's own motions. To see the hunk before deciding, `:Gitsigns preview_hunk_inline` draws it in the buffer and `:Gitsigns preview_hunk` opens it in a popup.

If you want hunks collected in one place instead of navigated one at a time, `:Gitsigns setqflist` and `:Gitsigns setloclist` populate the quickfix or location list. The README documents a `target` option with values `all` for the whole repository, `attached` for attached buffers, or an integer for a specific buffer.

Where gitsigns.nvim stops being the right tool

The plugin is scoped to buffers that are attached and, by default, tracked. `attach_to_untracked = false` means a new file shows nothing until it is added to the index. That is a reasonable default, but it surprises people who expect a brand new file to be marked. You can flip the flag, and the README lists `untracked` as a sign type in both sign tables, so the capability exists.

Large files are skipped. `max_file_length` defaults to 40000 lines, and the README's comment says to disable it if the file is longer than that. So on a very large generated file, signs and hunk actions will not be there. That is a guard against doing diff work on files where the result would be meaningless anyway.

The blame virtual text runs on a 1000 ms delay by default. On a file with heavy history and a slow Git, that delay is the point at which you stop noticing blame as you move the cursor. The `use_focus` and `ignore_whitespace` options exist in `current_line_blame_opts`, but the README does not explain what they change, so treat them as undocumented knobs to experiment with rather than settings you can reason about from the README alone.

Finally, the scope boundary matters. There is no commit interface here. If you want to write a commit message, amend, rebase or resolve a conflict, gitsigns.nvim will not do it, and the README does not claim otherwise. It also does not document rollback behaviour for `stage_hunk` or `reset_hunk`, so if you want an undo path, the ordinary Git reflog and index are your safety net, not a plugin feature.

gitsigns.nvim compared with running Git in a terminal split

The obvious alternative is not another plugin; it is a terminal split running `git add -p`, `git diff` and `git blame`. The difference is the interaction model, not the feature list. `git add -p` asks you y/n per hunk in a prompt and gives you limited control over hunk boundaries. gitsigns.nvim lets you make a visual selection with Neovim motions and stage exactly that range, then preview the result inline before committing to it. If your hunks are usually clean and you rarely split them, the terminal is fine and adds no dependency.

Among Neovim plugins, the alternative people look for is a full Git porcelain inside the editor, with a status buffer, commit staging view and log. gitsigns.nvim is not that. It never builds a repository view; its quickfix integration can list hunks across the repository with `target=all`, but that is a list of changes, not a staging area you can commit from. If you want to review a branch and write commits without leaving Neovim, gitsigns.nvim covers only the part between editing and `git add`.

The third comparison is with built-in Neovim features. Neovim ships its own diff mode, and `:Gitsigns diffthis <REVISION>` is the plugin's route into it. The plugin's contribution is choosing the revision for you and keeping signs in sync with the buffer as you type, which the built-in diff mode does not do on its own.

Maintenance, releases and what the MIT licence means here

The repository is not archived and the last push was on 2026-09-16, which is recent. Releases are tagged and versioned: v2.1.0 on 2026-03-26, v2.0.0 on 2026-01-09 and v1.0.2 on 2025-03-16. The gap between v1.0.2 and v2.0.0 is roughly ten months, so the major version boundary is not something that arrives every few weeks. The repository also carries a CHANGELOG.md and a release-please configuration, which suggests releases are generated from commit history rather than hand-written.

The upgrade cost is dominated by the Neovim version requirement, not by the plugin's own API. The README states Neovim >= 0.11.0 and points users on older versions at a past release, so a Neovim upgrade is often the real work. The Makefile shows the project tests against v0.11.7, v0.12.0 and nightly through targets `test-011`, `test-012` and `test-nightly`, which tells you which Neovim versions the maintainer considers supported. If you run a distribution build that lags, you are outside that tested set.

The licence is MIT. That permits use, modification and redistribution with the licence and copyright notice retained. It is a permissive licence with no copyleft obligation on your configuration or your other plugins. This is a description of the licence identifier in the repository, not legal advice; if you are redistributing the plugin inside a product, read the LICENSE file and get your own counsel.

Editorial conclusion

Adopt gitsigns.nvim if you edit inside Neovim and want staging, resetting, previewing and blame to happen in the buffer rather than in a terminal. Do not adopt it if you are on Neovim older than 0.11.0 and unwilling to pin an older release, or if you need a full commit and branch UI, which the README does not claim. Before relying on it, check `:Gitsigns diffthis` against `git diff` on a file with a long history, and confirm the blame delay and `max_file_length` default suit the repositories you open.

Frequently asked questions

Official sources

1. Issues
2. lewis6991/gitsigns.nvim on GitHub
3. License: MIT
4. README
5. Releases