Zed Filesystem Handling Needs an Overhaul

[auwi-nordic]

This is a continuation of the discussion in "Manual Refresh the File Tree" #54150

The discussion was closed, and has remained closed despite repeated comments pointing out that the issue being discussed is unresolved. The title of the issue also only captures one aspect of the overarching issue plaguing Zed.

The core of the issue is that Zed has a fundamentally broken model for handling the filesystem. It has been built on the assumption that Zed can reliably track the state of the filesystem with just file system notifications.

The poller backend that was implemented in #54481 by @probably-neb was a step in the right direction but still demonstrated a fundamentally flawed understanding of how to handle the filesystem. There should never have been one notification based backend and one poller based backend which is must be manually selected. There should only be one backend. Polling is always needed at some level to ensure that the view Zed has of the filesystem doesn't drift. The only question is how often to poll, and that's an answer that should probably depend on the view the user has of the project.

There is still no button or even context menu or commands to trigger a manual refresh, something which is an essential backstop implemented by almost every text editor for very good reasons.

I have seen top comments pointing this issue out when Zed has been discussed in Hacker News, so it's clearly not just me and the others complaining in #54150 who are experiencing this.

This wouldn't have been such a critical issue if Zed was still in Beta. But the release of 1.0 communicates a quality level which Zed simply does not reach. I can not recommend it to anyone despite how much I like every other aspect of Zed. I can also point out #58792 as another example of the basic fundamentals of being a Code Editor is neglected over landing trivial improvements to Markdown rendering or a bunch of AI features – which are all nice but should probably not be the top priority until the core of the software is robust.

This seems to have been resolved by Gram Editor, a fork of Zed. If I connect to the same remote server with Zed and Gram, Zed is unable to track changes, while Gram eventually catches the changes in both the Project Panel and Git Panel. So I can recommend others in the same situation to try to use Gram if they need to remote to a server for occasional work.

[auwi-nordic]

@SomeoneToIgnore Could you please re-open the discussion?
Edit: It was somehow posted by Github before I had a chance to edit the body of the post, it has been filled out now.

[SomeoneToIgnore]

First, reopened but then realized it adds nothing but "bad bug, fix it".
Agree with that, but see no point of the discussion still, while we have an open issue for that.

[auwi-nordic]

@SomeoneToIgnore I'm very sorry, I should have spent a bit more time to prepare the post describing the what I want to discuss. I understand that you're very busy and don't want duplicate issues and such. But this isn't about that. It's not about ONE issue. This is about a much-needed discussion about the overarching focus on filesystem tracking, and getting to a comprehensive solution that actually fixes the root problem.

Please see my two comments below for the kind of discussion I think we need here. Do you really think this isn't worth discussing at this level?

I think these facts unequivocally demonstrate the need for a serious high-level discussion:

• The repeated calls from multiple users for re-opening Manual Refresh the File Tree #54150
• The comments repeatedly seen on Hacker News and Reddit about these issues in Zed
• That Gram — which has fewer maintainers and actively shun using AI to help in development and thus should be less productive than the Zed team — is already significantly more robust and user-friendly than Zed in this area.

[auwi-nordic]

Had a session with Claude to generate an overview of all the issues related to this topic, and to compare with the improvements made in Gram

Zed File-Watching / Manual Refresh Saga

Discussion lineage

#	Title	Type / Status	Note
#16873	Reload folder from disk (remote development)	Issue · Closed	Earliest ask (Aug 2024)
#26857	Refresh the open folder dock as files/folders change	Discussion · Open, 69 upvotes	Root discussion (Mar 2025)
#54150	Manual Refresh the File Tree	Discussion · Closed	Continuation of #26857, 47 upvotes; closed despite pushback
#64581	Zed Filesystem Handling Needs an Overhaul	Discussion · Closed	Follow-up asking to reopen #54150

Duplicate / root-cause bug reports

