save "viewed" state in the diff file

[jacekkopecky]

Motivation

When reviewing code by going through a long-ish diff, especially if I want to jump around, the "viewed" feature of diff2html is very useful to hide files I've reviewed. Sometimes, a bigger review goes on for a few days; it is terrible if I have to restart VSCode in the meantime and lose the "viewed" state. The view also loses its state if the file gets touched externally, or if I accidentally close and then reopen the tab.

Therefore, I've been thinking about saving the state somewhere. I don't know much about VSCode extensions yet so I don't know if they have some kind of information store available. Therefore, I implemented a version that saves the "viewed" state right in the diff file.

Proposed solution

In a diff file, there can be any number of extra lines, provided they don't start with -/+/space. My version uses a line like this:

viewed e8 (hex bitmap)

The syntax is: "viewed" SP <hexBitmap> SP <comment>

The comment can be anything (after the hex bitmap, the rest of the line is ignored).

The hex bitmap is a hexadecimal representation of the boolean array that indicates which files have been viewed. E.g. "e8" means that the first, second, third and fifth files are marked as viewed. (e8 is 11101000).

The "viewed" line can be anywhere in the diff file; by default it's saved at the top of the file because that's fastest to find on load. Hexadecimal was chosen for brevity.

So, two questions for discussion:

1. where should we save the "viewed" state?
2. if in the file itself, is the proposed format OK?

[caponetto]

Thanks for the complete description, @jacekkopecky! This use case makes total sense to me.

As described in [1], the VS Code Extension API provides a data storage mechanism. However, the "viewed" state would be bound to VS Code, not the file itself. If the file is copied, moved, or opened in a different VS Code instance, the "viewed" state would be lost.
Would this be an issue? I'm not sure that such a scenario would be frequent.

On the other hand, the proposed approach avoids the issue I've mentioned because the state is saved in the file itself. I don't a see problem with this approach as long as this feature is an optional thing (enabled with a config) and disabled by default. The user must be fully aware that the file content will be changed and the reason they are changing.

Either way, storing the state using hexBitmap can be used in both approaches.

Let me know your thoughts. :)

[1] https://code.visualstudio.com/api/extension-capabilities/common-capabilities#data-storage

[jacekkopecky]

Thanks for the link @caponetto, workspaceState would definitely be an option; we would key on the file path and have the hex bitmap as the value.

The transferability of the "viewed" state to other tools or other workspaces is not a strong use case IMO.

Using workspaceState would have an added benefit of not getting lost if when regenerating the .diff file.

But it opens more work: if the diff file is regenerated, we really should remember which file's part we've viewed by file path and name (not just by file order in a bitmap), and notice and display "changed since last viewed" when the diff file gets updated. This would then behave like GitHub's diffs.

It would also open up the possibility for other git extensions to send multi-file diffs into vscode-diff-viewer; having previously worked with Atom and Github where multi-file diffs are the norm, I for one miss multi-file diffs in VSCode and in Bitbucket, which I have to work with now.

What do you think?

I'll sit on this for a while until inspiration strikes again (it's not difficult but I need to be in the mood, which is entirely unpredictable); if anyone else wants to take a stab at it sooner, I definitely won't mind. 8-)