git.nvim is an asynchronous git command wrapper plugin for Neovim, using :Git command instead of blocking :!git.

• ✨ Features
• 📦 Installation
  • Prerequisites
  • Using nvim-plug
  • Using lazy.nvim
  • Using luarocks
• ⚙️ Basic Usage
  • Git Commands
  • git-add
  • git-blame
  • git-branch
  • git-rm
  • git-remote
  • git-status
  • git-log
  • git-diff
  • git-push/pull
• 🎨 Statusline Integration
• 🔍 Picker Integration
  • Available Sources
  • Usage Example
• ❓ FAQ
  • How is this different from other Git plugins?
  • Does it support all Git commands?
  • Can I use partial Git command flags?
  • How do I view git diff for current file?
  • How does conflict detection work?
  • Can I use this with other Git plugins?
  • Where are commit messages edited?
• 📣 Self-Promotion
• 💬 Feedback
• 📄 License

• Asynchronous Git Commands — Run Git commands via :Git without blocking Neovim UI, powered by job.nvim
• Full Git Coverage — Support for 26+ Git commands including status, add, commit, push/pull, fetch, diff, branch, log, reflog, rebase, stash, tag, cherry-pick, and more
• Interactive Branch Manager — Visual branch list with key mappings for checkout, delete, view log, and diff operations
• Remote Repository Browser — Side panel to browse remote repositories and their branches with fetch support
• Git Blame Integration — Line-by-line blame view with history navigation (view previous versions)
• Git Log Viewer — Commit history with graph visualization and commit details preview
• Picker.nvim Integration — Fuzzy finder sources for branch switching (git-branch) and finding deleted files (git-ghosts)
• Statusline Integration — Easy branch display with optional push/pull status indicators
• Command Completion — Intelligent completion for Git commands, branches, remotes, and file paths
• Conflict Detection — Automatic quickfix list for merge conflicts during pull
• Split Window Editing — Commit messages, rebase todos, and merge messages open in split windows
• No Default Key Bindings — Full control over your workflow without imposed mappings

1. System Dependencies:

   • Git (required): Version 2.0 or higher
   • Neovim: Version 0.9.0 or higher

   Install Git with your package manager:

   # Ubuntu/Debian
   sudo apt install git
   
   # macOS
   brew install git
   
   # Arch Linux
   sudo pacman -S git

2. Neovim Plugin Dependencies:

   • job.nvim: Required for asynchronous operations
   • notify.nvim: Recommended for notifications
   • picker.nvim: Optional for fuzzy finder integration
   • utils.nvim: Optional for statusline spinners

require('plug').add({
    {
        'wsdjeg/git.nvim',
        depends = {
            { 'wsdjeg/job.nvim' },      -- Required
            { 'wsdjeg/notify.nvim' },   -- Recommended
        },
    },
})

Then use :PlugInstall git.nvim to install this plugin.

{
    'wsdjeg/git.nvim',
    dependencies = {
        'wsdjeg/job.nvim',       -- Required
        'wsdjeg/notify.nvim',    -- Recommended
    },
    config = function()
        -- Optional configuration
    end,
}

luarocks install --server=https://luarocks.org/manifests/wsdjeg git.nvim

Use :Git to execute git commands directly inside Neovim. The behavior is identical to the git command-line tool with these enhancements:

• Asynchronous execution — No UI blocking
• Command completion — Tab completion for commands and arguments
• Split window editing — Commit messages and rebase todos open in splits
• Visual interfaces — Branch manager, remote browser, log viewer, blame view
• No default key bindings — Full control over your workflow

git.nvim supports the following Git commands:

Example Key Bindings:

vim.keymap.set('n', '<leader>gs', '<cmd>Git status<cr>', { silent = true })
vim.keymap.set('n', '<leader>gA', '<cmd>Git add .<cr>', { silent = true })
vim.keymap.set('n', '<leader>gc', '<cmd>Git commit<cr>', { silent = true })
vim.keymap.set('n', '<leader>gv', '<cmd>Git log<cr>', { silent = true })
vim.keymap.set('n', '<leader>gV', '<cmd>Git log %<cr>', { silent = true })
vim.keymap.set('n', '<leader>gp', '<cmd>Git push<cr>', { silent = true })
vim.keymap.set('n', '<leader>gP', '<cmd>Git pull<cr>', { silent = true })
vim.keymap.set('n', '<leader>gd', '<cmd>Git diff<cr>', { silent = true })
vim.keymap.set('n', '<leader>gS', '<cmd>Git stash<cr>', { silent = true })
vim.keymap.set('n', '<leader>gB', '<cmd>Git blame<cr>', { silent = true })
vim.keymap.set('n', '<leader>gR', '<cmd>Git remote<cr>', { silent = true })

