Manage editors more intuitively when files are externally modified or deleted

[savetheclocktower]

Have you checked for existing feature requests?

• Completed

Summary

I don't know how feasible this is, but I'm going to throw it out here.

• Suppose you have two git branches in your project.
• File foo.js exists on branch old, but not on branch new.
• You are on branch old. You open foo.js in order to make a change. You commit the change. You leave foo.js open in your workspace.
• You switch to branch new.

What Pulsar does in this situation is what it would always do if it detects that a TextEditor’s backing file has suddenly disappeared: keep the TextEditor open, but adjust its status to be “unsaved.” That's often the right move — you want an “are you sure?” dialog if you try to close the editor, and you want the indication in the tab bar that the item is not committed to disk.

But in a version-control scenario, it's not what I want.

---

Let me try to turn this into a feature request:

If I were more diligent, I could have avoided the situation in my example by closing the foo.js tab in my workspace before switching branches. So could the github package take care of that automatically?

EDIT, 2025-02-20: In fact, there is a core.closeDeletedFileTabs option that I've never explored. Leaving this ticket open for the proposed UI changes and to cover the modified-buffer cases.

• The package (presumably) detects when I've switched from branch old to branch new.
• It can iterate through each open TextEditor in my workspace and ask these questions:
  • Is this file tracked in this repository? (If not, ignore it.)
  • Is this file present on branch new? (If so, ignore it.)
  • Does this file have untracked changes on branch old? (If so, ignore it; this is a bit paranoid, since Git would forbid the user from switching branches in this scenario, but it's good to be cautious.)
  • Was this buffer “dirty” — e.g., did its contents differ from what was on disk just before the branch switch? (If so, ignore it.)
  • If we get this far, we've identified a workspace item that I would be annoyed at having to close manually.
• Automatically close all the TextEditor workspace items that meet all the above criteria.

What benefits does this feature provide?

Managing the number of open tabs is hard enough, even with zentabs. Any logic that can safely prune my list of open tabs without my intervention is a plus.

It doesn't necessarily have to be default behavior, either; I'd be fine with opting into this.

Any alternatives?

It's possible that the APIs exist for this to be its own package instead of something built into the github package. I'm only suggesting it for that package because I'm pretty sure it would be able to do this with its current libraries… but maybe it's something that any package could do.

I notice that the GitRepository class is a bit short on event subscriptions; I would've expected a way to register a callback on a branch change, but maybe that wouldn't be too hard to add to core.

Other examples:

VS Code, in this scenario, keeps the editor open, but marks the file as “deleted”:

Even though this file has an open editor, VS Code correctly recognizes that it would not be destructive to close the tab at this point, and it will not ask me to confirm when I close this tab.

If I were to edit the buffer, the tab would change to add a “dirty” indicator, and will now show a confirmation dialog if I try to close the tab:

And if I save the open buffer while it's in the “deleted” state — whether I made changes or not — it commits the file to disk, abandons this “deleted” status, and correctly marks it as a new, untracked file in this branch:

---

I'm fine with this behavior, especially as a medium-term goal, but I'd also be OK with VS Code just closing those tabs — if it knows enough to mark them as “deleted,” it knows enough to close them automatically for me. (There might be a setting for that; I haven't looked.)

But I know that's something that would definitely need to change in core, so I'm wondering if we can do the simpler thing in the short term.

[savetheclocktower]

After some further tests, I can confirm that VS Code's behavior here matches what it does even outside the presence of a repository. If I have a file open in VS Code, and I delete the underlying file on disk, VS Code reacts exactly as documented above; it recognizes the “deleted” state of the file and indicates it with the strike-through and the red status color.

We ourselves could have such a state for all files. Aside from cosmetics, the major difference in VS Code is that you can close the editor of a deleted tab without an “are you sure?” confirmation; I suppose they feel like the red text and the strike-through are enough of a warning. (That confirmation will still happen, though, if the TextEditor was in a dirty state when the file was deleted.)

This would have to be a core change, but it's at least possible that this wouldn't be painful.

[savetheclocktower]

The other unknown aspect is how Pulsar, or the github package, detects when the user switches branches in a Git repo. I can't find anything in the docs for git-utils or dugite that would provide me what I want here, which is a callback that gets invoked whenever a given reference is checked out (whether or not it was initiated within Pulsar).

I figure that must exist, since various parts of the github package react when I switch branches. But I'm not sure how it gets notified.

[savetheclocktower]

Revisiting this.

Current behavior

Currently there are two states a buffer can be in, and which are reflected in the buffer's tab (some names are of my own invention just to make this easier to describe):

• Pristine: Contents of the buffer match what's on disk.
• Modified: Contents of the buffer do not match what's on disk.

For every open buffer in the workspace, we watch the associated path on disk. If the contents on disk change because they were modified by another process, all pristine buffers have their contents updated to reflect this.

Also: if the file on disk is deleted altogether, Pulsar can detect this and automatically close the tab if core.closeDeletedFileTabs is enabled.

Problems to solve

There are two scenarios we want to improve:

• Contents on disk change while the buffer is modified. Currently, the buffer's contents do not revert to what's on disk (which is fair, since any uncommitted changes would be lost); but that uncommitted text sits in an arguably hazardous state, since saving it would likely undo whatever changes had been made by the other process.
• The file itself is deleted while the buffer is modified. Currently, this looks a lot like the above scenario; the buffer's modified contents are not disrupted, but the user is given no indication that the file backing the buffer no longer exists.

Proposed additions

To do this, we should add two new states:

• Deleted: Contents of the buffer do not match what's on disk because the file on disk is no longer present.
• Conflicted: Contents of the buffer do not match what's on disk because the contents on disk changed — and those changes need to be reconciled with the modifications that the user has made but has not yet saved.

Right now, these two states are treated identically to the modified state, even though they are vastly different in their implications and effects.

It's possible that we'll handle the addition of these two new states in different ways, or add them at different times. The Deleted state is conceptually easier because it just requires its own treatment in the tab bar, and because the stakes are lower. (Accidentally write to a file that should be deleted? Just delete the file again.)

The Conflicted state, on the other hand, needs a UI built around it. In the first incarnation, though, it could be something as simple as an “are you sure?” dialog upon a save attempt.

---

VS Code handles both of these scenarios; when I get a minute I'll document its behavior with screenshots.

[savetheclocktower]

So suppose you've got a buffer open in VS Code. You change a word and are about to save… but then are distracted by a beautiful sunset.

Hours later, you return to your computer. In a trance, you open the same file in Vim or nano or micro or, uh, Pulsar. You make an incompatible change to the file and save it to disk.

Snapping out of your trance, you return to VS Code and attempt to save your uncommitted changes.

VS Code detects this and tries to save you from yourself:

If you choose “Compare,” you're brought to a diff view:

---

We can do most of this right off the bat.

It's easy to detect when a file is in conflict, and pretty easy to spawn a dialog like this when someone tries to save:

“Cancel” and “Overwrite” are straightforward. “View Conflicts” is certainly doable, but would require extraction of the conflict-resolution view from the github package (or reimplementation of something approximating it). That would represent the greatest amount of effort here, but we can wait until later to do that; this dialog is useful even if it's only got “Overwrite” and “Cancel.”

[savetheclocktower]

What about deleted files?

Say I've got a VS Code project open in a folder with something.txt, and I've got that file open for editing. The file is pristine, with no uncommitted changes. I switch over to Pulsar and delete something.txt. I switch back to VS Code and see:

Somewhat surprisingly to me, not much else changes in this scenario. You can commit that file back to disk at its previous location just by saving, and you can close the tab without any prompting.

What if you made uncommitted changes before the file was deleted? Nothing changes about that, either. If you try to close the tab, it'll warn you you're about to abandon your changes. And if you save, it'll commit back to disk without a prompt.

---

To replicate this behavior in Pulsar would require that we handle the deletion scenario differently than we do now. Right now, once the file is deleted, Pulsar puts the buffer into modified state, whether or not there are any uncommitted changes.

Instead, if there were no uncommitted changes at the time of deletion, we should allow the deletion to supersede the modified state. isModified should return false in this scenario.

But it should remain in the modified state (a) if the file was in a modified state prior to the deletion; or (b) if, after the deletion, the user makes any changes to the file. In these cases, we still want the user to be prompted before closing the pane item.

[savetheclocktower]

OK, implementation of conflicted-state handling is going well. Text buffers already know when they're in conflict; we've got an isInConflict method, along with an onDidConflict method for registering event listeners. So that's not the hard part.

One thing that might be a bit weird: this is technically a behavior of a pane, not of the editor itself. The most obvious model to follow here is the prompt you get before you try to close a modified editor; when you do that, the pane will recognize that the item is modified and ask the item itself if it should prompt you to save (via, uh, a shouldPromptToSave method implemented on the pane item).

But that makes a lot of sense! Closing a tab is task related to workspace management, so it's a fine idea for that prompt to be the concern of the workspace rather than something that is initiated directly from the TextEditor class. (It also grants any arbitrary pane item, not just text editors, the concept of uncommitted changes. The pane just cares about which methods you implement!)

It's a bit trickier when it comes to editor conflicts on save.

User-initiated saving goes through the workspace; the core:save key binding calls atom.workspace.saveActivePaneItem(). That calls through to the owning Pane of the active pane and calles Pane::saveItem. Right now, that's where I've got it doing the conflict check. The dialog pops up and the user can choose to Overwrite or Cancel; the first option proceeds, and the second option throws an error that bypasses the save operation and gets caught later in the promise chain.

This makes theoretical sense because, just as any pane item can implement saving, a conflict is something that could happen to any pane item. We want it to be handled identically across different kinds of pane item.

But it means that an editor can still programmatically be saved, even if it's in conflict, through the direct TextEditor::save method. Calling that method bypasses the extra layer of protection we've added.

This isn't a huge problem… but ideally I would like this API to be aware of the possibility of conflicts without affecting backward-compatibility, and to have its own opt-in strategy for handling attempted saves while a buffer is in conflict.

Right now, TextEditor::save takes no arguments and simply calls through to TextBuffer::save. But perhaps TextEditor could accept an options argument to control how it behaves. (editor.save({ throwOnConflict: true }) to opt into “safer” saving, perhaps?).

Again: this is a minor issue, and isn't a blocker for improving the current experience. I don't think that calling a method directly on the TextEditor should have a side effect that involves the workspace. In a workspace context, the solution to a potential save conflict is a dialog that says “you might not want to save yet because you could clobber some changes”; in a pure TextEditor context, I think we'd want the API to be simpler and without side effects, and make it the consumer's job to decide what to do about the conflict. I'll keep thinking about this.