From bcc70280fbe68ef97e9cb42d6a130d75b936427d Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Sat, 7 Feb 2026 15:44:56 -0500 Subject: [PATCH 1/5] docs: fix vim.max_lines default in config example Problem: the vimdoc config example showed max_lines = 500 under vim, but the actual default in init.lua is 200. Solution: change the example to match the real default. --- doc/diffs.nvim.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index 42009e9..3db6db6 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -66,7 +66,7 @@ Configuration is done via `vim.g.diffs`. Set this before the plugin loads: }, vim = { enabled = false, - max_lines = 500, + max_lines = 200, }, intra = { enabled = true, From 8e0c41bf6b5903e61b40900506f95e23359328e9 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Sat, 7 Feb 2026 15:45:34 -0500 Subject: [PATCH 2/5] fix(highlight): add default flag to DiffsDiff* groups Problem: DiffsDiff* highlight groups lacked default = true, making them impossible for colorschemes to override, inconsistent with the fugitive unified diff groups which already had it. Solution: add default = true to all four DiffsDiffAdd, DiffsDiffDelete, DiffsDiffChange, and DiffsDiffText nvim_set_hl calls. --- doc/diffs.nvim.txt | 6 +++--- lua/diffs/init.lua | 12 ++++++++---- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index 3db6db6..7704b5b 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -398,9 +398,9 @@ diff-related features. ============================================================================== HIGHLIGHT GROUPS *diffs-highlights* -diffs.nvim defines custom highlight groups. Fugitive unified diff groups use -`default = true`, so colorschemes can override them. Diff mode groups are -always derived from the corresponding `Diff*` groups. +diffs.nvim defines custom highlight groups. All groups use `default = true`, +so colorschemes can override them by defining the group before the plugin +loads. All derived groups are computed by alpha-blending a source color into the `Normal` background. Line-level groups blend at 40% alpha for a subtle tint; diff --git a/lua/diffs/init.lua b/lua/diffs/init.lua index cfdfb4b..14a4c13 100644 --- a/lua/diffs/init.lua +++ b/lua/diffs/init.lua @@ -219,10 +219,14 @@ local function compute_highlight_groups() local diff_change = resolve_hl('DiffChange') local diff_text = resolve_hl('DiffText') - vim.api.nvim_set_hl(0, 'DiffsDiffAdd', { bg = diff_add.bg }) - vim.api.nvim_set_hl(0, 'DiffsDiffDelete', { fg = diff_delete.fg, bg = diff_delete.bg }) - vim.api.nvim_set_hl(0, 'DiffsDiffChange', { bg = diff_change.bg }) - vim.api.nvim_set_hl(0, 'DiffsDiffText', { bg = diff_text.bg }) + vim.api.nvim_set_hl(0, 'DiffsDiffAdd', { default = true, bg = diff_add.bg }) + vim.api.nvim_set_hl( + 0, + 'DiffsDiffDelete', + { default = true, fg = diff_delete.fg, bg = diff_delete.bg } + ) + vim.api.nvim_set_hl(0, 'DiffsDiffChange', { default = true, bg = diff_change.bg }) + vim.api.nvim_set_hl(0, 'DiffsDiffText', { default = true, bg = diff_text.bg }) end local function init() From b7477e3af24ec499cfedf5cfcf4b3db2dda24653 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Sat, 7 Feb 2026 15:46:47 -0500 Subject: [PATCH 3/5] feat(highlight): add configurable blend alpha Problem: the character-level blend intensity was hardcoded to 0.6, giving users no way to tune how strongly changed characters stand out from the line-level background. Solution: add highlights.blend_alpha config option (number, 0-1, default 0.6) with type validation and range check. --- doc/diffs.nvim.txt | 8 ++++++++ lua/diffs/init.lua | 14 ++++++++++++-- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index 7704b5b..cf03a6f 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -56,6 +56,7 @@ Configuration is done via `vim.g.diffs`. Set this before the plugin loads: highlights = { background = true, gutter = true, + blend_alpha = 0.6, context = { enabled = true, lines = 25, @@ -117,6 +118,13 @@ Configuration is done via `vim.g.diffs`. Set this before the plugin loads: Highlight line numbers with matching colors. Only visible if line numbers are enabled. + {blend_alpha} (number, default: 0.6) + Alpha value for character-level blend intensity. + Controls how strongly changed characters stand + out from the line-level background. Must be + between 0 and 1 (inclusive). Higher values + produce more vivid character-level highlights. + {context} (table, default: see below) Syntax parsing context options. See |diffs.ContextConfig| for fields. diff --git a/lua/diffs/init.lua b/lua/diffs/init.lua index 14a4c13..3397bc1 100644 --- a/lua/diffs/init.lua +++ b/lua/diffs/init.lua @@ -18,6 +18,7 @@ ---@class diffs.Highlights ---@field background boolean ---@field gutter boolean +---@field blend_alpha? number ---@field context diffs.ContextConfig ---@field treesitter diffs.TreesitterConfig ---@field vim diffs.VimConfig @@ -192,8 +193,9 @@ local function compute_highlight_groups() local blended_add = blend_color(add_bg, bg, 0.4) local blended_del = blend_color(del_bg, bg, 0.4) - local blended_add_text = blend_color(add_fg, bg, 0.6) - local blended_del_text = blend_color(del_fg, bg, 0.6) + local alpha = config.highlights.blend_alpha or 0.6 + local blended_add_text = blend_color(add_fg, bg, alpha) + local blended_del_text = blend_color(del_fg, bg, alpha) vim.api.nvim_set_hl(0, 'DiffsClear', { default = true, fg = normal.fg or 0xc0c0c0 }) vim.api.nvim_set_hl(0, 'DiffsAdd', { default = true, bg = blended_add }) @@ -248,6 +250,7 @@ local function init() vim.validate({ ['highlights.background'] = { opts.highlights.background, 'boolean', true }, ['highlights.gutter'] = { opts.highlights.gutter, 'boolean', true }, + ['highlights.blend_alpha'] = { opts.highlights.blend_alpha, 'number', true }, ['highlights.context'] = { opts.highlights.context, 'table', true }, ['highlights.treesitter'] = { opts.highlights.treesitter, 'table', true }, ['highlights.vim'] = { opts.highlights.vim, 'table', true }, @@ -348,6 +351,13 @@ local function init() then error('diffs: highlights.intra.max_lines must be >= 1') end + if + opts.highlights + and opts.highlights.blend_alpha + and (opts.highlights.blend_alpha < 0 or opts.highlights.blend_alpha > 1) + then + error('diffs: highlights.blend_alpha must be >= 0 and <= 1') + end config = vim.tbl_deep_extend('force', default_config, opts) log.set_enabled(config.debug) From a0870a789239d571856883dfea11d6854da5aa98 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Sat, 7 Feb 2026 15:47:36 -0500 Subject: [PATCH 4/5] feat(highlight): add highlights.overrides config table Problem: users had no config-level way to override computed highlight groups and had to call nvim_set_hl externally. Solution: add highlights.overrides table that maps group names to highlight definitions. Overrides are applied after all computed groups without default = true, so they always win over both computed defaults and colorscheme definitions. --- doc/diffs.nvim.txt | 18 ++++++++++++++++++ lua/diffs/init.lua | 8 ++++++++ 2 files changed, 26 insertions(+) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index cf03a6f..391ad05 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -74,6 +74,7 @@ Configuration is done via `vim.g.diffs`. Set this before the plugin loads: algorithm = 'default', max_lines = 500, }, + overrides = {}, }, fugitive = { horizontal = 'du', @@ -141,6 +142,13 @@ Configuration is done via `vim.g.diffs`. Set this before the plugin loads: Character-level (intra-line) diff highlighting. See |diffs.IntraConfig| for fields. + {overrides} (table, default: {}) + Map of highlight group names to highlight + definitions (see |nvim_set_hl()|). Applied + after all computed groups without `default`, + so overrides always win over both computed + defaults and colorscheme definitions. + *diffs.ContextConfig* Context config fields: ~ {enabled} (boolean, default: true) @@ -469,6 +477,16 @@ To customize these in your colorscheme: >lua vim.api.nvim_set_hl(0, 'DiffsAdd', { bg = '#2e4a3a' }) vim.api.nvim_set_hl(0, 'DiffsDiffDelete', { link = 'DiffDelete' }) < +Or via `highlights.overrides` in config: >lua + vim.g.diffs = { + highlights = { + overrides = { + DiffsAdd = { bg = '#2e4a3a' }, + DiffsDiffDelete = { link = 'DiffDelete' }, + }, + }, + } +< ============================================================================== HEALTH CHECK *diffs-health* diff --git a/lua/diffs/init.lua b/lua/diffs/init.lua index 3397bc1..7fb4e6d 100644 --- a/lua/diffs/init.lua +++ b/lua/diffs/init.lua @@ -19,6 +19,7 @@ ---@field background boolean ---@field gutter boolean ---@field blend_alpha? number +---@field overrides? table ---@field context diffs.ContextConfig ---@field treesitter diffs.TreesitterConfig ---@field vim diffs.VimConfig @@ -229,6 +230,12 @@ local function compute_highlight_groups() ) vim.api.nvim_set_hl(0, 'DiffsDiffChange', { default = true, bg = diff_change.bg }) vim.api.nvim_set_hl(0, 'DiffsDiffText', { default = true, bg = diff_text.bg }) + + if config.highlights.overrides then + for group, hl in pairs(config.highlights.overrides) do + vim.api.nvim_set_hl(0, group, hl) + end + end end local function init() @@ -251,6 +258,7 @@ local function init() ['highlights.background'] = { opts.highlights.background, 'boolean', true }, ['highlights.gutter'] = { opts.highlights.gutter, 'boolean', true }, ['highlights.blend_alpha'] = { opts.highlights.blend_alpha, 'number', true }, + ['highlights.overrides'] = { opts.highlights.overrides, 'table', true }, ['highlights.context'] = { opts.highlights.context, 'table', true }, ['highlights.treesitter'] = { opts.highlights.treesitter, 'table', true }, ['highlights.vim'] = { opts.highlights.vim, 'table', true }, From ae65c50f9261707269d34b5db479c884d7e61250 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Sat, 7 Feb 2026 15:53:08 -0500 Subject: [PATCH 5/5] docs(readme): mention blend alpha and highlight overrides --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2b4d845..ca3d72e 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,8 @@ syntax highlighting. - Vim syntax fallback for languages without a treesitter parser - Hunk header context highlighting (`@@ ... @@ function foo()`) - Character-level (intra-line) diff highlighting for changed characters -- Configurable debouncing, max lines, and diff prefix concealment +- Configurable debouncing, max lines, diff prefix concealment, blend alpha, and + highlight overrides ## Requirements