Add file contents to the index. Same as git add <path>, with % being replaced by the current file.

Examples:

:Git add .          " Add all changes
:Git add %          " Add current file
:Git add src/       " Add all changes in src/ directory
:Git add -p         " Add interactively

Show the revision and author that last modified each line of a file, displayed in a tab with split windows for easy inspection.

Features:

• Line-by-line blame information in left panel
• Original file content in right panel
• Navigate through file history
• Compare different versions

Key Bindings in Blame Window:

Usage:

:Git blame           " Blame current file
:Git blame README.md " Blame specific file
:Git blame HEAD~5    " Blame at specific commit

List, create, or delete branches. Running :Git branch without arguments opens the branch manager in a left split window.

Branch Manager Features:

• Visual branch list in split window
• Shows current branch with * marker
• Local branches listed under "local" section
• Remote branches grouped by remote name
• Interactive operations with key bindings

Branch Manager Key Bindings:

Examples:

:Git branch              " Open branch manager
:Git branch feature-x    " Create new branch
:Git branch -d feature-x " Delete branch
:Git branch -a           " List all branches (including remote)

Remove files from the working tree and from the index. Supports file name completion after :Git rm command.

Examples:

:Git rm filename.txt     " Remove file
:Git rm -r directory/    " Remove directory
:Git rm --cached file    " Remove from index only
:Git rm %                " Remove current file

Manage set of tracked repositories. Running :Git remote without arguments opens a remote browser sidebar.

Remote Browser Features:

• Visual remote repository list
• Browse remote branches for each remote
• Fetch remote updates
• View remote branch logs
• Auto-update branch list with spinner indicator

Remote Browser Key Bindings:

Examples:

:Git remote                    " Open remote browser
:Git remote add origin <url>   " Add remote
:Git remote -v                 " List remotes verbose
:Git remote remove origin      " Remove remote

Show the working tree status in a top split window. The status window provides a clear view of changes in your repository.

Features:

• Opens in top split window (height: 10 lines)
• Shows staged, unstaged, and untracked files
• Read-only buffer with easy navigation
• Press q to close

Examples:

:Git status        " Show repository status
:Git status -s     " Short format

Show commit logs with enhanced visualization. Opens in a new buffer with commit graph.

Features:

• Commit graph with branch visualization
• Color-coded output (red commit hash, green author/date)
• Press <Enter> to view commit details in split window
• Relative dates for better readability
• Support for file-specific history

Key Bindings in Log Window:

Examples:

:Git log           " Show all commits with graph
:Git log %         " Show commits for current file
:Git log --oneline " Compact one-line format
:Git log -10       " Show last 10 commits
:Git log --decorate " Show with branch tags
:Git log branch-name " Show commits for specific branch

Show changes between commits, commit and working tree, etc. Opens in a split window with syntax highlighting.

Features:

• Split window with diff syntax highlighting
• Support for comparing specific files
• Press q to close

Examples:

:Git diff           " Show all unstaged changes
:Git diff %         " Show changes for current file
:Git diff --cached  " Show staged changes
:Git diff HEAD~5    " Compare with specific commit
:Git diff branch1 branch2 " Compare branches

Push to or pull from remote repositories with progress indication.

Features:

• Asynchronous execution with progress indicator (requires utils.nvim)
• Pull conflict detection with quickfix list
• Remote and branch completion
• Statusline spinner integration

Examples:

:Git push                    " Push to default remote
:Git push origin main        " Push to specific remote/branch
:Git push -u origin feature  " Push and set upstream
:Git pull                    " Pull from default remote
:Git pull origin main        " Pull from specific remote/branch

Conflict Handling:

