-
Notifications
You must be signed in to change notification settings - Fork 467
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
UX of universal undo feature (discussion) #3726
Comments
@krlvi I see this feature working like Git history, where we don't erase previous steps, but instead create a 'revert' snapshot that keeps track of changes, unlike traditional undo/redo (similar to the Photoshop example below): Screen.Recording.2024-05-08.at.15.47.24.movShould we even track or show spammy operations like setting the default branch or reordering branches? These don't have as much impact as file changes or branch deletions, so maybe we shouldn't focus on them and show them at all. Alternatively, we could allow simple operations like branch reordering and setting the default branch to be undone with Ctrl+Z, but keep the rest in the history/timeline sidebar. Because some operations we need in short term like set default branch" and some for long distance like "file changes" or "branch deleted". Because some operations are critical and involve large changes, we shouldn't allow going back with 'Ctrl+Z' or in this case automatically show the sidebar, so a user wouldn't do it blindly. Also, with 'Ctrl+Z', you wouldn't see a previous step erased—you'd just see a new snapshot at the top. That's why I suggest not treating this like a regular undo/redo function—it could be confusing. Since some operations look noisy and not that useful, I'd prefer not to see them at all. For example pub enum OperationType {
CreateCommit,
CreateBranch,
SetBaseBranch,
MergeUpstream,
UpdateWorkspaceBase,
MoveHunk,
UpdateBranchName,
// UpdateBranchNotes, // not in use
// ReorderBranches, // not really valuable in history
// SelectDefaultVirtualBranch, // not really valuable in history
UpdateBranchRemoteName,
GenericBranchUpdate,
DeleteBranch,
ApplyBranch,
DiscardHunk,
DiscardFile,
AmendCommit,
UndoCommit,
UnapplyBranch,
CherryPick,
SquashCommit,
UpdateCommitMessage,
MoveCommit,
RestoreFromSnapshot,
ReorderCommit,
// InsertBlankCommit, // what is usecase to display this in history?
MoveCommitFile,
FileChanges,
#[default]
Unknown,
} |
Just an average user here, but I have a couple initial thoughts: The photoshop history comparison is exactly how I'd expect this feature to work when you describe it in GitButler. However, an important note is that undo (ctrl+z) in photoshop traverses back up the history list, and redo goes forward, until you make a change, then the 'undone' changes are thrown away. For example, if you undo three times and are three levels back in history, but then draw on the canvas, a new history item is created which overwrites the three "future" history items and you can no longer redo. This differs from what is being pitched in Gitbutler, where undo-ing wouldn't really travel back up the history list but would instead add a new history entry. I guess the history would be more of a forking tree in GitButler, rather than a one dimensional list. I like the idea of not ever overwriting "undo-ed" changes, but from a complexity standpoint I agree with @PavelLaptev that I wouldn't necessarily treat this as an undo feature in the traditional sense and I'm not sure I'd map it to ctrl+z. As a user, for undo/redo, I think I'd expect to be able to ctrl+z ten times and end up at a state I was in ten actions ago, without cluttering the snapshots or commits with a bunch of "revert" changes. But, a non-destructive 'snapshot' sidebar seems super useful as well. Not to feature creep, but I wonder if it's worth having both functions, a more simple ctrl+z/undo/redo that is potentially destructive to quickly undo mis-clicks and typos, and a more in-depth snapshot sidebar that tracks every change ever made for when you need to dig through the history for more complex operations.
Personally, I would expect (and want) repeated cmd+Z presses to traverse back in history.
Personally I think this is critical. It seems like there will be hundreds of snapshots generated, and for this tool to be useful at all I think I'd need a UI to see the specific differences that restoring to this snapshot would apply. Another common use case for me would be to view snapshots without necessarily restoring them -- I might have started writing some code, changed my mind and deleted it, written different code, changed my mind back, but then want to go back to that snapshot and be able to copy/paste the code I deleted into my current working file without resetting the whole file to that snapshot. If that makes sense. Anyway, that's just my two cents. Very excited about this feature and gitbutler in general, it really solves a ton of friction I've had trying to use git personally. |
Thanks for your feedback on this, @slingshotvfx. I agree about separating snapshots from undo/redo. Figma provides a good example of this:
Additionally, I agree with @slingshotvfx about previewing file changes. This is crucial, especially if you need to go far back in the history. I think @krlvi sees this feature as more of a short memory track, where you wouldn't necessarily try to restore something from months ago. I tend to agree, because having extensive history within a Git GUI feels like creating "Git inside Git." I can hardly imagine a case where you'd need to restore a project state from three months ago. Also, the deeper you go into snapshot history, the more likely you'll encounter artifacts, mismatches, or conflicts. I'm not sure if we should restrict how far back you can go in the snapshot history, but I doubt that older snapshots hold much value. Currently, there are no limits. As a first step, I suggest focusing on implementing "snapshots." This seems more valuable than "undo/redo" with "Ctrl + Z." |
I've created a draft of the history sideview: |
I love the design @PavelLaptev! You raise very good points @slingshotvfx @PavelLaptev. Regarding the spammy nature of certain actions we could either skip creating those, or we could just filter them out from the UI (in case we change our mind later). Somehow I suspect that the most "spammy" snapshot will be Regarding Cmd+Z i agree that we don't wanna break the expectations ppl have, maybe we can ship the history without a hotkey and then think how to do this properly as we iterate |
ah, also, about previewing a specific snapshot I will try to have something implemented this week @PavelLaptev @slingshotvfx |
Okay, I implemented an endpoint for getting the diff of a specific snapshot (#3740), and updated the top comment here
This will give you the diffs that that specific snapshot has, compared to the snapshot before it. Here's an example usage in the mock UI, it only prints the content in the console https://github.com/gitbutlerapp/gitbutler/blob/master/app/src/lib/components/History.svelte#L97 @PavelLaptev i guess when we display that, a primary use case is the ability to copy-paste |
@Caleb-T-Owens thanks for the explanation. In "Undo/Redo" context, I think it makes sense.
@krlvi thanks for adding this, I'll check it out and see how we can design this. |
Hi @PavelLaptev, I've now gone through the full discussion. Revert Snapshots.I've seen revert snapshots mentioned a couple of times, and I know they're currently implemented in the app too, but I don't understand why they're needed. I would appreciate me if someone could help my understanding as to why they're beneficial. In my current mental model, they just don't seem helpful. If my snapshot history looks like:
If I restore to Snapshot 2, Snapshot 3 is still there to go back to the future to. The only time we need to make a new snapshot before going back to a previous time is if there have been text changes or untracked operations made since the last snapshot was taken The History ViewOut of the gate; it looks very cool, and I can see how the incremental changes in there are helpful. I think the main thing that I'm interested in is how will this play into things like code replay in the long run I do however think that we should try to get Undo/Redo working will enough that this doesn't need to be used instead of Cmd+z |
@Caleb-T-Owens, I see the "History" feature as something different from just "Undo/Redo." It's more like snapshots or versions of my current project. When I restore a Snapshot 1, the app shouldn't erase or overwrite any existing snapshots. Instead, it should create a new snapshot/version on top of it. This creates a "new" state of the project that comes from Snapshot 1. It's useful when you're experimenting with different changes but still want to keep a stable version to fall back to. For example, you might want to bring back or just check some code you deleted a day or week ago. Another reason it should work this way, in my opinion, is that it's more "foolproof." Restoring versions could cause unpredictable errors due to conflicts or edge cases. If restoring Snapshot 1 doesn't work for some reason, I can still go back to Snapshot 3. It also ensures that users can't accidentally erase or damage their current code, adding a safety net. While snapshots give more extensive control and flexibility, they shouldn't replace the basic Undo/Redo (Cmd+Z/Cmd+Shift+Z) functionality. Ideally, Undo/Redo handles simple day-to-day corrections, while revert snapshots offer broader restoration options. An example of this approach is Figma. They have "Undo/Redo" for basic corrections, plus a "History" feature where it creates new versions without deleting old ones. Here are some screenshots showing how Figma does it: The difference between Figma's "Undo/Redo" and "History":
|
@Caleb-T-Owens, how will it work if I jump back to an earlier point in history and then make new changes? Does it overwrite the existing history or it will look like this? |
@PavelLaptev I think it would be important to still let the user have access to the alternate timeline, so I think if we did like that, but perhaps if there is an expandy/accordion button which can show/hide the alternate history |
If you were to go to a snapshot in a forked history, that forked history would become the main timeline, and the other would then be displayed as a forked history |
I see, is that how the flow should look like @Caleb-T-Owens? Link to figma if you need to edit this |
I would rather not do forked history. I think that becomes quite complicated both from a data and UI perspective. I would much rather simply add the revert to the top of the timeline. It's always a simple history of "what did my working directory look like". If you look at Jujutsu, they have something similar. If you run To be honest, I'm not sure that |
i also agree with the idea of keeping it simple for the first iteration so that we can see how it feels during usage. @PavelLaptev i like the designs, just curious - how does one trigger the "restore" from a snapshot as well as "preview" it? (btw, note that not all snapshots can be previewed, only the ones that have file changes - for example "File changes" or "Update base" or "Delete branch (if it had file changes)" etc |
@krlvi, that's what I'll check during development. |
This is now implemented with v0.12.0 https://discord.com/channels/1060193121130000425/1183737922785116161/1246475064006807575 |
Background
We want to create a user interface for programmers using GitButler to be able to undo and redo changes they make with GitButler as well as changes in the repository. This includes:
This is similar to "Command/Control-Z" but more flexible. Some applications like Photoshop (and even VSCode) have the notion of an "undo history" - this is what we are aiming for.
Snapshots
The GitButler application already has the concept of a "snapshot". A snapshot represents the complete state of the project at a specific point in time.
NB: Snapshots are currently feature flagged. To enable snapshots edit the
'/Users/<username>/Library/Application Support/com.gitbutler.app/projects.json'
file, setting"enable_snapshots": true
on the project for which you want to enable this for. Then, in the app, the snapshots UI is toggled withCmd+Shift+H
When are snapshots created?
Snapshot creation is triggered under the following conditions:
default_snapshot_lines_threshold
)What does a snapshot contain?
A snapshot has everything needed to restore the project to a given state, therefore a lot of content can in theory be extracted. Currently, when listing snapshots the following structure is available on the API:
Link to the Operation types available.
Most operations on the GitButler API create snapshots, and they are reflected by the OperationType enum.
If a snapshot is created as a result of restoring to a previous snapshot, the OperationType will be
RestoreFromSnapshot
.If a snapshot is created as a result of simply performing a number of file changes in the working directory, the OperationType will be
FileChanges
.Trailers:
Depending on what triggered a snapshot, there may be additional informatio saved in a trailer. Currently this only applies to snapshots triggered by a restore operation (
RestoreFromSnapshot
). Those snapshots contain a trailer with the keyrestored_from
for which the value is the sha of the snapshot that was restored from.In the future we can add additional info to trailers, specific to the operation that triggered the snapshot. For example
moved_from
andmoved_to
for snapshots triggered by a move operation, orold_name
andnew_name
for snapshots triggered by a rename operation.Restoring to a snapshot
Restoring to a snapshot is trigered by the user with an api call.
This means that restoring is not an undo of the change in the snapshot but timetravel to that snapshot.
Whenever a restore operation is performed, it is followed by a new snapshot creation with the
RestoreFromSnapshot
type/trigger (and it contains arestored_from
trailer referring to the id of the snapshot that was restored from).How are snapshots saved and restored?
Out of scope for this UX discussion, check the code in
https://github.com/gitbutlerapp/gitbutler/blob/master/crates/gitbutler-core/src/ops/oplog.rs
Snapshot history visualized
The app currently has is a mock UI for visualizing the snapshot history while we are designing a proper UI for this. The following is an illustration of the view snapshot history (1), restore to a snapshot (2) and restore back (3) uses cases.
View snapshot history
FileChanges
snapshot is triggered when there is at least 20 lines of added + removed code, as compared to the previous snapshot. (In the screenshot the threshold is configured to a smaller value)Restore to a snapshot
Let's restore to snapshot
adc6d74
(This is the state after the file changes were made but before the commit was created). Now the project looks the way it before the commit was created (as reflected in the rest of the UI). The branch name also looks the way it did before it was renamed.adc6d74
the newest snapshot is of trigger typeRestoreFromSnapshot
and contains a reference to the snapshot that it was restored from.In this scenario 2, as far as UX is concerned we could conceptually "gray out" the snapshots 2.2 and 2.3 because with 2.1 we have time traveled to 2.4. Of course this could be achieved by also collapsing / hiding those entries.
Undoing the undo
Let's say that the restore operation from (2) was a mistake and lets restore to the point where we started from in (1). This means restoring to the snapshot that was flagged as "current" in the begining -
df89e5c
. Here's how that looks like:RestoreFromSnapshot
trigger is created, referencingdf89e5c
from 1.1.Questions
Getting the details of a specific snapshot
It is possible to get the diff of a specific snapshot with the
snapshot_diff
command. This will get a diff between the state of the workdir (project files) in the snapshot and the state of the workdir in the snapshot before it.Note that some snapshots represent changes to app state (for example name change of virtual branches) and in those cases, the working directory is the same as the previous snapshot.
UX needs
For now, we wanna facilitate the following:
To achieve all of that we need to be able present information in a way that is glance-able and easy to understand. We wanna make it visually clear what the different operations were and when they occured. When restoring, it should be clear to what point the user is restoring to.
Challenges
CreatedCommit
it may be unclear if that means that I will restore to a point before or after the commit was created.RestoreFromSnapshot
snapshot entry, it may be non-obvious that all the snapshots that are between it and the one it restored from are not part of the current state (but can be restored to).Lets discuss 💬
Similar to #3121, the purpose of this GH issue is to invite a discussion and maybe go over some drafts / ideas that come up. @schacon @mtsgrd @PavelLaptev @Qix- @Caleb-T-Owens let me know if I have missed something
The text was updated successfully, but these errors were encountered: