TimUntersberger/neogit

github github
git plugin
star 992
stars
alert-circle 56
open issues
users 23
subscribers
git-branch 46
forks
CREATED

2020-06-18

UPDATED

yesterday

packer

require('packer').startup(function()
  use 'TimUntersberger/neogit'
end)

paq

require "paq" { 
  'TimUntersberger/neogit'
}

Neogit

preview

A work-in-progress Magit clone for Neovim that is geared toward the Vim philosophy.

Installation

NOTE: We depend on plenary.nvim, so to use this plugin, you will additionally need to require nvim-lua/plenary.nvim using your plugin manager of choice, before requiring this plugin.

Plugin Manager Command
Packer use { 'TimUntersberger/neogit', requires = 'nvim-lua/plenary.nvim' }
Vim-plug Plug 'TimUntersberger/neogit'
NeoBundle NeoBundle 'TimUntersberger/neogit'
Vundle Bundle 'TimUntersberger/neogit'
Pathogen git clone https://github.com/TimUntersberger/neogit.git ~/.vim/bundle/neogit
Dein call dein#add('TimUntersberger/neogit')

You also use in the built-in package manager:

$ git clone --depth 1 https://github.com/TimUntersberger/neogit $XDG_CONFIG_HOME/nvim/pack/plugins/start/neogit

Now you have to add the following lines to your init.lua

local neogit = require('neogit')

neogit.setup {}

Usage

You can either open neogit by using the Neogit command

:Neogit " uses tab
:Neogit kind=<kind> " override kind
:Neogit cwd=<cwd> " override cwd
:Neogit commit" open commit popup

or using the lua api:

local neogit = require('neogit')

-- open using defaults
neogit.open()

-- open commit popup
neogit.open({ "commit" })

-- open with split kind
neogit.open({ kind = "split" })

-- open home directory
neogit.open({ cwd = "~" })

The create function takes 1 optional argument that can be one of the following values:

  • tab (default)
  • floating (This currently doesn't work with popups. Very unstable)
  • split
  • split_above
  • vsplit

Status Keybindings

Keybinding Function
Tab Toggle diff
1, 2, 3, 4 Set a foldlevel
$ Command history
b Branch popup
s Stage (also supports staging selection/hunk)
S Stage unstaged changes
<C-s> Stage Everything
u Unstage (also supports staging selection/hunk)
U Unstage staged changes
c Open commit popup
r Open rebase popup
L Open log popup
p Open pull popup
P Open push popup
Z Open stash popup
? Open help popup
x Discard changes (also supports discarding hunks)
<enter> Go to file
<C-r> Refresh Buffer

With diffview integration enabled

Keybinding Function
d Open diffview.nvim at hovered file
D (TODO) Open diff popup

Configuration

You can configure neogit by running the neogit.setup function.

local neogit = require("neogit")

neogit.setup {
  disable_signs = false,
  disable_hint = false,
  disable_context_highlighting = false,
  disable_commit_confirmation = false,
  auto_refresh = true,
  disable_builtin_notifications = false,
  commit_popup = {
      kind = "split",
  },
  -- Change the default way of opening neogit
  kind = "tab"
  -- customize displayed signs
  signs = {
    -- { CLOSED, OPENED }
    section = { ">", "v" },
    item = { ">", "v" },
    hunk = { "", "" },
  },
  integrations = {
    -- Neogit only provides inline diffs. If you want a more traditional way to look at diffs, you can use `sindrets/diffview.nvim`.
    -- The diffview integration enables the diff popup, which is a wrapper around `sindrets/diffview.nvim`.
    --
    -- Requires you to have `sindrets/diffview.nvim` installed.
    -- use { 
    --   'TimUntersberger/neogit', 
    --   requires = { 
    --     'nvim-lua/plenary.nvim',
    --     'sindrets/diffview.nvim' 
    --   }
    -- }
    --
    diffview = false  
  },
  -- Setting any section to `false` will make the section not render at all
  sections = {
    untracked = {
      folded = false
    },
    unstaged = {
      folded = false
    },
    staged = {
      folded = false
    },
    stashes = {
      folded = true
    },
    unpulled = {
      folded = true
    },
    unmerged = {
      folded = false
    },
    recent = {
      folded = true
    },
  },
  -- override/add mappings
  mappings = {
    -- modify status buffer mappings
    status = {
      -- Adds a mapping with "B" as key that does the "BranchPopup" command
      ["B"] = "BranchPopup",
      -- Removes the default mapping of "s"
      ["s"] = "",
    }
  }
}

Right now, only the status buffer supports custom mappings.

List of status commands:

  • Close
  • Depth1 (Set foldlevel to 1)
  • Depth2 (Set foldlevel to 2)
  • Depth3 (Set foldlevel to 3)
  • Depth4 (Set foldlevel to 4)
  • Toggle
  • Discard (Normal and visual mode)
  • Stage (Normal and visual mode)
  • StageUnstaged
  • StageAll
  • GoToFile
  • Unstage (Normal and visual mode)
  • UnstageStaged
  • CommandHistory
  • RefreshBuffer
  • HelpPopup
  • PullPopup
  • PushPopup
  • CommitPopup
  • LogPopup
  • StashPopup
  • BranchPopup

Magit-style keybindings

Neogit uses 'p' for pulling instead of 'F'.

Add the following line to your config to use magit-style keybindings.

neogit.config.use_magit_keybindings()

Notification Highlighting

Neogit defines three highlight groups for the notifications:

hi NeogitNotificationInfo guifg=#80ff95
hi NeogitNotificationWarning guifg=#fff454
hi NeogitNotificationError guifg=#c44323

You can override them to fit your colorscheme in your vim configuration.

Contextual Highlighting

The colors for contextual highlighting are defined with these highlight groups:

hi def NeogitDiffAddHighlight guibg=#404040 guifg=#859900
hi def NeogitDiffDeleteHighlight guibg=#404040 guifg=#dc322f
hi def NeogitDiffContextHighlight guibg=#333333 guifg=#b2b2b2
hi def NeogitHunkHeader guifg=#cccccc guibg=#404040
hi def NeogitHunkHeaderHighlight guifg=#cccccc guibg=#4d4d4d

You can override them to fit your colorscheme by creating a syntax/NeogitStatus.vim in your vim configuration and adding your custom highlights there.

Disabling Contextual Highlighting

Set disable_context_highlighting = true in your call to setup to disable context highlighting altogether.

Disabling Hint

Set disable_hint = true in your call to setup to hide hints on top of the panel.

Disabling Commit Confirmation

Set disable_commit_confirmation = true in your call to setup to disable the "Are you sure you want to commit?" prompt after saving the commit message buffer.

Disabling Insert On Commit

Set disable_insert_on_commit = true in your call to setup to disable automatically changing to insert mode when opening the commit message buffer. (Disabled is the default)

Events

Neogit emits a NeogitStatusRefreshed event whenever the status gets reloaded.

You can listen to the event using the following code:

autocmd User NeogitStatusRefreshed echom "Hello World!"

Further information can be found under :h autocmd.

Todo

Note: This file is no longer being updated.

The todo file does not represent ALL of the missing features. This file just shows the features which I noticed were missing and I have to implement.

TODO

Testing

Assure that you have plenary.nvim installed as a plugin for your neovim instance. Afterwards, run make test to run the unit test suite.

Plenary uses it's own port of busted and a bundled luassert, so consult their code and the respective busted and luassert docs for what methods are available.