When pulling results in merge conflicts, git.nvim automatically:

1. Detects conflict files
2. Opens quickfix list with conflict file locations
3. Shows notification about merge conflicts

Display current branch information in your statusline using the Lua API.

Basic Example:

-- Get current branch name
local branch = require('git.command.branch').current()

Using with statusline.nvim:

require('plug').add({
  {
    'wsdjeg/statusline.nvim',
    events = { 'VimEnter' },
    config = function()
      require('statusline').register_sections('vcs', function()
        return '%{ v:lua.require("git.command.branch").current() }'
      end)
      require('statusline').setup({
        left_sections = { 'winnr', 'filename', 'vcs' },
      })
    end,
  },
})

Advanced Example with Push/Pull Status:

To display unicode spinners on statusline during push/pull operations, use git.nvim together with utils.nvim:

return {
    'wsdjeg/statusline.nvim',
    events = { 'VimEnter' },
    config = function()
        require('statusline').register_sections('vcs', function()
            return '%{ v:lua.require("git.command.branch").current() .. v:lua.require("git.command.pull").status() .. v:lua.require("git.command.push").status() }'
        end)
        require('statusline').setup({
            left_sections = { 'winnr', 'filename', 'major mode', 'syntax checking', 'vcs' },
            right_sections = { 'fileformat', 'fileencoding', 'cursorpos' },
        })
    end,
    type = 'rocks',
    desc = 'module statusline',
}

API Functions:

• require('git.command.branch').current() — Returns current branch name with optional prefix
• require('git.command.branch').detect() — Force update branch name
• require('git.command.push').status() — Returns push spinner status (requires utils.nvim)
• require('git.command.pull').status() — Returns pull spinner status (requires utils.nvim)

git.nvim provides built-in picker sources for picker.nvim integration:

1. git-branch — Fuzzy find and checkout git branches

   • Quick branch switching
   • Preview branch information
   • Delete branches from picker

   :Picker git-branch

2. git-ghosts — Fuzzy find deleted files in repository history

   • Find files that were deleted
   • Useful for recovering lost work
   • View commit that deleted the file

   :Picker git-ghosts

-- Add key bindings for picker sources
vim.keymap.set('n', '<leader>gb', '<cmd>Picker git-branch<cr>', { silent = true })
vim.keymap.set('n', '<leader>gG', '<cmd>Picker git-ghosts<cr>', { silent = true })

git.nvim focuses on being a thin asynchronous wrapper around Git commands, providing:

• Native Git command syntax — No need to learn new commands, use standard Git commands
• Asynchronous execution — Non-blocking UI powered by job.nvim
• Visual interfaces — Branch manager, remote browser, log viewer, blame view
• Command completion — Intelligent tab completion for commands, branches, remotes, and files
• Zero default key bindings — You're in control of your workflow
• Lightweight — Minimal dependencies and overhead

Yes! git.nvim supports 26+ Git commands including:

• Basic: add, commit, push, pull, fetch, status, diff
• Branching: branch, checkout, merge, rebase, cherry-pick
• History: log, blame, show, reflog, shortlog
• Staging: reset, rm, mv, clean, update-index, stash
• Remote: remote, tag, grep, config

Yes! git.nvim passes all arguments directly to Git, so any Git flag or option is supported:

:Git log --oneline --graph --all
:Git commit --amend --no-edit
:Git push -f origin main
:Git diff HEAD~5 HEAD --stat

:Git diff %        " Diff current file against index
:Git diff --cached " Diff staged changes
:Git diff HEAD     " Diff against HEAD commit

When running :Git pull, git.nvim automatically:

1. Monitors for merge conflict messages
2. Detects files with conflict markers
3. Opens quickfix list with conflict file locations
4. Shows notification about conflicts

Absolutely! git.nvim is designed to complement other Git plugins without conflicts. It focuses on command execution while other plugins may provide additional features like git signs, blame virtual text, etc.

Commit messages, rebase todos, and merge messages open in split windows within Neovim, providing a native editing experience without leaving the editor.

Like this plugin? Star the repository on GitHub.

Love this plugin? Follow me on GitHub.

If you encounter any bugs or have suggestions, please file an issue in the issue tracker.

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.