gitsigns.nvim

Statusline Integration

You can display Git status in your statusline using buffer variables:

• b:gitsigns_status: A formatted string (uses config.status_formatter).
• b:gitsigns_status_dict: A dictionary containing added, removed, changed, and head.
• b:gitsigns_head: The current branch name.

Example Vimscript for statusline:

set statusline+=%{get(b:,'gitsigns_status','')}

Trouble.nvim Integration

If trouble.nvim is installed, Gitsigns will automatically use it to display the results of :Gitsigns setqflist or :Gitsigns setloclist instead of the standard Neovim quickfix/location lists.

You can lint your commit messages locally using the make command with the commitlint target. Use the following commands:

• To lint only your latest commit: make commitlint COMMIT=HEAD
• To lint a range of commits: make commitlint RANGE=origin/main..HEAD

When creating or amending commits, follow these formatting rules:

• Subject Format: Use <type>(<scope>): <verb phrase>.
• Subject Length: Keep the subject line under 72 characters.
• Body: Include a detailed body explaining the problem and the solution.
• Line Wrapping: Wrap both body and footer lines at 72 characters.
• Issue Resolution: When a commit resolves a specific issue, add a footer such as Resolves #1525.
• Multi-line Messages: When scripting git commit, use git commit -F <file> for multi-line messages. If using the -m flag, pass actual line breaks instead of literal \n characters.

Install gitsigns.nvim using your preferred Neovim package manager. While no setup is strictly required for basic functionality, you can pass an options object to require('gitsigns').setup() to customize signs, blame behavior, and diff settings.

Requirements:

• Neovim >= 0.9.0
• A recent version of Git

require('gitsigns').setup {
  -- Example configuration
  signs = {
    add          = { text = '┃' },
    change       = { text = '┃' },
    delete       = { text = '_' },
    topdelete    = { text = '‾' },
    changedelete = { text = '~' },
    untracked    = { text = '┆' },
  },
  signs_staged_enable = true,
  current_line_blame = false,
  word_diff = false,
}

Use the following Makefile commands to ensure code quality and documentation consistency before committing changes:

• Format and build: make build formats Lua sources and regenerates documentation.
• Documentation check: make doc regenerates help docs, while make doc-check regenerates them and fails if there is any drift.
• Static analysis: make emmylua-check runs an optional static analysis pass.

To automate commit message linting, you can install a local commit-msg hook using the following command:

make commitlint-hook

To run functional tests, you must first raise the file descriptor limit to avoid failures. Use the following command patterns:

• Run all functional tests: ulimit -n 1024; make test [FILTER=pattern] (where pattern is an optional filter).
• Run against specific Neovim versions: Use make test-010, make test-011, make test-012, or make test-nightly.

Always prefix these commands with ulimit -n 1024 in the sandbox environment.

ulimit -n 1024; make test [FILTER=pattern]
# Or for specific versions:
ulimit -n 1024; make test-010
ulimit -n 1024; make test-nightly

You can populate the quickfix or location list with Git hunks using the following commands:

• :Gitsigns setqflist: Set the quickfix list.
• :Gitsigns setloclist: Set the location list.

Use the target argument to specify the scope:

• target=all: Show hunks for the whole repository.
• target=attached: Show hunks for attached buffers.
• target=[integer]: Show hunks for a specific buffer ID.

The gitsigns.nvim CLI allows you to run actions, attach/detach, or debug functions directly from the command line. When running a command without a specific function name, an interactive selection menu (via vim.ui.select) will appear to let you choose from available actions.

Arguments passed to the command are automatically parsed into Lua types:

• 'true'/'false' becomes boolean true/false.
• 'nil' becomes nil.
• Numeric strings (e.g., '100') become numbers.
• Other strings (e.g., 'HEAD~300') remain strings.