Avoid blocking the UI after file staging in large repositories

[Saafo]

Context

In large repositories, staging or unstaging from the files panel can make the UI unresponsive for a noticeable amount of time. The slow path appears to come from two separate costs:

• git status --untracked-files=all can take multiple seconds.
• git add, git reset HEAD, or git rm --cached can also take hundreds of milliseconds to more than a second.

Today, the files panel does an optimistic in-memory update, but the real git operation and follow-up refresh can still block interaction long enough that scrolling the files panel or switching panels feels frozen.

Local measurements

These are local measurements from a large working tree, intended as directional data rather than a formal benchmark.

Before the prototype change:

• Full files refresh with untracked files: around 2.4s - 3.9s.
• Slow observed stage/unstage key handling: around 2.1s - 2.5s.
• In one case, the key handler waited almost 2s just to acquire the files refresh mutex while a full refresh was running.

After the prototype change:

• Stage/unstage key handling returned in about 76ms - 188ms, averaging around 100ms in the latest sample.
• The real git operations still took time, but no longer blocked panel navigation:
  • git add: roughly 400ms - 550ms in the latest sample.
  • git reset HEAD: roughly 900ms - 1.1s in the latest sample.
  • git rm --cached: roughly 340ms - 360ms in the latest sample.
• Background tracked-only refresh using git status --untracked-files=no took around 735ms - 1.0s in the latest sample.
• Background model apply was small, roughly 15ms - 25ms.

Prototype approach

I tried a prototype with these changes:

1. Split files refresh into a load phase and an apply phase.

   • The expensive git status call runs outside the files refresh mutex.
   • The mutex is only held briefly while applying the new model.

2. Add generation-based refresh invalidation.

   • If a newer files refresh request appears, stale background results are skipped.
   • Repeated stage operations are coalesced instead of queueing multiple full refreshes.

3. Use a faster background reconcile after stage/unstage.

   • Stage-triggered background refresh uses --untracked-files=no.
   • Existing untracked files are merged back into the model so the files panel does not lose visible untracked entries during the tracked-only reconcile.

4. Move files-panel stage/unstage git writes onto a worker.

   • The UI keeps the existing optimistic update.
   • The real git add, git reset HEAD, or git rm --cached runs asynchronously.
   • Files panel scrolling and panel switching stay responsive while the git command is still running.

Main concern

The performance improvement is significant, but moving the git write operation to a worker introduces a semantic question.

There is now a short window where:

• the UI has already optimistically shown a file as staged or unstaged;
• but the real git index has not been updated yet.

That means a user could potentially trigger another operation before the pending stage operation finishes, for example:

• commit immediately after staging;
• switch branches immediately after staging;
• discard/reset while a stage operation is still pending;
• apply a hunk from the staging panel while a files-panel stage operation is still pending.

Without a shared barrier, those operations may observe the real index before the pending stage operation has completed, even though the UI already reflects the optimistic state.

Possible directions

I would like feedback on which direction fits lazygit's architecture best.

Option A: Keep git stage/unstage synchronous, only optimize refresh

This is the safest semantic option.

• Keep git add/reset/rm on the existing interaction path.
• Still split files refresh into load/apply phases.
• Still avoid holding the files refresh mutex while running slow git status.
• Still coalesce stale background refreshes.

This should reduce the worst freezes caused by full files refreshes, but it will not hide slow git add or git reset HEAD.

Option B: Workerize stage/unstage, but add a pending index-operation barrier

This preserves the best UI responsiveness but needs a stronger consistency mechanism.

The idea would be:

• files-panel stage/unstage registers a pending index operation;
• commit, branch checkout/switch, discard/reset, staging panel hunk operations, stash, and similar index/working-tree operations wait for pending index operations before proceeding;
• ordinary navigation, scrolling, and panel switching do not wait.

This keeps the UI responsive for navigation while preventing operations that depend on the index from racing ahead of the pending git write.

Option C: Workerize only selected cases

For example:

• keep single-file stage/unstage synchronous;
• workerize only expensive directory or stage-all operations;
• or workerize only when the files refresh/status path is known to be slow.

This reduces the semantic surface area, but the behavior becomes less uniform.

Additional edge cases

There are a few smaller correctness details to handle if we continue with the background reconcile approach:

• If staging an untracked file fails after the optimistic update, a tracked-only refresh may not see the file. The failure path probably needs a full files refresh or an operation-preimage snapshot of untracked files.
• The refresh code should avoid reading shared *models.File fields outside the files refresh mutex. A lightweight snapshot of the fields needed for auto-staging resolved conflicts may be safer than a shallow slice copy.
• Refresh invalidation should probably happen only after we know an operation will proceed, or failure paths should ensure a replacement refresh is scheduled.

Question

Would lazygit prefer the more conservative approach of keeping index writes synchronous while making refresh non-blocking, or is an asynchronous stage/unstage path acceptable if paired with a shared pending index-operation barrier?

[Saafo]

Hi @stefanhaller I would appreciate your input on the direction we should take.