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` linehl = false, -- Toggle with `:Gitsigns toggle_linehl`
word_diff = false, -- Toggle with `:Gitsigns toggle_word_diff` word_diff = false, -- Toggle with `:Gitsigns toggle_word_diff`
watch_gitdir = { watch_gitdir = {
interval = 1000,
follow_files = true follow_files = true
}, },
attach_to_untracked = true, attach_to_untracked = true,
@ -99,8 +98,8 @@ setup({cfg}) *gitsigns.setup()*
{async} {async}
Parameters: ~ Parameters: ~
{cfg} Table object containing configuration for {cfg} (table): Configuration for Gitsigns.
Gitsigns. See |gitsigns-usage| for more details. See |gitsigns-usage| for more details.
attach({bufnr}, {ctx}) *gitsigns.attach()* attach({bufnr}, {ctx}) *gitsigns.attach()*
Attach Gitsigns to the buffer. Attach Gitsigns to the buffer.
@ -109,29 +108,29 @@ attach({bufnr}, {ctx}) *gitsigns.attach()*
{async} {async}
Parameters: ~ Parameters: ~
{bufnr} (number): Buffer number {bufnr} (integer): Buffer number
{ctx} (table|nil): {ctx} (table|nil):
Git context data that may optionally be used to attach to any Git context data that may optionally be used to attach to any
buffer that represents a real git object. buffer that represents a real git object.
• {file}: (string) • {file}: (string)
Path to the file represented by the buffer, relative to the Path to the file represented by the buffer, relative to the
top-level. top-level.
• {toplevel}: (string) • {toplevel}: (string)
Path to the top-level of the parent git repository. Path to the top-level of the parent git repository.
• {gitdir}: (string) • {gitdir}: (string)
Path to the git directory of the parent git repository Path to the git directory of the parent git repository
(typically the ".git/" directory). (typically the ".git/" directory).
• {commit}: (string) • {commit}: (string)
The git revision that the file belongs to. The git revision that the file belongs to.
• {base}: (string|nil) • {base}: (string|nil)
The git revision that the file should be compared to. The git revision that the file should be compared to.
detach({bufnr}) *gitsigns.detach()* detach({bufnr}) *gitsigns.detach()*
Detach Gitsigns from the buffer {bufnr}. If {bufnr} is not Detach Gitsigns from the buffer {bufnr}. If {bufnr} is not
provided then the current buffer is used. provided then the current buffer is used.
Parameters: ~ Parameters: ~
{bufnr} (number): Buffer number {bufnr} (integer): Buffer number
detach_all() *gitsigns.detach_all()* detach_all() *gitsigns.detach_all()*
Detach Gitsigns from all buffers it is attached to. 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 Get all the available line specific actions for the current
buffer at the cursor position. 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. performs action.
setloclist({nr}, {target}) *gitsigns.setloclist()* setloclist({nr}, {target}) *gitsigns.setloclist()*
@ -160,9 +160,9 @@ setloclist({nr}, {target}) *gitsigns.setloclist()*
{async} {async}
Parameters: ~ Parameters: ~
{nr} (integer): Window number or the |window-ID|. {nr} (integer): Window number or the |window-ID|.
`0` for the current window (default). `0` for the current window (default).
{target} (integer or string): See |gitsigns.setqflist()|. {target} (integer|string): See |gitsigns.setqflist()|.
setqflist({target}, {opts}) *gitsigns.setqflist()* setqflist({target}, {opts}) *gitsigns.setqflist()*
Populate the quickfix list with hunks. Automatically opens the Populate the quickfix list with hunks. Automatically opens the
@ -172,7 +172,7 @@ setqflist({target}, {opts}) *gitsigns.setqflist()*
{async} {async}
Parameters: ~ Parameters: ~
{target} (integer or string): {target} (integer|string):
Specifies which files hunks are collected from. Specifies which files hunks are collected from.
Possible values. Possible values.
• [integer]: The buffer with the matching buffer • [integer]: The buffer with the matching buffer
@ -181,8 +181,7 @@ setqflist({target}, {opts}) *gitsigns.setqflist()*
• `"all"`: All modified files for each git • `"all"`: All modified files for each git
directory of all attached buffers in addition directory of all attached buffers in addition
to the current working directory. to the current working directory.
{opts} (table|nil): {opts} (table|nil): Additional options:
Additional options:
• {use_location_list}: (boolean) • {use_location_list}: (boolean)
Populate the location list instead of the Populate the location list instead of the
quickfix list. Default to `false`. 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 If {base} is the index, then the opened buffer is editable and
any written changes will update the index accordingly. 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: > Examples: >
" Diff against the index " Diff against the index
:Gitsigns diffthis :Gitsigns diffthis
@ -249,6 +235,17 @@ diffthis({base}, {opts}) *gitsigns.diffthis()*
Attributes: ~ Attributes: ~
{async} {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_base({global}) *gitsigns.reset_base()*
Reset the base revision to diff against back to the Reset the base revision to diff against back to the
index. index.
@ -264,10 +261,6 @@ change_base({base}, {global}) *gitsigns.change_base()*
Attributes: ~ Attributes: ~
{async} {async}
Parameters:~
{base} string|nil The object/revision to diff against.
{global} boolean|nil Change the base of all buffers.
Examples: > Examples: >
" Change base to 1 commit behind head " Change base to 1 commit behind head
:lua require('gitsigns').change_base('HEAD~1') :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 For a more complete list of ways to specify bases, see
|gitsigns-revision|. |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()* blame_line({opts}) *gitsigns.blame_line()*
Run git blame on the current line and show the results in a Run git blame on the current line and show the results in a
floating window. If already open, calling this will cause the floating window. If already open, calling this will cause the
window to get focus. 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: ~ Attributes: ~
{async} {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_hunks({bufnr}) *gitsigns.get_hunks()*
Get hunk array for specified buffer. Get hunk array for specified buffer.
Parameters: ~ Parameters: ~
{bufnr} integer: Buffer number, if not provided (or 0) {bufnr} (integer): Buffer number, if not provided (or 0)
will use current buffer. will use current buffer.
Return: ~ Returns: ~
Array of hunk objects. Each hunk object has keys: (table|nil): Array of hunk objects.
• `"type"`: String with possible values: "add", "change", Each hunk object has keys:
"delete" • `"type"`: String with possible values: "add", "change",
• `"head"`: Header that appears in the unified diff "delete"
output. • `"head"`: Header that appears in the unified diff
• `"lines"`: Line contents of the hunks prefixed with output.
either `"-"` or `"+"`. • `"lines"`: Line contents of the hunks prefixed with
• `"removed"`: Sub-table with fields: either `"-"` or `"+"`.
• `"start"`: Line number (1-based) • `"removed"`: Sub-table with fields:
• `"count"`: Line count • `"start"`: Line number (1-based)
• `"added"`: Sub-table with fields: • `"count"`: Line count
• `"start"`: Line number (1-based) • `"added"`: Sub-table with fields:
• `"count"`: Line count • `"start"`: Line number (1-based)
• `"count"`: Line count
select_hunk() *gitsigns.select_hunk()* select_hunk() *gitsigns.select_hunk()*
Select the hunk under the cursor. Select the hunk under the cursor.
@ -353,23 +350,23 @@ next_hunk({opts}) *gitsigns.next_hunk()*
at the next hunk. at the next hunk.
Parameters: ~ Parameters: ~
{opts} table|nil Configuration table. Keys: {opts} (table|nil): Configuration table. Keys:
• {wrap}: (boolean) • {wrap}: (boolean)
Whether to loop around file or not. Defaults Whether to loop around file or not. Defaults
to the value 'wrapscan' to the value 'wrapscan'
• {navigation_message}: (boolean) • {navigation_message}: (boolean)
Whether to show navigation messages or not. Whether to show navigation messages or not.
Looks at 'shortmess' for default behaviour. Looks at 'shortmess' for default behaviour.
• {foldopen}: (boolean) • {foldopen}: (boolean)
Expand folds when navigating to a hunk which is Expand folds when navigating to a hunk which is
inside a fold. Defaults to `true` if 'foldopen' inside a fold. Defaults to `true` if 'foldopen'
contains `search`. contains `search`.
• {preview}: (boolean) • {preview}: (boolean)
Automatically open preview_hunk() upon navigating Automatically open preview_hunk() upon navigating
to a hunk. to a hunk.
• {greedy}: (boolean) • {greedy}: (boolean)
Only navigate between non-contiguous hunks. Only useful if Only navigate between non-contiguous hunks. Only useful if
'diff_opts' contains `linematch`. Defaults to `true`. 'diff_opts' contains `linematch`. Defaults to `true`.
reset_buffer_index() *gitsigns.reset_buffer_index()* reset_buffer_index() *gitsigns.reset_buffer_index()*
Unstage all hunks for current buffer in the index. Note: 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 meaning if a range only includes a portion of a particular
hunk, only the lines within the range will be reset. hunk, only the lines within the range will be reset.
Parameters:~ Parameters: ~
{range} table|nil List-like table of two integers making {range} (table|nil): List-like table of two integers making
up the line range from which you want to reset the hunks. up the line range from which you want to reset the hunks.
If running via command line, then this is taken from the If running via command line, then this is taken from the
command modifiers. command modifiers.
{opts} table|nil Additional options: {opts} (table|nil): Additional options:
• {greedy}: (boolean) • {greedy}: (boolean)
Stage all contiguous hunks. Only useful if 'diff_opts' Stage all contiguous hunks. Only useful if 'diff_opts'
contains `linematch`. Defaults to `true`. contains `linematch`. Defaults to `true`.
stage_hunk({range}, {opts}) *gitsigns.stage_hunk()* stage_hunk({range}, {opts}) *gitsigns.stage_hunk()*
Stage the hunk at the cursor position, or all lines in the Stage the hunk at the cursor position, or all lines in the
given range. If {range} is provided, all lines in the given given range. If {range} is provided, all lines in the given
@ -425,76 +421,76 @@ stage_hunk({range}, {opts}) *gitsigns.stage_hunk()*
Attributes: ~ Attributes: ~
{async} {async}
Parameters:~ Parameters: ~
{range} table|nil List-like table of two integers making {range} (table|nil): List-like table of two integers making
up the line range from which you want to stage the hunks. up the line range from which you want to stage the hunks.
If running via command line, then this is taken from the If running via command line, then this is taken from the
command modifiers. command modifiers.
{opts} table|nil Additional options: {opts} (table|nil): Additional options:
• {greedy}: (boolean) • {greedy}: (boolean)
Stage all contiguous hunks. Only useful if 'diff_opts' Stage all contiguous hunks. Only useful if 'diff_opts'
contains `linematch`. Defaults to `true`. contains `linematch`. Defaults to `true`.
toggle_deleted({value}) *gitsigns.toggle_deleted()* toggle_deleted({value}) *gitsigns.toggle_deleted()*
Toggle |gitsigns-config-show_deleted| Toggle |gitsigns-config-show_deleted|
Parameters:~ Parameters: ~
{value} boolean|nil Value to set toggle. If `nil` {value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted. the toggle value is inverted.
Returns:~ Returns: ~
Current value of |gitsigns-config-show_deleted| (boolean): Current value of |gitsigns-config-show_deleted|
toggle_current_line_blame({value}) *gitsigns.toggle_current_line_blame()* toggle_current_line_blame({value}) *gitsigns.toggle_current_line_blame()*
Toggle |gitsigns-config-current_line_blame| Toggle |gitsigns-config-current_line_blame|
Parameters:~ Parameters: ~
{value} boolean|nil Value to set toggle. If `nil` {value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted. the toggle value is inverted.
Returns:~ Returns: ~
Current value of |gitsigns-config-current_line_blame| (boolean): Current value of |gitsigns-config-current_line_blame|
toggle_word_diff({value}) *gitsigns.toggle_word_diff()* toggle_word_diff({value}) *gitsigns.toggle_word_diff()*
Toggle |gitsigns-config-word_diff| Toggle |gitsigns-config-word_diff|
Parameters:~ Parameters: ~
{value} boolean|nil Value to set toggle. If `nil` {value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted. the toggle value is inverted.
Returns:~ Returns: ~
Current value of |gitsigns-config-word_diff| (boolean): Current value of |gitsigns-config-word_diff|
toggle_linehl({value}) *gitsigns.toggle_linehl()* toggle_linehl({value}) *gitsigns.toggle_linehl()*
Toggle |gitsigns-config-linehl| Toggle |gitsigns-config-linehl|
Parameters:~ Parameters: ~
{value} boolean|nil Value to set toggle. If `nil` {value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted. the toggle value is inverted.
Returns:~ Returns: ~
Current value of |gitsigns-config-linehl| (boolean): Current value of |gitsigns-config-linehl|
toggle_numhl({value}) *gitsigns.toggle_numhl()* toggle_numhl({value}) *gitsigns.toggle_numhl()*
Toggle |gitsigns-config-numhl| Toggle |gitsigns-config-numhl|
Parameters:~ Parameters: ~
{value} boolean|nil Value to set toggle. If `nil` {value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted. 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_signs({value}) *gitsigns.toggle_signs()*
Toggle |gitsigns-config-signbooleancolumn| Toggle |gitsigns-config-signbooleancolumn|
Parameters:~ Parameters: ~
{value} boolean|nil Value to set toggle. If `nil` {value} (boolean|nil): Value to set toggle. If `nil`
the toggle value is inverted. the toggle value is inverted.
Returns:~ Returns: ~
Current value of |gitsigns-config-signcolumn| (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. -- Simple script to update the help doc by reading the config schema.
local inspect = vim.inspect local inspect = vim.inspect
local list_extend = vim.list_extend
local startswith = vim.startswith
local config = require('lua.gitsigns.config') local config = require('lua.gitsigns.config')
function table.slice(tbl, first, last, step) --- @param path string
local sliced = {} --- @return string
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
local function read_file(path) local function read_file(path)
local f = assert(io.open(path, 'r')) local f = assert(io.open(path, 'r'))
local t = f:read("*all") local t = f:read("*all")
@ -163,42 +156,209 @@ local function parse_func_header(line)
) )
end end
--- @param path string --- @param x string
--- @return string --- @return string? name
local function gen_functions_doc_from_file(path) --- @return string? type
local i = read_file(path):gmatch("([^\n]*)\n?") --- @return string? description
local function parse_param(x)
local name, ty, des = x:match('([^ ]+) +([^ ]+) *(.*)')
return name, ty, des
end
local res = {} --- @param x string[]
local blocks = {} --- @return string[]
local block = {''} local function trim_lines(x)
local min_pad --- @type integer?
local in_block = false for _, e in ipairs(x) do
for l in i do local _, i = e:find('^ *')
local l1 = l:match('^%-%-%- ?(.*)') if not min_pad or min_pad > i then
if l1 then min_pad = i
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
end end
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 for j = #blocks, 1, -1 do
local b = blocks[j] local b = blocks[j]
for k = 1, #b do for k = 1, #b do
res[#res+1] = b[k] res[#res+1] = b[k]:match('^ *$') and '' or b[k]
end end
res[#res+1] = '' res[#res+1] = ''
end end
@ -254,19 +414,21 @@ end
--- @return string --- @return string
local function get_setup_from_readme() 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 res = {} --- @type string[]
local function append(line) local function append(line)
res[#res+1] = line ~= '' and ' '..line or '' res[#res+1] = line ~= '' and ' '..line or ''
end end
for l in i do
for l in readme do
if l:match("require%('gitsigns'%).setup {") then if l:match("require%('gitsigns'%).setup {") then
append(l) append(l)
break break
end end
end end
for l in i do for l in readme do
append(l) append(l)
if l == '}' then if l == '}' then
break break
@ -276,6 +438,8 @@ local function get_setup_from_readme()
return table.concat(res, '\n') return table.concat(res, '\n')
end end
--- @param marker string
--- @return string|fun():string
local function get_marker_text(marker) local function get_marker_text(marker)
return ({ return ({
VERSION = '0.7-dev', VERSION = '0.7-dev',
@ -293,11 +457,11 @@ local function get_marker_text(marker)
end end
local function main() 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('{{(.*)}}') local marker = l:match('{{(.*)}}')
if marker then if marker then
local sub = get_marker_text(marker) local sub = get_marker_text(marker)

5
lua/gitsigns.lua
View File

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

228
lua/gitsigns/actions.lua
View File

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