search

tanvirtin / vgit.nvim

Visual git plugin for Neovim
MIT License
583 stars 11 forks source link
git git-porcelain lua neovim scm

readme

VGit

Visual Git Plugin for Neovim to enhance your git experience
[![Lua](https://img.shields.io/badge/Lua-blue.svg?style=for-the-badge&logo=lua)](http://www.lua.org) [![Neovim](https://img.shields.io/badge/Neovim%200.8+-green.svg?style=for-the-badge&logo=neovim)](https://neovim.io) CI License


Hunk Preview

Highlighted features

Requirements

Prerequisites

Recommended settings

vim.o.updatetime = 300
vim.o.incsearch = false
vim.wo.signcolumn = 'yes'

Installation

Default installation via Packer.

use {
  'tanvirtin/vgit.nvim',
  requires = {
    'nvim-lua/plenary.nvim'
  }
}

Setup

You must instantiate the plugin in order for the features to work.

require('vgit').setup()

To embed the above code snippet in a .vim file wrap it in lua << EOF code-snippet EOF.

lua << EOF
require('vgit').setup()
EOF

Highlights, signs, keymappings are few examples of what can be configured in VGit. Advanced setup below shows you all configurable parameters in VGit.

Show advanced setup
```lua require('vgit').setup({ keymaps = { ['n '] = function() require('vgit').hunk_up() end, ['n '] = function() require('vgit').hunk_down() end, ['n gs'] = function() require('vgit').buffer_hunk_stage() end, ['n gr'] = function() require('vgit').buffer_hunk_reset() end, ['n gp'] = function() require('vgit').buffer_hunk_preview() end, ['n gb'] = function() require('vgit').buffer_blame_preview() end, ['n gf'] = function() require('vgit').buffer_diff_preview() end, ['n gh'] = function() require('vgit').buffer_history_preview() end, ['n gu'] = function() require('vgit').buffer_reset() end, ['n gg'] = function() require('vgit').buffer_gutter_blame_preview() end, ['n glu'] = function() require('vgit').buffer_hunks_preview() end, ['n gls'] = function() require('vgit').project_hunks_staged_preview() end, ['n gd'] = function() require('vgit').project_diff_preview() end, ['n gq'] = function() require('vgit').project_hunks_qf() end, ['n gx'] = function() require('vgit').toggle_diff_preference() end, }, settings = { git = { cmd = 'git', -- optional setting, not really required fallback_cwd = vim.fn.expand("$HOME"), fallback_args = { "--git-dir", vim.fn.expand("$HOME/dots/yadm-repo"), "--work-tree", vim.fn.expand("$HOME"), }, }, hls = { GitBackground = 'Normal', GitHeader = 'NormalFloat', GitFooter = 'NormalFloat', GitBorder = 'LineNr', GitLineNr = 'LineNr', GitComment = 'Comment', GitSignsAdd = { gui = nil, fg = '#d7ffaf', bg = nil, sp = nil, override = false, }, GitSignsChange = { gui = nil, fg = '#7AA6DA', bg = nil, sp = nil, override = false, }, GitSignsDelete = { gui = nil, fg = '#e95678', bg = nil, sp = nil, override = false, }, GitSignsAddLn = 'DiffAdd', GitSignsDeleteLn = 'DiffDelete', GitWordAdd = { gui = nil, fg = nil, bg = '#5d7a22', sp = nil, override = false, }, GitWordDelete = { gui = nil, fg = nil, bg = '#960f3d', sp = nil, override = false, }, }, live_blame = { enabled = true, format = function(blame, git_config) local config_author = git_config['user.name'] local author = blame.author if config_author == author then author = 'You' end local time = os.difftime(os.time(), blame.author_time) / (60 * 60 * 24 * 30 * 12) local time_divisions = { { 1, 'years' }, { 12, 'months' }, { 30, 'days' }, { 24, 'hours' }, { 60, 'minutes' }, { 60, 'seconds' }, } local counter = 1 local time_division = time_divisions[counter] local time_boundary = time_division[1] local time_postfix = time_division[2] while time < 1 and counter ~= #time_divisions do time_division = time_divisions[counter] time_boundary = time_division[1] time_postfix = time_division[2] time = time * time_boundary counter = counter + 1 end local commit_message = blame.commit_message if not blame.committed then author = 'You' commit_message = 'Uncommitted changes' return string.format(' %s • %s', author, commit_message) end local max_commit_message_length = 255 if #commit_message > max_commit_message_length then commit_message = commit_message:sub(1, max_commit_message_length) .. '...' end return string.format( ' %s, %s • %s', author, string.format( '%s %s ago', time >= 0 and math.floor(time + 0.5) or math.ceil(time - 0.5), time_postfix ), commit_message ) end, }, live_gutter = { enabled = true, edge_navigation = true, -- This allows users to navigate within a hunk }, authorship_code_lens = { enabled = true, }, scene = { diff_preference = 'unified', -- unified or split keymaps = { quit = 'q' } }, diff_preview = { keymaps = { buffer_stage = 'S', buffer_unstage = 'U', buffer_hunk_stage = 's', buffer_hunk_unstage = 'u', toggle_view = 't', }, }, project_diff_preview = { keymaps = { buffer_stage = 's', buffer_unstage = 'u', buffer_hunk_stage = 'gs', buffer_hunk_unstage = 'gu', buffer_reset = 'r', stage_all = 'S', unstage_all = 'U', reset_all = 'R', }, }, project_commit_preview = { keymaps = { save = 'S', }, }, signs = { priority = 10, definitions = { GitSignsAddLn = { linehl = 'GitSignsAddLn', texthl = nil, numhl = nil, icon = nil, text = '', }, GitSignsDeleteLn = { linehl = 'GitSignsDeleteLn', texthl = nil, numhl = nil, icon = nil, text = '', }, GitSignsAdd = { texthl = 'GitSignsAdd', numhl = nil, icon = nil, linehl = nil, text = '┃', }, GitSignsDelete = { texthl = 'GitSignsDelete', numhl = nil, icon = nil, linehl = nil, text = '┃', }, GitSignsChange = { texthl = 'GitSignsChange', numhl = nil, icon = nil, linehl = nil, text = '┃', }, }, usage = { screen = { add = 'GitSignsAddLn', remove = 'GitSignsDeleteLn', }, main = { add = 'GitSignsAdd', remove = 'GitSignsDelete', change = 'GitSignsChange', }, }, }, symbols = { void = '⣿', }, } }) ```

Status Line

Use b:vgit_status, a table containing the current buffer's number of added, removed, changed lines.

Example:

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

API

VGit Commands


Function Name Description
setup Sets VGit up for you. This plugin cannot be used before this function has been called.
hunk_up Moves the cursor to the hunk above the current cursor position.
hunk_down Moves the cursor to the hunk below the current cursor position.
checkout [args] Wrapper command for git checkout. You can switch branches or restore working tree files
buffer_hunk_preview Opens a diff preview showing the diff of the current buffer in comparison to that found in index. This preview will open up in a smaller window relative to where your cursor is.
buffer_diff_preview Opens a diff preview showing the diff of the current buffer in comparison to that found in index. If the command is called while being on a hunk, the window will open focused on the diff of that hunk.
buffer_history_preview Opens a diff preview along with a table of logs, enabling users to see different iterations of the file through it's lifecycle in git.
buffer_blame_preview Opens a preview detailing the blame of the line that based on the cursor position within the buffer.
buffer_gutter_blame_preview Opens a preview which shows all the blames related to the lines of the buffer.
buffer_diff_staged_preview Opens a diff preview showing the diff of the staged changes in the current buffer.
buffer_hunk_staged_preview Opens a diff preview showing the diff of the staged changes in the current buffer. This preview will open up in a smaller window relative to where your cursor is.
buffer_hunk_stage Stages a hunk, if a cursor is on the hunk.
buffer_hunk_reset Removes all changes made in the buffer on the hunk the cursor is currently on to what exists in HEAD.
buffer_stage Stages all changes in the current buffer.
buffer_unstage Unstages all changes in the current buffer.
buffer_reset Removes all current changes in the buffer and resets it to the version in HEAD.
project_diff_preview Opens a diff preview along with a list of all the files that have been changed, enabling users to see all the files that were changed in the current project
project_logs_preview [args] Opens a preview listing all the logs in the current working branch. Users can filter the list by passing options to this list. Pressing the "tab" key on a list item will keep the item selected. Pressing the "enter" key on the preview will close the preview and open "project_commits_preview" with the selected commits
project_commit_preview Opens a preview through which staged changes can be committed
project_commits_preview [args] Opens a diff preview along with a list of all your commits
project_stash_preview Opens a preview listing all stashes. Pressing the "enter" key on the preview will close the preview and open "project_commits_preview" with the selected stashes
project_hunks_preview Opens a diff preview along with a foldable list of all the current hunks in the project. Users can use this preview to cycle through all the hunks.
project_hunks_staged_preview Opens a diff preview along with a foldable list of all the current staged hunks in the project. Users can use this preview to cycle through all the hunks.
project_debug_preview Opens a VGit view showing logs of a pariticular kind traced within the application.
project_hunks_qf Populate the quickfix list with hunks. Automatically opens the quickfix window.
project_stage_all Stages all file changes in your project.
project_unstage_all Unstages all file changes in your project.
project_reset_all Discards all file changes that are not staged.
toggle_diff_preference Used to switch between "split" and "unified" diff.
toggle_live_gutter Enables/disables git gutter signs.
toggle_live_blame Used to switch between "split" and "unified" diff.
toggle_authorship_code_lens Enables/disables authorship code lens that can be found on top of the file
toggle_tracing Enables/disables debug logs that are used internally by VGit to make suppressed logs visible.

Debugging

Start off by allowing VGit to trace your actions: - `:VGit toggle_tracing` Each category of logs can be previewed using the following commands: - `:VGit debug_preview infos` - `:VGit debug_preview warnings` - `:VGit debug_preview errors`