nvim-pack
/
gitsigns.nvim
mirror of https://github.com/lewis6991/gitsigns.nvim
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: make gen_help.lua emmy aware

This commit is contained in:
Lewis Russell 2023-07-10 13:50:10 +01:00 committed by Lewis Russell
parent 0daf763ed7
commit fd4d953614
5 changed files with 448 additions and 322 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

240
doc/gitsigns.txt
View File

@ -47,7 +47,6 @@ of the default settings:
linehl = false, -- Toggle with `:Gitsigns toggle_linehl`
word_diff = false, -- Toggle with `:Gitsigns toggle_word_diff`
watch_gitdir = {
interval = 1000,
follow_files = true
},
attach_to_untracked = true,
@ -99,8 +98,8 @@ setup({cfg}) *gitsigns.setup()*
{async}
Parameters: ~
{cfg} Table object containing configuration for
Gitsigns. See |gitsigns-usage| for more details.
{cfg} (table): Configuration for Gitsigns.
See |gitsigns-usage| for more details.
attach({bufnr}, {ctx}) *gitsigns.attach()*
Attach Gitsigns to the buffer.
@ -109,29 +108,29 @@ attach({bufnr}, {ctx}) *gitsigns.attach()*
{async}
Parameters: ~
{bufnr} (number): Buffer number
{ctx} (table|nil):
Git context data that may optionally be used to attach to any
buffer that represents a real git object.
• {file}: (string)
Path to the file represented by the buffer, relative to the
top-level.
• {toplevel}: (string)
Path to the top-level of the parent git repository.
• {gitdir}: (string)
Path to the git directory of the parent git repository
(typically the ".git/" directory).
• {commit}: (string)
The git revision that the file belongs to.
• {base}: (string|nil)
The git revision that the file should be compared to.
{bufnr} (integer): Buffer number
{ctx} (table|nil):
Git context data that may optionally be used to attach to any
buffer that represents a real git object.
• {file}: (string)
Path to the file represented by the buffer, relative to the
top-level.
• {toplevel}: (string)
Path to the top-level of the parent git repository.
• {gitdir}: (string)
Path to the git directory of the parent git repository
(typically the ".git/" directory).
• {commit}: (string)
The git revision that the file belongs to.
• {base}: (string|nil)
The git revision that the file should be compared to.
detach({bufnr}) *gitsigns.detach()*
Detach Gitsigns from the buffer {bufnr}. If {bufnr} is not
provided then the current buffer is used.
Parameters: ~
{bufnr} (number): Buffer number
{bufnr} (integer): Buffer number
detach_all() *gitsigns.detach_all()*
Detach Gitsigns from all buffers it is attached to.
@ -146,8 +145,9 @@ get_actions() *gitsigns.get_actions()*
Get all the available line specific actions for the current
buffer at the cursor position.
Return: ~
Dictionary of action name to function which when called
Returns: ~
(table|nil): Dictionary of action name to function which when called
performs action.
setloclist({nr}, {target}) *gitsigns.setloclist()*
@ -160,9 +160,9 @@ setloclist({nr}, {target}) *gitsigns.setloclist()*
{async}
Parameters: ~
{nr} (integer): Window number or the |window-ID|.
{nr} (integer): Window number or the |window-ID|.
`0` for the current window (default).
{target} (integer or string): See |gitsigns.setqflist()|.
{target} (integer|string): See |gitsigns.setqflist()|.
setqflist({target}, {opts}) *gitsigns.setqflist()*
Populate the quickfix list with hunks. Automatically opens the
@ -172,7 +172,7 @@ setqflist({target}, {opts}) *gitsigns.setqflist()*
{async}
Parameters: ~
{target} (integer or string):
{target} (integer|string):
Specifies which files hunks are collected from.
Possible values.
• [integer]: The buffer with the matching buffer
@ -181,8 +181,7 @@ setqflist({target}, {opts}) *gitsigns.setqflist()*
• `"all"`: All modified files for each git
directory of all attached buffers in addition
to the current working directory.
{opts} (table|nil):
Additional options:
{opts} (table|nil): Additional options:
• {use_location_list}: (boolean)
Populate the location list instead of the
quickfix list. Default to `false`.
@ -222,19 +221,6 @@ diffthis({base}, {opts}) *gitsigns.diffthis()*
If {base} is the index, then the opened buffer is editable and
any written changes will update the index accordingly.
Parameters: ~
{base} (string|nil): Revision to diff against. Defaults
to index.
{opts} (table|nil):
Additional options:
• {vertical}: {boolean}. Split window vertically. Defaults to
config.diff_opts.vertical. If running via command line, then
this is taken from the command modifiers.
• {split}: {string}. One of: 'aboveleft', 'belowright',
'botright', 'rightbelow', 'leftabove', 'topleft'. Defaults to
'aboveleft'. If running via command line, then this is taken
from the command modifiers.
Examples: >
" Diff against the index
:Gitsigns diffthis
@ -249,6 +235,17 @@ diffthis({base}, {opts}) *gitsigns.diffthis()*
Attributes: ~
{async}
Parameters: ~
{base} (string|nil): Revision to diff against. Defaults to index.
{opts} (table|nil): Additional options:
• {vertical}: {boolean}. Split window vertically. Defaults to
config.diff_opts.vertical. If running via command line, then
this is taken from the command modifiers.
• {split}: {string}. One of: 'aboveleft', 'belowright',
'botright', 'rightbelow', 'leftabove', 'topleft'. Defaults to
'aboveleft'. If running via command line, then this is taken
from the command modifiers.
reset_base({global}) *gitsigns.reset_base()*
Reset the base revision to diff against back to the
index.
@ -264,10 +261,6 @@ change_base({base}, {global}) *gitsigns.change_base()*
Attributes: ~
{async}
Parameters:~
{base} string|nil The object/revision to diff against.
{global} boolean|nil Change the base of all buffers.
Examples: >
" Change base to 1 commit behind head
:lua require('gitsigns').change_base('HEAD~1')
@ -290,43 +283,47 @@ change_base({base}, {global}) *gitsigns.change_base()*
For a more complete list of ways to specify bases, see
|gitsigns-revision|.
Parameters: ~
{base} (string|nil): The object/revision to diff against.
{global} (boolean|nil): Change the base of all buffers.
blame_line({opts}) *gitsigns.blame_line()*
Run git blame on the current line and show the results in a
floating window. If already open, calling this will cause the
window to get focus.
Parameters: ~
{opts} (table|nil):
Additional options:
• {full}: (boolean)
Display full commit message with hunk.
• {ignore_whitespace}: (boolean)
Ignore whitespace when running blame.
Attributes: ~
{async}
Parameters: ~
{opts} (table|nil): Additional options:
• {full}: (boolean)
Display full commit message with hunk.
• {ignore_whitespace}: (boolean)
Ignore whitespace when running blame.
get_hunks({bufnr}) *gitsigns.get_hunks()*
Get hunk array for specified buffer.
Parameters: ~
{bufnr} integer: Buffer number, if not provided (or 0)
{bufnr} (integer): Buffer number, if not provided (or 0)
will use current buffer.
Return: ~
Array of hunk objects. Each hunk object has keys:
• `"type"`: String with possible values: "add", "change",
"delete"
• `"head"`: Header that appears in the unified diff
output.
• `"lines"`: Line contents of the hunks prefixed with
either `"-"` or `"+"`.
• `"removed"`: Sub-table with fields:
• `"start"`: Line number (1-based)
• `"count"`: Line count
• `"added"`: Sub-table with fields:
• `"start"`: Line number (1-based)
• `"count"`: Line count
Returns: ~
(table|nil): Array of hunk objects.
Each hunk object has keys:
• `"type"`: String with possible values: "add", "change",
"delete"
• `"head"`: Header that appears in the unified diff
output.
• `"lines"`: Line contents of the hunks prefixed with
either `"-"` or `"+"`.
• `"removed"`: Sub-table with fields:
• `"start"`: Line number (1-based)
• `"count"`: Line count
• `"added"`: Sub-table with fields:
• `"start"`: Line number (1-based)
• `"count"`: Line count
select_hunk() *gitsigns.select_hunk()*
Select the hunk under the cursor.
@ -353,23 +350,23 @@ next_hunk({opts}) *gitsigns.next_hunk()*
at the next hunk.
Parameters: ~
{opts} table|nil Configuration table. Keys:
• {wrap}: (boolean)
Whether to loop around file or not. Defaults
to the value 'wrapscan'
• {navigation_message}: (boolean)
Whether to show navigation messages or not.
Looks at 'shortmess' for default behaviour.
• {foldopen}: (boolean)
Expand folds when navigating to a hunk which is
inside a fold. Defaults to `true` if 'foldopen'
contains `search`.
• {preview}: (boolean)
Automatically open preview_hunk() upon navigating
to a hunk.
• {greedy}: (boolean)
Only navigate between non-contiguous hunks. Only useful if
'diff_opts' contains `linematch`. Defaults to `true`.
{opts} (table|nil): Configuration table. Keys:
• {wrap}: (boolean)
Whether to loop around file or not. Defaults
to the value 'wrapscan'
• {navigation_message}: (boolean)
Whether to show navigation messages or not.
Looks at 'shortmess' for default behaviour.
• {foldopen}: (boolean)
Expand folds when navigating to a hunk which is
inside a fold. Defaults to `true` if 'foldopen'
contains `search`.
• {preview}: (boolean)
Automatically open preview_hunk() upon navigating
to a hunk.
• {greedy}: (boolean)
Only navigate between non-contiguous hunks. Only useful if
'diff_opts' contains `linematch`. Defaults to `true`.
reset_buffer_index() *gitsigns.reset_buffer_index()*
Unstage all hunks for current buffer in the index. Note:
@ -404,17 +401,16 @@ reset_hunk({range}, {opts}) *gitsigns.reset_hunk()*
meaning if a range only includes a portion of a particular
hunk, only the lines within the range will be reset.
Parameters:~
{range} table|nil List-like table of two integers making
Parameters: ~
{range} (table|nil): List-like table of two integers making
up the line range from which you want to reset the hunks.
If running via command line, then this is taken from the
command modifiers.
{opts} table|nil Additional options:
{opts} (table|nil): Additional options:
• {greedy}: (boolean)
Stage all contiguous hunks. Only useful if 'diff_opts'
contains `linematch`. Defaults to `true`.
stage_hunk({range}, {opts}) *gitsigns.stage_hunk()*
Stage the hunk at the cursor position, or all lines in the
given range. If {range} is provided, all lines in the given
@ -425,76 +421,76 @@ stage_hunk({range}, {opts}) *gitsigns.stage_hunk()*
Attributes: ~
{async}
Parameters:~
{range} table|nil List-like table of two integers making
Parameters: ~
{range} (table|nil): List-like table of two integers making
up the line range from which you want to stage the hunks.
If running via command line, then this is taken from the
command modifiers.
{opts} table|nil Additional options:
{opts} (table|nil): Additional options:
• {greedy}: (boolean)
Stage all contiguous hunks. Only useful if 'diff_opts'
contains `linematch`. Defaults to `true`.
toggle_deleted({value}) *gitsigns.toggle_deleted()*
Toggle |gitsigns-config-show_deleted|
Parameters:~
{value} boolean|nil Value to set toggle. If `nil`
the toggle value is inverted.
Parameters: ~
{value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted.
Returns:~
Current value of |gitsigns-config-show_deleted|
Returns: ~
(boolean): Current value of |gitsigns-config-show_deleted|
toggle_current_line_blame({value}) *gitsigns.toggle_current_line_blame()*
Toggle |gitsigns-config-current_line_blame|
Parameters:~
{value} boolean|nil Value to set toggle. If `nil`
the toggle value is inverted.
Parameters: ~
{value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted.
Returns:~
Current value of |gitsigns-config-current_line_blame|
Returns: ~
(boolean): Current value of |gitsigns-config-current_line_blame|
toggle_word_diff({value}) *gitsigns.toggle_word_diff()*
Toggle |gitsigns-config-word_diff|
Parameters:~
{value} boolean|nil Value to set toggle. If `nil`
the toggle value is inverted.
Parameters: ~
{value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted.
Returns:~
Current value of |gitsigns-config-word_diff|
Returns: ~
(boolean): Current value of |gitsigns-config-word_diff|
toggle_linehl({value}) *gitsigns.toggle_linehl()*
Toggle |gitsigns-config-linehl|
Parameters:~
{value} boolean|nil Value to set toggle. If `nil`
the toggle value is inverted.
Parameters: ~
{value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted.
Returns:~
Current value of |gitsigns-config-linehl|
Returns: ~
(boolean): Current value of |gitsigns-config-linehl|
toggle_numhl({value}) *gitsigns.toggle_numhl()*
Toggle |gitsigns-config-numhl|
Parameters:~
{value} boolean|nil Value to set toggle. If `nil`
the toggle value is inverted.
Parameters: ~
{value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted.
Returns:~
Current value of |gitsigns-config-numhl|
Returns: ~
(boolean): Current value of |gitsigns-config-numhl|
toggle_signs({value}) *gitsigns.toggle_signs()*
Toggle |gitsigns-config-signbooleancolumn|
Parameters:~
{value} boolean|nil Value to set toggle. If `nil`
the toggle value is inverted.
Parameters: ~
{value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted.
Returns:~
Current value of |gitsigns-config-signcolumn|
Returns: ~
(boolean): Current value of |gitsigns-config-signcolumn|
==============================================================================

258
gen_help.lua
View File

@ -5,20 +5,13 @@ exec nvim -l "$0" "$@"
-- Simple script to update the help doc by reading the config schema.
local inspect = vim.inspect
local list_extend = vim.list_extend
local startswith = vim.startswith
local config = require('lua.gitsigns.config')
function table.slice(tbl, first, last, step)
local sliced = {}
for i = first or 1, last or #tbl, step or 1 do
sliced[#sliced+1] = tbl[i]
end
return sliced
end
local function startswith(str, start)
return str.sub(str, 1, string.len(start)) == start
end
--- @param path string
--- @return string
local function read_file(path)
local f = assert(io.open(path, 'r'))
local t = f:read("*all")
@ -163,42 +156,209 @@ local function parse_func_header(line)
)
end
--- @param path string
--- @return string
local function gen_functions_doc_from_file(path)
local i = read_file(path):gmatch("([^\n]*)\n?")
--- @param x string
--- @return string? name
--- @return string? type
--- @return string? description
local function parse_param(x)
local name, ty, des = x:match('([^ ]+) +([^ ]+) *(.*)')
return name, ty, des
end
local res = {}
local blocks = {}
local block = {''}
local in_block = false
for l in i do
local l1 = l:match('^%-%-%- ?(.*)')
if l1 then
in_block = true
if l1 ~= '' and l1 ~= '<' then
l1 = ' '..l1
end
block[#block+1] = l1
else
if in_block then
-- First line after block
local ok, header = pcall(parse_func_header, l)
if ok then
block[1] = header
blocks[#blocks+1] = block
end
block = {''}
end
in_block = false
--- @param x string[]
--- @return string[]
local function trim_lines(x)
local min_pad --- @type integer?
for _, e in ipairs(x) do
local _, i = e:find('^ *')
if not min_pad or min_pad > i then
min_pad = i
end
end
local r = {} --- @type string[]
for _, e in ipairs(x) do
r[#r+1] = e:sub(min_pad + 1)
end
return r
end
--- @param name string
--- @param ty string
--- @param desc string[]
--- @param name_pad? integer
--- @return string[]
local function render_param_or_return(name, ty, desc, name_pad)
name_pad = name_pad and (name_pad + 3) or 0
local name_str --- @type string
if name == ':' then
name_str = ''
else
local nf = '%-'..tostring(name_pad)..'s'
name_str = nf:format(string.format('{%s} ', name))
end
if #desc == 0 then
return { string.format(' %s(%s)', name_str, ty) }
end
local r = {} --- @type string[]
local desc1 = desc[1] == '' and '' or ' '..desc[1]
r[#r+1] = string.format(' %s(%s): %s', name_str, ty, desc1)
local remain_desc = trim_lines(vim.list_slice(desc, 2))
for _, d in ipairs(remain_desc) do
r[#r+1] = ' '..string.rep(' ', name_pad)..d
end
return r
end
--- @param x string[]
--- @param amount integer
--- @return string[]
local function pad(x, amount)
local pad_str = string.rep(' ', amount)
local r = {} --- @type string[]
for _, e in ipairs(x) do
r[#r+1] = pad_str..e
end
return r
end
--- @param state EmmyState
--- @param doc_comment string
--- @param desc string[]
--- @param params {[1]: string, [2]: string, [3]: string[]}[]
--- @param returns {[1]: string, [2]: string, [3]: string[]}[]
--- @return EmmyState
local function process_doc_comment(state, doc_comment, desc, params, returns)
if state == 'none' then
state = 'in_block'
end
local emmy_type, emmy_str = doc_comment:match(' ?@([a-z]+) (.*)')
if emmy_type == 'param' then
local name, ty, pdesc = parse_param(emmy_str)
params[#params+1] = {name, ty, { pdesc }}
return 'in_param'
end
if emmy_type == 'return' then
local ty, name, rdesc = parse_param(emmy_str)
returns[#returns+1] = {name, ty, { rdesc }}
return 'in_return'
end
if state == 'in_param' then
-- Consume any remaining doc document lines as the description for the
-- last parameter
local lastdes = params[#params][3]
lastdes[#lastdes+1] = doc_comment
elseif state == 'in_return' then
-- Consume any remaining doc document lines as the description for the
-- last return
local lastdes = returns[#returns][3]
lastdes[#lastdes+1] = doc_comment
else
if doc_comment ~= '' and doc_comment ~= '<' then
doc_comment = string.rep(' ', 16)..doc_comment
end
desc[#desc+1] = doc_comment
end
return state
end
--- @param header string
--- @param block string[]
--- @param params {[1]: string, [2]: string, [3]: string[]}[]
--- @param returns {[1]: string, [2]: string, [3]: string[]}[]
--- @return string[]
local function render_block(header, block, params, returns)
local res = { header }
list_extend(res, block)
-- filter arguments beginning with '_'
params = vim.tbl_filter(
--- @param v {[1]: string, [2]: string, [3]: string[]}
--- @return boolean
function(v)
return not startswith(v[1], '_')
end,
params
)
if #params > 0 then
local param_block = {'Parameters: ~'}
local name_pad = 0
for _, v in ipairs(params) do
if #v[1] > name_pad then
name_pad = #v[1]
end
end
for _, v in ipairs(params) do
local name, ty, desc = v[1], v[2], v[3]
list_extend(param_block, render_param_or_return(name, ty, desc, name_pad))
end
list_extend(res, pad(param_block, 16))
end
if #returns > 0 then
res[#res+1] = ''
local param_block = {'Returns: ~'}
for _, v in ipairs(returns) do
local name, ty, desc = v[1], v[2], v[3]
list_extend(param_block, render_param_or_return(name, ty, desc))
end
list_extend(res, pad(param_block, 16))
end
return res
end
--- @param path string
--- @return string
local function gen_functions_doc_from_file(path)
local i = read_file(path):gmatch("([^\n]*)\n?") --- @type Iterator[string]
local blocks = {} --- @type string[][]
--- @alias EmmyState 'none'|'in_block'|'in_param'|'in_return'
local state = 'none' --- @type EmmyState
local desc = {} --- @type string[]
local params = {} --- @type {[1]: string, [2]: string, [3]: string[]}[]
local returns = {} --- @type {[1]: string, [2]: string, [3]: string[]}[]
for l in i do
local doc_comment = l:match('^%-%-%- ?(.*)') --- @type string?
if doc_comment then
state = process_doc_comment(state, doc_comment, desc, params, returns)
elseif state ~= 'none' then
-- First line after block
local ok, header = pcall(parse_func_header, l)
if ok then
blocks[#blocks+1] = render_block(header, desc, params, returns)
end
state = 'none'
desc = {}
params = {}
returns = {}
end
end
local res = {} --- @type string[]
for j = #blocks, 1, -1 do
local b = blocks[j]
for k = 1, #b do
res[#res+1] = b[k]
res[#res+1] = b[k]:match('^ *$') and '' or b[k]
end
res[#res+1] = ''
end
@ -254,19 +414,21 @@ end
--- @return string
local function get_setup_from_readme()
local i = read_file('README.md'):gmatch("([^\n]*)\n?")
local readme = read_file('README.md'):gmatch("([^\n]*)\n?") --- @type Iterator
local res = {} --- @type string[]
local function append(line)
res[#res+1] = line ~= '' and ' '..line or ''
end
for l in i do
for l in readme do
if l:match("require%('gitsigns'%).setup {") then
append(l)
break
end
end
for l in i do
for l in readme do
append(l)
if l == '}' then
break
@ -276,6 +438,8 @@ local function get_setup_from_readme()
return table.concat(res, '\n')
end
--- @param marker string
--- @return string|fun():string
local function get_marker_text(marker)
return ({
VERSION = '0.7-dev',
@ -293,11 +457,11 @@ local function get_marker_text(marker)
end
local function main()
local i = read_file('etc/doc_template.txt'):gmatch("([^\n]*)\n?")
local template = read_file('etc/doc_template.txt'):gmatch("([^\n]*)\n?") --- @type Iterator
local out = io.open('doc/gitsigns.txt', 'w')
local out = assert(io.open('doc/gitsigns.txt', 'w'))
for l in i do
for l in template do
local marker = l:match('{{(.*)}}')
if marker then
local sub = get_marker_text(marker)

5
lua/gitsigns.lua
View File

@ -154,9 +154,8 @@ end
--- Attributes: ~
--- {async}
---
--- Parameters: ~
--- {cfg} Table object containing configuration for
--- Gitsigns. See |gitsigns-usage| for more details.
--- @param cfg table Configuration for Gitsigns.
--- See |gitsigns-usage| for more details.
M.setup = void(function(cfg)
gs_config.build(cfg)

228
lua/gitsigns/actions.lua
View File

@ -48,12 +48,9 @@ end
--- Toggle |gitsigns-config-signbooleancolumn|
---
--- Parameters:~
--- {value} boolean|nil Value to set toggle. If `nil`
--- @param value boolean|nil Value to set toggle. If `nil`
--- the toggle value is inverted.
---
--- Returns:~
--- Current value of |gitsigns-config-signcolumn|
--- @return boolean : Current value of |gitsigns-config-signcolumn|
M.toggle_signs = function(value)
if value ~= nil then
config.signcolumn = value
@ -66,12 +63,10 @@ end
--- Toggle |gitsigns-config-numhl|
---
--- Parameters:~
--- {value} boolean|nil Value to set toggle. If `nil`
--- @param value boolean|nil Value to set toggle. If `nil`
--- the toggle value is inverted.
---
--- Returns:~
--- Current value of |gitsigns-config-numhl|
--- @return boolean : Current value of |gitsigns-config-numhl|
M.toggle_numhl = function(value)
if value ~= nil then
config.numhl = value
@ -84,12 +79,9 @@ end
--- Toggle |gitsigns-config-linehl|
---
--- Parameters:~
--- {value} boolean|nil Value to set toggle. If `nil`
--- @param value boolean|nil Value to set toggle. If `nil`
--- the toggle value is inverted.
---
--- Returns:~
--- Current value of |gitsigns-config-linehl|
--- @return boolean : Current value of |gitsigns-config-linehl|
M.toggle_linehl = function(value)
if value ~= nil then
config.linehl = value
@ -102,12 +94,9 @@ end
--- Toggle |gitsigns-config-word_diff|
---
--- Parameters:~
--- {value} boolean|nil Value to set toggle. If `nil`
--- @param value boolean|nil Value to set toggle. If `nil`
--- the toggle value is inverted.
---
--- Returns:~
--- Current value of |gitsigns-config-word_diff|
--- @return boolean : Current value of |gitsigns-config-word_diff|
M.toggle_word_diff = function(value)
if value ~= nil then
config.word_diff = value
@ -121,12 +110,9 @@ end
--- Toggle |gitsigns-config-current_line_blame|
---
--- Parameters:~
--- {value} boolean|nil Value to set toggle. If `nil`
--- @param value boolean|nil Value to set toggle. If `nil`
--- the toggle value is inverted.
---
--- Returns:~
--- Current value of |gitsigns-config-current_line_blame|
--- @return boolean : Current value of |gitsigns-config-current_line_blame|
M.toggle_current_line_blame = function(value)
if value ~= nil then
config.current_line_blame = value
@ -139,12 +125,9 @@ end
--- Toggle |gitsigns-config-show_deleted|
---
--- Parameters:~
--- {value} boolean|nil Value to set toggle. If `nil`
--- @param value boolean|nil Value to set toggle. If `nil`
--- the toggle value is inverted.
---
--- Returns:~
--- Current value of |gitsigns-config-show_deleted|
--- @return boolean : Current value of |gitsigns-config-show_deleted|
M.toggle_deleted = function(value)
if value ~= nil then
config.show_deleted = value
@ -251,16 +234,14 @@ end
--- Attributes: ~
--- {async}
---
--- Parameters:~
--- {range} table|nil List-like table of two integers making
--- @param range table|nil List-like table of two integers making
--- up the line range from which you want to stage the hunks.
--- If running via command line, then this is taken from the
--- command modifiers.
--- {opts} table|nil Additional options:
--- @param opts table|nil Additional options:
--- • {greedy}: (boolean)
--- Stage all contiguous hunks. Only useful if 'diff_opts'
--- contains `linematch`. Defaults to `true`.
---
M.stage_hunk = mk_repeatable(void(function(range, opts)
opts = opts or {}
local bufnr = current_buf()
@ -304,16 +285,14 @@ end
--- meaning if a range only includes a portion of a particular
--- hunk, only the lines within the range will be reset.
---
--- Parameters:~
--- {range} table|nil List-like table of two integers making
--- up the line range from which you want to reset the hunks.
--- If running via command line, then this is taken from the
--- command modifiers.
--- {opts} table|nil Additional options:
--- • {greedy}: (boolean)
--- Stage all contiguous hunks. Only useful if 'diff_opts'
--- contains `linematch`. Defaults to `true`.
---
--- @param range table|nil List-like table of two integers making
--- up the line range from which you want to reset the hunks.
--- If running via command line, then this is taken from the
--- command modifiers.
--- @param opts table|nil Additional options:
--- • {greedy}: (boolean)
--- Stage all contiguous hunks. Only useful if 'diff_opts'
--- contains `linematch`. Defaults to `true`.
M.reset_hunk = mk_repeatable(void(function(range, opts)
opts = opts or {}
local bufnr = current_buf()
@ -540,24 +519,23 @@ end)
--- (popup or inline) was previously opened, it will be re-opened
--- at the next hunk.
---
--- Parameters: ~
--- {opts} table|nil Configuration table. Keys:
--- • {wrap}: (boolean)
--- Whether to loop around file or not. Defaults
--- to the value 'wrapscan'
--- • {navigation_message}: (boolean)
--- Whether to show navigation messages or not.
--- Looks at 'shortmess' for default behaviour.
--- • {foldopen}: (boolean)
--- Expand folds when navigating to a hunk which is
--- inside a fold. Defaults to `true` if 'foldopen'
--- contains `search`.
--- • {preview}: (boolean)
--- Automatically open preview_hunk() upon navigating
--- to a hunk.
--- • {greedy}: (boolean)
--- Only navigate between non-contiguous hunks. Only useful if
--- 'diff_opts' contains `linematch`. Defaults to `true`.
--- @param opts table|nil Configuration table. Keys:
--- • {wrap}: (boolean)
--- Whether to loop around file or not. Defaults
--- to the value 'wrapscan'
--- • {navigation_message}: (boolean)
--- Whether to show navigation messages or not.
--- Looks at 'shortmess' for default behaviour.
--- • {foldopen}: (boolean)
--- Expand folds when navigating to a hunk which is
--- inside a fold. Defaults to `true` if 'foldopen'
--- contains `search`.
--- • {preview}: (boolean)
--- Automatically open preview_hunk() upon navigating
--- to a hunk.
--- • {greedy}: (boolean)
--- Only navigate between non-contiguous hunks. Only useful if
--- 'diff_opts' contains `linematch`. Defaults to `true`.
M.next_hunk = function(opts)
opts = opts or {}
opts.forwards = true
@ -759,24 +737,22 @@ end
--- Get hunk array for specified buffer.
---
--- Parameters: ~
--- {bufnr} integer: Buffer number, if not provided (or 0)
--- @param bufnr integer Buffer number, if not provided (or 0)
--- will use current buffer.
---
--- Return: ~
--- Array of hunk objects. Each hunk object has keys:
--- • `"type"`: String with possible values: "add", "change",
--- "delete"
--- • `"head"`: Header that appears in the unified diff
--- output.
--- • `"lines"`: Line contents of the hunks prefixed with
--- either `"-"` or `"+"`.
--- • `"removed"`: Sub-table with fields:
--- • `"start"`: Line number (1-based)
--- • `"count"`: Line count
--- • `"added"`: Sub-table with fields:
--- • `"start"`: Line number (1-based)
--- • `"count"`: Line count
--- @return table|nil : Array of hunk objects.
--- Each hunk object has keys:
--- • `"type"`: String with possible values: "add", "change",
--- "delete"
--- • `"head"`: Header that appears in the unified diff
--- output.
--- • `"lines"`: Line contents of the hunks prefixed with
--- either `"-"` or `"+"`.
--- • `"removed"`: Sub-table with fields:
--- • `"start"`: Line number (1-based)
--- • `"count"`: Line count
--- • `"added"`: Sub-table with fields:
--- • `"start"`: Line number (1-based)
--- • `"count"`: Line count
M.get_hunks = function(bufnr)
bufnr = bufnr or current_buf()
if not cache[bufnr] then
@ -844,16 +820,14 @@ end
--- floating window. If already open, calling this will cause the
--- window to get focus.
---
--- Parameters: ~
--- {opts} (table|nil):
--- Additional options:
--- • {full}: (boolean)
--- Display full commit message with hunk.
--- • {ignore_whitespace}: (boolean)
--- Ignore whitespace when running blame.
---
--- Attributes: ~
--- {async}
---
--- @param opts table|nil Additional options:
--- • {full}: (boolean)
--- Display full commit message with hunk.
--- • {ignore_whitespace}: (boolean)
--- Ignore whitespace when running blame.
M.blame_line = void(function(opts)
if popup.focus_open('blame') then
return
@ -917,10 +891,6 @@ end
--- Attributes: ~
--- {async}
---
--- Parameters:~
--- {base} string|nil The object/revision to diff against.
--- {global} boolean|nil Change the base of all buffers.
---
--- Examples: >
--- " Change base to 1 commit behind head
--- :lua require('gitsigns').change_base('HEAD~1')
@ -942,6 +912,9 @@ end
---
--- For a more complete list of ways to specify bases, see
--- |gitsigns-revision|.
---
--- @param base string|nil The object/revision to diff against.
--- @param global boolean|nil Change the base of all buffers.
M.change_base = void(function(base, global)
base = util.calc_base(base)
@ -986,19 +959,6 @@ end
--- If {base} is the index, then the opened buffer is editable and
--- any written changes will update the index accordingly.
---
--- Parameters: ~
--- {base} (string|nil): Revision to diff against. Defaults
--- to index.
--- {opts} (table|nil):
--- Additional options:
--- • {vertical}: {boolean}. Split window vertically. Defaults to
--- config.diff_opts.vertical. If running via command line, then
--- this is taken from the command modifiers.
--- • {split}: {string}. One of: 'aboveleft', 'belowright',
--- 'botright', 'rightbelow', 'leftabove', 'topleft'. Defaults to
--- 'aboveleft'. If running via command line, then this is taken
--- from the command modifiers.
---
--- Examples: >
--- " Diff against the index
--- :Gitsigns diffthis
@ -1012,6 +972,16 @@ end
---
--- Attributes: ~
--- {async}
---
--- @param base string|nil Revision to diff against. Defaults to index.
--- @param opts table|nil Additional options:
--- • {vertical}: {boolean}. Split window vertically. Defaults to
--- config.diff_opts.vertical. If running via command line, then
--- this is taken from the command modifiers.
--- • {split}: {string}. One of: 'aboveleft', 'belowright',
--- 'botright', 'rightbelow', 'leftabove', 'topleft'. Defaults to
--- 'aboveleft'. If running via command line, then this is taken
--- from the command modifiers.
M.diffthis = function(base, opts)
-- TODO(lewis6991): can't pass numbers as strings from the command line
if base ~= nil then
@ -1147,28 +1117,26 @@ end
--- Attributes: ~
--- {async}
---
--- Parameters: ~
--- {target} (integer or string):
--- Specifies which files hunks are collected from.
--- Possible values.
--- • [integer]: The buffer with the matching buffer
--- number. `0` for current buffer (default).
--- • `"attached"`: All attached buffers.
--- • `"all"`: All modified files for each git
--- directory of all attached buffers in addition
--- to the current working directory.
--- {opts} (table|nil):
--- Additional options:
--- • {use_location_list}: (boolean)
--- Populate the location list instead of the
--- quickfix list. Default to `false`.
--- • {nr}: (integer)
--- Window number or ID when using location list.
--- Expand folds when navigating to a hunk which is
--- inside a fold. Defaults to `0`.
--- • {open}: (boolean)
--- Open the quickfix/location list viewer.
--- Defaults to `true`.
--- @param target integer|string
--- Specifies which files hunks are collected from.
--- Possible values.
--- • [integer]: The buffer with the matching buffer
--- number. `0` for current buffer (default).
--- • `"attached"`: All attached buffers.
--- • `"all"`: All modified files for each git
--- directory of all attached buffers in addition
--- to the current working directory.
--- @param opts table|nil Additional options:
--- • {use_location_list}: (boolean)
--- Populate the location list instead of the
--- quickfix list. Default to `false`.
--- • {nr}: (integer)
--- Window number or ID when using location list.
--- Expand folds when navigating to a hunk which is
--- inside a fold. Defaults to `0`.
--- • {open}: (boolean)
--- Open the quickfix/location list viewer.
--- Defaults to `true`.
M.setqflist = void(function(target, opts)
opts = opts or {}
if opts.open == nil then
@ -1209,10 +1177,9 @@ end)
--- Attributes: ~
--- {async}
---
--- Parameters: ~
--- {nr} (integer): Window number or the |window-ID|.
--- `0` for the current window (default).
--- {target} (integer or string): See |gitsigns.setqflist()|.
--- @param nr integer Window number or the |window-ID|.
--- `0` for the current window (default).
--- @param target integer|string See |gitsigns.setqflist()|.
M.setloclist = function(nr, target)
M.setqflist(target, {
nr = nr,
@ -1223,8 +1190,7 @@ end
--- Get all the available line specific actions for the current
--- buffer at the cursor position.
---
--- Return: ~
--- Dictionary of action name to function which when called
--- @return table|nil : Dictionary of action name to function which when called
--- performs action.
M.get_actions = function()
local bufnr = current_buf()

39
lua/gitsigns/attach.lua
View File

@ -105,6 +105,7 @@ local function on_lines(_, bufnr, _, first, last_orig, last_new, byte_count)
return manager.on_lines(bufnr, first, last_orig, last_new)
end
--- @param _ 'reload'
--- @param bufnr integer
local function on_reload(_, bufnr)
local __FUNC__ = 'on_reload'
@ -112,6 +113,7 @@ local function on_reload(_, bufnr)
manager.update_debounced(bufnr)
end
--- @param _ 'detach'
--- @param bufnr integer
local function on_detach(_, bufnr)
M.detach(bufnr, true)
@ -371,8 +373,8 @@ end
--- Detach Gitsigns from the buffer {bufnr}. If {bufnr} is not
--- provided then the current buffer is used.
---
--- Parameters: ~
--- {bufnr} (number): Buffer number
--- @param bufnr integer Buffer number
--- @param _keep_signs? boolean
function M.detach(bufnr, _keep_signs)
-- When this is called interactively (with no arguments) we want to remove all
-- the signs, however if called via a detach event (due to nvim_buf_attach)
@ -401,23 +403,22 @@ end
--- Attributes: ~
--- {async}
---
--- Parameters: ~
--- {bufnr} (number): Buffer number
--- {ctx} (table|nil):
--- Git context data that may optionally be used to attach to any
--- buffer that represents a real git object.
--- • {file}: (string)
--- Path to the file represented by the buffer, relative to the
--- top-level.
--- • {toplevel}: (string)
--- Path to the top-level of the parent git repository.
--- • {gitdir}: (string)
--- Path to the git directory of the parent git repository
--- (typically the ".git/" directory).
--- • {commit}: (string)
--- The git revision that the file belongs to.
--- • {base}: (string|nil)
--- The git revision that the file should be compared to.
--- @param bufnr integer Buffer number
--- @param ctx table|nil
--- Git context data that may optionally be used to attach to any
--- buffer that represents a real git object.
--- • {file}: (string)
--- Path to the file represented by the buffer, relative to the
--- top-level.
--- • {toplevel}: (string)
--- Path to the top-level of the parent git repository.
--- • {gitdir}: (string)
--- Path to the git directory of the parent git repository
--- (typically the ".git/" directory).
--- • {commit}: (string)
--- The git revision that the file belongs to.
--- • {base}: (string|nil)
--- The git revision that the file should be compared to.
M.attach = void(function(bufnr, ctx, _trigger)
attach_throttled(bufnr or api.nvim_get_current_buf(), ctx, _trigger)
end)