Copilot CLI: document rolling back changes made during a CLI session (#60810)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com>
Co-authored-by: Vanessa <vgrl@github.com>

Author: 5 people

content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back.md

@@ -0,0 +1,75 @@
+---
+title: Canceling a {% data variables.copilot.copilot_cli %} operation and rolling back changes
+shortTitle: Cancel and roll back
+intro: 'Find out about the different ways to cancel an active {% data variables.product.prodname_copilot_short %} operation, and how to roll back changes made during a session if the result isn''t what you expected.'
+versions:
+  feature: copilot
+contentType: concepts
+docsTeamMetrics:
+  - copilot-cli
+category:
+  - Learn about Copilot # Copilot discovery page
+  - Learn about Copilot CLI # Copilot CLI bespoke page
+---
+
+## Introduction
+
+When you work in an interactive {% data variables.copilot.copilot_cli_short %} session, you can press <kbd>Esc</kbd> or <kbd>Ctrl</kbd>+<kbd>C</kbd> to control what {% data variables.product.prodname_copilot_short %} is doing. Both keypresses can cancel operations, but they work slightly differently:
+
+* <kbd>Ctrl</kbd>+<kbd>C</kbd> immediately stops the current operation.
+* A single <kbd>Esc</kbd> keypress gives you more gradual control—letting you dismiss dialogs, clear queued prompts, or cancel an operation in stages.
+
+If {% data variables.product.prodname_copilot_short %} has already made changes and you want to undo them, you can roll back your workspace to a previous point in the session. {% data variables.copilot.copilot_cli_short %} takes a snapshot of your workspace state each time you enter a prompt, and this allows you to rewind to an earlier state by pressing <kbd>Esc</kbd> twice when {% data variables.product.prodname_copilot_short %} is idle and the input area is empty.
+
+## What pressing Esc does in different situations
+
+Pressing <kbd>Esc</kbd> once performs different actions depending on the current state of the session:
+
+| Current state | What pressing <kbd>Esc</kbd> does |
+| ------------- | ------------------------ |
+| {% data variables.product.prodname_copilot_short %} is active with no queued prompts. | Cancels the running operation. |
+| {% data variables.product.prodname_copilot_short %} is active and there are queued prompts. | Clears the queued prompts without stopping the current operation. |
+| A dialog, overlay, or picker is open. | Closes the dialog, overlay, or picker. |
+| {% data variables.product.prodname_copilot_short %} is idle. | Shows a brief reminder that pressing <kbd>Esc</kbd> again quickly will open the rewind picker. See [Rolling back changes](#rolling-back-changes). |
+
+## When to use Esc instead of Ctrl+C
+
+The main difference between these two ways of canceling an operation is that <kbd>Esc</kbd> is designed for gradual, targeted intervention, while <kbd>Ctrl</kbd>+<kbd>C</kbd> is a hard stop.
+
+Use <kbd>Esc</kbd> when you want to interact with {% data variables.product.prodname_copilot_short %} without necessarily ending the current operation. For example, if a permission dialog appears and you want to deny that specific request, pressing <kbd>Esc</kbd> dismisses the dialog and {% data variables.product.prodname_copilot_short %} continues working—it just won't use the tool you denied. Similarly, if you've queued follow-up prompts and want to cancel them without interrupting the work already in progress, <kbd>Esc</kbd> clears the queue while the current operation keeps running. Pressing <kbd>Esc</kbd> only cancels the operation outright if there are no dialogs open and no queued prompts to clear first.
+
+Use <kbd>Ctrl</kbd>+<kbd>C</kbd> when you want to stop everything at once. It immediately cancels the active operation and clears any queued prompts in a single keypress. Any file write that is already in progress will complete—files are not left corrupted mid-write—but any remaining planned changes are abandoned. Pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> a second time within two seconds, when the input area is empty, exits the session entirely.
+
+As a rule of thumb, use <kbd>Esc</kbd> when you want to intervene selectively, and <kbd>Ctrl</kbd>+<kbd>C</kbd> when you want to stop and start over.
+
+## Rolling back changes
+
+While {% data variables.product.prodname_copilot_short %} is inactive and there is no text in the input area, you can press <kbd>Esc</kbd> twice to display a list of points in your current session that you can roll back to. Each point corresponds to a snapshot of your workspace that was taken immediately before {% data variables.product.prodname_copilot_short %} started working on the prompt shown in the list.
+
+For full details of how to use the double <kbd>Esc</kbd> keypress to roll back changes made during a session, see [AUTOTITLE](/copilot/how-tos/copilot-cli/roll-back-changes).
+
+> [!WARNING]
+> {% data reusables.copilot.copilot-cli.cli-rewind-warning %}
+
+### What happens when you roll back
+
+When you select a snapshot from the rewind picker, the following actions occur:
+
+1. **Git state is restored.** The repository is checked out to the Git commit and branch recorded in the snapshot.
+1. **Untracked files are cleaned.** Files that did not exist at the time of the snapshot are removed.
+1. **Modified files are restored.** Files that were changed after the snapshot are reverted to their backed-up state, including permissions and staging state.
+1. **Session history is truncated.** The conversation is rewound to the point where the selected snapshot was taken. All messages and tool calls that occurred after that point are removed from the session.
+1. **Snapshots are removed.** The selected snapshot and all snapshots after it are permanently deleted. Only snapshots from earlier conversation steps remain available for future rewinds.
+1. **Rollback confirmed.** After the rollback, {% data variables.product.prodname_copilot_short %} displays a message indicating how many files were restored.
+1. **Your prompt is restored.** The prompt associated with the selected snapshot is placed in the input area.
+
+### Changes that can't be rolled back
+
+Rewind is unavailable in the following situations:
+
+* **Files over 10 MB.** Individual files larger than 10 MB are skipped during snapshot creation. Changes to these files are not restored during a rollback.
+* **More than 500 changed files.** If more than 500 files were changed during a single step of a CLI conversation, a snapshot is not created for that step. You will not be able to roll back changes made in that step. Earlier snapshots are unaffected.
+
+## Further reading
+
+* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference)

content/copilot/concepts/agents/copilot-cli/index.md

@@ -8,6 +8,7 @@ versions:
 children:
   - /about-copilot-cli
   - /comparing-cli-features
+  - /cancel-and-roll-back
   - /about-remote-access
   - /about-custom-agents
   - /about-cli-plugins

content/copilot/how-tos/copilot-cli/index.md

@@ -25,9 +25,11 @@ children:
   - /use-copilot-cli-agents
   - /administer-copilot-cli-for-your-enterprise
   - /speed-up-task-completion
+  - /roll-back-changes
   - /chronicle
   - /content/copilot/concepts/agents/copilot-cli/about-copilot-cli
   - /content/copilot/concepts/agents/copilot-cli/comparing-cli-features
+  - /content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back
   - /content/copilot/concepts/agents/about-agent-skills
   - /content/copilot/concepts/agents/copilot-cli/about-cli-plugins
   - /content/copilot/concepts/agents/copilot-cli/autopilot

content/copilot/how-tos/copilot-cli/roll-back-changes.md

@@ -0,0 +1,70 @@
+---
+title: Rolling back changes made during a {% data variables.copilot.copilot_cli %} session
+shortTitle: Roll back changes
+intro: 'Rewind your {% data variables.copilot.copilot_cli_short %} session to a previous prompt to undo changes and restore your repository to a previous state.'
+versions:
+  feature: copilot
+contentType: how-tos
+category:
+  - Author and optimize with Copilot # Copilot discovery page
+  - Build with Copilot CLI # Copilot CLI bespoke page
+docsTeamMetrics:
+  - copilot-cli
+---
+
+## Introduction
+
+When you work in an interactive {% data variables.copilot.copilot_cli_short %} session, {% data variables.product.prodname_copilot_short %} can make changes to files, run shell commands, and modify your repository. If the result isn't what you expected, you can rewind to a previous point in the session to undo those changes.
+
+When you enter a prompt, the first thing {% data variables.copilot.copilot_cli_short %} does is take a snapshot of your workspace state. This snapshot allows you to roll back to that point in the session if you need to. You can trigger a rewind by pressing <kbd>Esc</kbd> twice, or by using the `/undo` slash command.
+
+This article explains how to roll back changes. For more conceptual information about rewinding to an earlier point in a session, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/cancel-and-roll-back).
+
+## Prerequisites
+
+* **You must be working in a Git repository with at least one commit.** {% data variables.copilot.copilot_cli_short %} uses Git operations to track and restore workspace state.
+* **A snapshot must exist.** Snapshots are created automatically at the start of each of your interactions with {% data variables.product.prodname_copilot_short %} in a CLI session. You can't roll back changes made before your first prompt in a session, or to the repository state for a step where snapshot creation was skipped, see [Changes that can't be rolled back](/copilot/concepts/agents/copilot-cli/cancel-and-roll-back#changes-that-cant-be-rolled-back).
+
+## Rolling back with a double Esc keypress
+
+> [!WARNING]
+> * {% data reusables.copilot.copilot-cli.cli-rewind-warning %}
+> * Rewinding cannot be undone. Once you roll back to a snapshot, all snapshots and session history after that point are permanently removed.
+
+When {% data variables.product.prodname_copilot_short %} has finished responding to a prompt you've entered:
+
+1. Make sure the input area is empty. If there's text in the input area, pressing <kbd>Esc</kbd> twice in quick succession clears the text.
+1. Press <kbd>Esc</kbd> twice in quick succession to open the rewind picker.
+
+   The rewind picker lists the available snapshots for the current session, with the most recent first. The ten most recent snapshots are displayed. If there are more than ten snapshots available you can use the <kbd>↓</kbd> arrow key to scroll down through earlier snapshots.
+
+   For each snapshot, the beginning of the prompt you entered is shown, with an indication of how long ago you submitted it.
+
+1. Choose a snapshot to roll back to. This will return you to the state of the repository when you entered the associated prompt.
+
+   > [!NOTE]
+   > The repository is rolled back to its state immediately before {% data variables.product.prodname_copilot_short %} started working on the prompt, not immediately after it finished working on the prompt.
+
+   The prompt you selected is shown in the input area, so you can edit and resubmit it, if required.
+
+## Rolling back with the `/undo` slash command
+
+The `/undo` slash command, and its alias `/rewind`, provide an alternative way of opening the rewind picker.
+
+Both commands produce the same result that you get by pressing <kbd>Esc</kbd> twice when {% data variables.product.prodname_copilot_short %} is idle and there is no text in the input area.
+
+## Verifying the rollback
+
+After rolling back, you can use Git commands to verify the state of your repository and confirm that it matches your expectations.
+
+Typing `!` allows you to run shell commands directly from the {% data variables.copilot.copilot_cli_short %} input prompt, so you don't need to exit the CLI to check the repository state.
+
+| To do this | Enter this command       |
+| ---------- | ------------------------ |
+| Check which files show as modified, staged, or untracked. | `! git status` |
+| Show the SHA and commit message of the current commit.    | `! git log --oneline -1` |
+| Review the unstaged changes. | `! git diff` |
+
+## Further reading
+
+* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference)

data/reusables/copilot/copilot-cli/cli-rewind-warning.md

@@ -0,0 +1 @@
+Rewinding restores your entire workspace to the state it was in at the selected snapshot. This reverts all changes made after that point—not only changes made by {% data variables.product.prodname_copilot_short %}, but also any manual edits, and changes resulting from shell commands. Any new files created in the workspace after the snapshot was taken are deleted, irrespective of their Git status.