#	Title	Status
#20044	Manual refresh support (NFS shares)	Closed, dup of #29598
#25740	Remote Development: Files not updated	Closed, dup of #29598
#27227	Zed does not detect changes to NFS mounts	Closed, dup of #29598
#29242	Remote Workspace File Tree does not refresh	Open, heavily active
#29598	Manual refresh on unsupported filesystems (NFS/FUSE/exFAT)	Open — consolidated feature request
#38109	Zed out of sync with changes made outside editor	Closed as completed — 60+ later comments say still broken
#51340	Add PollWatcher fallback for WSL/network/FUSE	Closed, fixed by PR #54481
#48439	Zed shows cached/old file content when modified externally	Related bug
#57042	Remote server creates 95GB log after watcher loses sync	Related bug
#62486	Watcher fd leak on macOS (FSEvent retry loop)	Related bug
#49162	ACP readTextFile returns stale buffer (race condition)	Related bug
#63693	LSP watchers force-load ignored dirs, unbounded	Related bug

Fix attempts (Pull Requests)

#	Title	Status
#46291	Add command to manually trigger a refresh/rescan of folders	Closed/rejected — staff blocked over "masking FS issues"
#48871	project_panel: Add "rescan worktrees" action	Closed, simpler alternative, also not merged
#54481	fs: Polling backend support	Merged
#51208	Handle Linux FS Rescan Events	Merged (inotify queue-overflow handling)
#57720	Add cooldown when file watch limit reached	Merged
#59714	Handle case-insensitive filesystems in watcher	Merged
#59064	Send missing didChangeWatchedFiles/didChange events	Open
#62200	Fix watch-before-read race in worktree scanner	Draft/open

How Gram resolved it

The more important fix, per Gram's own changelog (release 3.0.0, 2026-06-29),
is original to Gram and not backported from Zed at all:

• "Trigger full rescan when focusing project panel"
• "Refresh git panel when focused"
• "Refresh entries for paths whenever active item changes"

This forces a reconciliation scan whenever you focus the Project Panel or Git
Panel, or switch the active item — independent of whether the underlying
inotify/FSEvents watcher ever fired a real event. This is most likely what
explains "eventually catches the changes" behavior in Gram that Zed doesn't have.

Zed vs. Gram comparison

Aspect	Zed	Gram
Manual "refresh folders" command	Rejected (PR #46291 closed)	Merged (cherry-picked #46291)
Polling watcher (fallback to inotify/FSEvents)	Shipped (PR #54481, merged)	Present, but implementation differs
Rescan on inotify queue overflow	Shipped (PR #51208, merged)	Backported from Zed
Rescan triggered on Project/Git panel focus	Not present	Present (Gram-original, since 3.0.0)
Governance stance on manual refresh	Staff opposed it as "masking FS issues"; asked community to consolidate into a discussion instead	Maintainer simply merged the community fix

[auwi-nordic]

Here's an elaboration of what I think could be a comprehensive solution to have robust filesystem tracking in Zed

1. The manual refresh command should be added
2. The rescan on Project/Git panel focus should be implemented
3. Get ride of the mode-switching between notify and polling based filesystem watching. There should only be one setting: polling interval. It can default to a very high value, effectively infinity if you really want to turn it off.
4. Zed detects filesystem that has know issues with notify through detect_requires_poll_watcher_linux. This is a nice optimization, but can by definition not catch all cases. It should not switch modes. It should bump the polling to a higher rate.
5. Another detection mechanism can be made: if Zed detects that it sees a filesystem change it did not get notified about, it should bump the polling rate up. This could be through one of three mechanisms:
   a. Changes seen through the default slow polling rate
   b. Changes seen when user triggered manual refresh
   c. Changes seen when refresh was triggered by panel focus
6. Should consider having a higher polling rate for the repository shown in the git panel, and the folders that are open in the project panel
7. Configuration of polling rates should be surfaced as a proper setting in both the user and project settings. An environment variable is not a long term solution.

If these things are implemented, I think there's a high chance we wont have any more significant issue with file system watching in Zed.

[auwi-nordic]

In researching issues from Gram, came across this issue which should probably also be looked at as part of this:

https://codeberg.org/GramEditor/gram/issues/214

If we can determine that file change detection won't work reliably, we should inform the user of that, and explain how they can fix it.
JetBrains does this well.

This is the right attitude. Don't assume that notify just works. Have mechanisms to detect failures, and surface issues to the user so they can update configurations as needed.