From a0870a789239d571856883dfea11d6854da5aa98 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Sat, 7 Feb 2026 15:47:36 -0500
Subject: [PATCH] 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<string, 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 },