README.md

nvim-gitstatus

A simple Neovim plugin providing a lualine component to display git status results in the status line.

Caution

This plugin is still in early development. It has not been tested extensively and may not work as expected. Use at your own risk.

Prerequisites

• Neovim ≥ 0.10.0.
• Git.
• lualine for status line integration.

Installation

Using lazy.nvim:

{
  "abccsss/nvim-gitstatus",
  event = "VeryLazy",
  config = true,
}

Setup

Add the component gitstatus to your lualine configuration. For example:

require("lualine").setup({
  sections = {
    lualine_a = { "mode" },
    lualine_b = {
      {
        "gitstatus",
        sections = {
          { "branch", format = " {}" },
          { "is_dirty", format = "*" },
        },
        sep = "",
      },
    },
    lualine_c = {
      {
        "gitstatus",
        sections = {
          { "ahead", format = "{}↑" },
          { "behind", format = "{}↓" },
          { "conflicted", format = "{}!" },
          { "staged", format = "{}=" },
          { "untracked", format = "{}+" },
          { "modified", format = "{}*" },
          { "renamed", format = "{}~" },
          { "deleted", format = "{}-" },
        },
        sep = " ",
      },
      -- other parts here
    },
    -- other sections here
  },
  -- other options here
})

Each item in the sections table is either a string or a table with the following fields:

• [1]: string | function - Either one of the following:

  • string - The variable name to display, which must be one of the following:

    • branch - The current branch name.
    • upstream_branch - The remote branch name.
    • is_dirty - A boolean value indicating whether the working directory is dirty. Useful for e.g. showing a * next to the branch name.
    • up_to_date - A boolean value indicating whether the local branch is up to date with the remote branch.
    • up_to_date_and_clean - Equal to up_to_date and not is_dirty. Useful for showing a symbol when nothing else is displayed.
    • ahead - The number of commits ahead of the remote branch.
    • behind - The number of commits behind the remote branch.
    • conflicted - The number of conflicted items.
    • deleted - The number of deleted items.
    • modified - The number of modified items.
    • renamed - The number of renamed items.
    • staged - The number of staged items, including additions, deletions, modifications, and renames.
    • staged_added - The number of staged additions.
    • staged_deleted - The number of staged deletions.
    • staged_modified - The number of staged modifications.
    • staged_renamed - The number of staged renames.
    • stashed - The number of stashed items.
    • untracked - The number of new items.

  • function - A function which takes an argument status, which is a table containing the above values, and returns a string to display.

• format: string (optional) - The format string to use when [1] is a string. The variable value is inserted at {}. If not provided, the variable value is displayed as is.

• hl: string (optional) - The highlight group to use, which is one of the following:

  • A hex code of the form #rrggbb.
  • The name of a highlight group, such as Normal, or MiniIconsYellow, etc., if you use mini.icons. Only the foreground colour of the highlight group is used.

  The second option is preferred, as it adapts to different colour schemes.

If [1] is a string and the value of a variable is 0 or false or an empty string, the entire section is omitted.

The sep field is either a string or a table with the following fields:

• [1]: string - the separator between sections.
• hl: string (optional) - the highlight group for the separator. See above for the syntax.

Options

The plugin comes with the following default options:

{
  --- Interval to automatically run `git fetch`, in milliseconds.
  --- Set to `false` to disable auto fetch.
  auto_fetch_interval = 30000,

  --- Timeout in milliseconds for `git status` to complete before it is killed.
  git_status_timeout = 1000,

  --- Whether to show debug messages.
  debug = false,
}