fix(multi): Suppress VGitSync during staging

Adds API to git_buffer_store for suppressing VGitSync events during
staging. Applies suppression in DiffScreen staging methods to prevent
cascading buffer refreshes.

Performance from local profiling:
95% reduction in calls (10,421 → 564 per session staging 39 hunks),
99.6% reduction in LiveGutter:fetch (1,380 → 6).

DiffScreen already manually fetches and renders, making VGitSync refresh
of all tracked buffers redundant.

Author: MaxFangX

lua/vgit/features/screens/DiffScreen/init.lua

@@ -138,6 +138,10 @@ function DiffScreen:reset(buffer)
   local filename = self.model:get_filename()
   if not filename then return end
 
+  -- Performance: Suppress VGitSync during reset since we manually fetch below
+  local git_buffer_store = require('vgit.git.git_buffer_store')
+  git_buffer_store.suppress_sync_for(200)
+
   loop.free_textlock()
   self.model:reset_file(filename)
 
@@ -185,6 +189,11 @@ function DiffScreen:stage_hunk(buffer)
   local hunk, index = self.diff_view:get_hunk_under_cursor()
   if not hunk then return end
 
+  -- Performance: Suppress VGitSync during staging since we manually fetch below
+  -- This prevents refreshing all tracked buffers unnecessarily
+  local git_buffer_store = require('vgit.git.git_buffer_store')
+  git_buffer_store.suppress_sync_for(200)
+
   self.model:stage_hunk(filename, hunk)
 
   loop.free_textlock()
@@ -212,6 +221,10 @@ function DiffScreen:unstage_hunk(buffer)
   local hunk, index = self.diff_view:get_hunk_under_cursor()
   if not hunk then return end
 
+  -- Performance: Suppress VGitSync during unstaging since we manually fetch below
+  local git_buffer_store = require('vgit.git.git_buffer_store')
+  git_buffer_store.suppress_sync_for(200)
+
   loop.free_textlock()
   self.model:unstage_hunk(filename, hunk)
 
@@ -247,6 +260,10 @@ function DiffScreen:reset_hunk(buffer)
 
   if decision ~= 'yes' and decision ~= 'y' then return end
 
+  -- Performance: Suppress VGitSync during reset since we manually fetch below
+  local git_buffer_store = require('vgit.git.git_buffer_store')
+  git_buffer_store.suppress_sync_for(200)
+
   loop.free_textlock()
   self.model:reset_hunk(filename, hunk)
 
@@ -271,6 +288,10 @@ function DiffScreen:stage(buffer)
   local filename = self.model:get_filename()
   if not filename then return end
 
+  -- Performance: Suppress VGitSync during staging since we manually fetch below
+  local git_buffer_store = require('vgit.git.git_buffer_store')
+  git_buffer_store.suppress_sync_for(200)
+
   loop.free_textlock()
   self.model:stage_file(filename)
 
@@ -292,6 +313,10 @@ function DiffScreen:unstage(buffer)
   local filename = self.model:get_filename()
   if not filename then return end
 
+  -- Performance: Suppress VGitSync during unstaging since we manually fetch below
+  local git_buffer_store = require('vgit.git.git_buffer_store')
+  git_buffer_store.suppress_sync_for(200)
+
   loop.free_textlock()
   self.model:unstage_file(filename)
 

lua/vgit/git/git_buffer_store.lua

@@ -16,6 +16,13 @@ local events = {
 }
 local is_registered = false
 
+-- Performance optimization: control VGitSync refresh behavior during staging
+local staging_state = {
+  active = false,           -- True when selective refresh mode is active
+  target_buffer = nil,      -- The specific buffer to refresh (nil = all buffers)
+  suppress_sync = false,    -- True to completely suppress VGitSync events
+}
+
 local git_buffer_store = {}
 
 git_buffer_store.register_events = loop.coroutine(function()
@@ -40,6 +47,21 @@ git_buffer_store.register_events = loop.coroutine(function()
   -- Use vim.schedule to avoid "must not be called in a lua loop callback" error
   vim.schedule(function()
     event.custom_on('VGitSync', function()
+      -- Skip sync entirely if suppressed (e.g., during batch staging operations)
+      if staging_state.suppress_sync then
+        return
+      end
+
+      -- Selective refresh: only refresh specific buffer if configured
+      if staging_state.active and staging_state.target_buffer then
+        local target_buf = staging_state.target_buffer
+        if target_buf:is_valid() then
+          git_buffer_store.dispatch(target_buf, 'sync')
+        end
+        return
+      end
+
+      -- Default behavior: refresh all tracked buffers
       git_buffer_store.for_each(function(buffer)
         git_buffer_store.dispatch(buffer, 'sync')
       end)
@@ -181,4 +203,43 @@ git_buffer_store.collect = function()
   git_buffer_store.dispatch(git_buffer, 'attach')
 end
 
+-- Performance: API for controlling VGitSync behavior during staging operations
+-- Reduces buffer refresh cascade by limiting which buffers get refreshed
+
+-- Suppress all VGitSync events for a specified duration
+-- Useful for batch operations where multiple git index changes occur
+-- Usage: git_buffer_store.suppress_sync_for(500)
+git_buffer_store.suppress_sync_for = function(ms)
+  staging_state.suppress_sync = true
+  vim.defer_fn(function()
+    staging_state.suppress_sync = false
+  end, ms)
+end
+
+-- Enable selective refresh mode - only refresh the specified buffer on VGitSync
+-- Usage: git_buffer_store.begin_selective_staging(buffer)
+git_buffer_store.begin_selective_staging = function(buffer)
+  staging_state.active = true
+  staging_state.target_buffer = buffer
+end
+
+-- Disable selective refresh mode, returning to default behavior
+git_buffer_store.end_selective_staging = function()
+  staging_state.active = false
+  staging_state.target_buffer = nil
+end
+
+-- Convenience wrapper: execute staging function with selective refresh
+-- Automatically enables selective mode, runs function, then restores after delay
+-- Usage: git_buffer_store.with_selective_staging(buffer, function() ... end)
+git_buffer_store.with_selective_staging = function(buffer, stage_fn)
+  git_buffer_store.begin_selective_staging(buffer)
+  local ok, err = pcall(stage_fn)
+  -- Keep selective mode active briefly to catch the filesystem watcher event
+  vim.defer_fn(function()
+    git_buffer_store.end_selective_staging()
+  end, 150)  -- Filesystem watcher has 10ms debounce, add margin
+  if not ok then error(err) end
+end
+
 return git_buffer_store