gitsigns.nvim — Git Integration for Neovim Buffers

Introduction

gitsigns.nvim by lewis6991 is a Neovim plugin that provides git decorations and operations directly in your buffers. With nearly 7,000 stars on GitHub, it is the standard choice for in-buffer git integration in the Neovim ecosystem, replacing the older vim-gitgutter with a faster, async Lua implementation.

What gitsigns.nvim Does

The plugin shows colored signs in the sign column next to lines that have been added, changed, or deleted relative to the git index. Beyond visual indicators, it provides actions on diff hunks: stage a hunk, reset a hunk, preview the diff inline, and navigate between hunks. It also supports inline blame annotations showing who last modified each line.

Architecture Overview

gitsigns.nvim is written in Lua and uses Neovim's async facilities (libuv) to run git operations without blocking the editor. It shells out to git to compute diffs rather than embedding a git library. The diff computation runs in a separate luv thread, and results are applied to the buffer's sign column and extmarks on completion. File watchers detect changes to the working tree and index, triggering automatic updates.

Self-Hosting & Configuration

The plugin runs entirely locally and requires only git to be installed. Configuration is passed to the setup() function. Key options include: signs (customize sign characters and highlights), current_line_blame (enable inline blame), current_line_blame_opts (blame display delay and format), on_attach (callback to set buffer-local keymaps), and diff_opts (algorithm and indent heuristic settings). Word-level diff highlighting is available via word_diff.

Key Features

• Async sign column indicators for added, changed, and deleted lines
• Hunk actions: stage, unstage, reset, preview diff inline
• Inline git blame on the current line with configurable delay
• Navigation between hunks with next/previous commands
• Support for both file-level and hunk-level staging
• Virtual text and line highlighting options for changes
• Works with detached HEAD, bare repos, and worktrees

Comparison with Similar Tools

vim-gitgutter provides similar sign column functionality but is written in Vimscript and uses synchronous git calls, which can cause UI lag. vim-signify supports multiple VCS backends but lacks hunk staging. mini.diff from mini.nvim offers a minimal alternative but with fewer features. gitsigns.nvim combines comprehensive features with async performance.

FAQ

Does it slow down Neovim on large files? No. Git diff operations run asynchronously and do not block the UI. Sign updates are debounced to avoid excessive recomputation.

Can I stage individual hunks? Yes. Use :Gitsigns stage_hunk to stage the hunk under the cursor or a visual selection. You can also reset or undo staged hunks.

Does it replace fugitive or neogit? No. gitsigns.nvim handles in-buffer decorations and hunk operations. For full git workflows (commits, branches, log), use a dedicated git plugin alongside it.

Sources

• GitHub repository: https://github.com/lewis6991/gitsigns.nvim
• Neovim documentation: :help gitsigns