Proposed
Give users an option to, before they make a commit, see diffs of all staged changes in one view, akin to the Files changed tab in pull requests on github.com.
So that users can view a full set of changes with more context before committing them.
Note that the multi-diff view is the MVP of this RFC, and we have identified Commit Preview to be the least frictional way to introduce this feature without making too many UX changes. Other planned features that will also make use of multi-diff view are:
- commit pane item where it shows all changes in a single commit
- new PR review flow that shows all changed files proposed in a PR
- (TBD) multi-select files from unstaged & staged panes to view diffs
A new button added above the commit message box that, when clicked, opens a multi-file diff pane item called something like "Commit Preview" and shows a summary of what will go into the user's next commit based on what is currently staged.
- Shows diffs of multiple files as a stack.
- Each diff retains the file-specific controls it currently has in its header (e.g. the open file, stage file, undo last discard, etc).
- [out of scope] It should be easy to jump quickly to a specific file you care about, or back to the file list to get to another file. Dotcom does so by creating a
jump todrop down. - [out of scope] As user scrolls through a long list of diffs, there should be a sticky heading which remains visible showing the filename of the diff being viewed.
- [out of scope] Each file diff can be collapsed.
This would be a nice addition to the top-to-bottom flow that currently exists in our panel:
- View unstaged changes
- Stage changes to be committed
- 🆕 Click "Commit Preview" 🆕
- Write commit message that summarizes all changes
- Hit commit button
- See commit appear in recent commits list
- Profit 🎉
- There might be performance concerns having to render many diffs at once.
An alternative would be to not implement multi-file diff, as other editors like VS Code also only has per-file diff at the time of writing. However, not implementing this would imply that the proposed new PR review flow will have to find another solution to display all changes in a PR. Additionally users would have to do a lot more clicking to view all of their changes. Imagine there was a variable rename and only 10 lines are changed, but they are each in a different file. It'd be a bit of a pain to click through to view each one. Also, if we didn't implement multi-file diffs then we couldn't show commit contents since they often include changes across multiple files.
How exactly do we construct the multi-file diffs? Do we have one TextEditor component that has different sections for each file. Or do we create a new type of pane item that contains multiple TextEditor components stacked on top of one another, one for each file diff... If we do the former we could probably get something shipped sooner (we could just get the diff of the staged changes from Git, add a special decoration for file headers, and present all the changes in one editor). But to pave the way for a more complex code review UX I think taking extra time to do the latter will serve us well. For example, I can imagine reviewers wanting to collapse some files, or mark them as "Done", in which case it would be easier if we treated each diff as its own component.
The following items are considered out of scope for this RFC, but can be addressed in the future independently of this RFC.
It would be cool if each diff was collapsable. Especially for when we start using the multi-file diff for code review and the reviewers may want to hide the contents of a file once they're done addressing the changes in it. "Collapse/Expand All" capabilities would be nice as well.
| All files collapsed | Some files collapsed |
|---|---|
 |
 |
"Find" input field for filtering diffs based on search term (which could be a file name, an author, a variable name, etc). When filtering, files that have no match get collapsed. This allows you to uncollapse files (and seeing their diff) without having to clear the filter. Matches get highlighted with a yellow overlay as well as a stripe on the side, similar to git-diff in the editor.
| Unfiltered | Filtered |
|---|---|
 |
 |
Alternative: It might be possible to re-use the find+replace UI to filter the multi-file diff. And maybe even have "replace" working.
As user scrolls through a long list of diffs, there should be a sticky heading which remains visible showing the filename of the diff being viewed.
- whether
cmd+clickto select multiple files is discoverable
See checklist on PR