Enhance checkpoints documentation: detail functionality, configuration, and usage with new images

Author: hannesrudolph

docs/advanced-usage/checkpoints.md

@@ -1,35 +1,241 @@
 # Checkpoints
 
-Checkpoints allow you to save the state of your project at a specific point in time during a task. This enables you to easily revert to a previous state if needed, providing a safety net for complex or potentially risky operations.
+Checkpoints automatically version your workspace files during Roo Code tasks, enabling non-destructive exploration of AI suggestions and easy recovery from unwanted changes.
+
+Checkpoints let you:
+- Safely experiment with AI-suggested changes
+- Easily recover from undesired modifications
+- Compare different implementation approaches
+- Revert to previous project states without losing work
+
+:::info Important Notes
+- **Checkpoints are enabled by default.**
+- **Git must be installed** for checkpoints to function - [see installation instructions](#git-installation)
+- No GitHub account or repository is required
+- No Git personal information configuration is needed
+- The shadow Git repository operates independently from your project's existing Git configuration
+:::
+
+## Configuration Options
+
+Access checkpoint settings in Roo Code settings under the "Checkpoints" section:
+
+1. Open Settings by clicking the gear icon <Codicon name="gear" /> → Checkpoints
+2. Check or uncheck the "Enable automatic checkpoints" checkbox
+
+   <img src="/img/checkpoints/checkpoints.png" alt="Checkpoint settings in Roo Code configuration" width="500" />
 
 ## How Checkpoints Work
 
-When checkpoints are enabled, Roo Code automatically creates a new checkpoint whenever:
+Roo Code creates immutable snapshots of your project using a shadow Git repository that operates independently from your own version control system. These checkpoints capture the complete state of tracked files at specific points in your AI-assisted workflow.
+
+Checkpoints are automatically created when:
+- A task begins (initial checkpoint)
+- Files are created, modified, or deleted
+- Commands are executed
+
+Each checkpoint is stored as a Git commit in the shadow repository, capturing:
+- File content changes
+- New files added to the workspace
+- Deleted files
+- Renamed files
+- Binary file changes
+
+
+## Working with Checkpoints
+
+Checkpoints are integrated directly into your workflow through the chat interface.
+
+Checkpoints appear directly in your chat history in two forms:
+
+- **Initial checkpoint** marks your starting project state
+   <img src="/img/checkpoints/checkpoints-1.png" alt="Initial checkpoint indicator in chat" width="500" />
+
+- **Regular checkpoints** appear after file modifications or command execution
+   <img src="/img/checkpoints/checkpoints-2.png" alt="Regular checkpoint indicator in chat" width="500" />
+
+Each checkpoint provides two primary functions:
+
+### Viewing Differences
+
+To compare your current workspace with a previous checkpoint:
+
+1. Locate the checkpoint in your chat history
+2. Click the checkpoint's `View Differences` button
+
+   <img src="/img/checkpoints/checkpoints-6.png" alt="View Differences button interface" width="100" />
+
+3. Review the differences in the comparison view:
+   - Added lines are highlighted in green
+   - Removed lines are highlighted in red
+   - Modified files are listed with detailed changes
+   - Renamed and moved files are tracked with their path changes
+   - New or deleted files are clearly marked
+
+<img src="/img/checkpoints/checkpoints-3.png" alt="View differences option for checkpoints" width="800" />
+
+### Restoring Checkpoints
+
+To restore a project to a previous checkpoint state:
+
+1. Locate the checkpoint in your chat history
+2. Click the checkpoint's `Restore Checkpoint` button
+   <img src="/img/checkpoints/checkpoints-7.png" alt="Restore checkpoint button interface" width="100" />
+3. Choose one of these restoration options:
+   
+   <img src="/img/checkpoints/checkpoints-4.png" alt="Restore checkpoint option" width="300" />
+
+   - **Restore Files Only** - Reverts only workspace files to checkpoint state without modifying conversation history. Ideal for comparing alternative implementations while maintaining chat context, allowing you to seamlessly switch between different project states. This option does not require confirmation and lets you quickly switch between different implementations.
+   
+   - **Restore Files & Task** - Reverts both workspace files AND removes all subsequent conversation messages. Use when you want to completely reset both your code and conversation back to the checkpoint's point in time. This option requires confirmation in a dialog as it cannot be undone.
+
+      <img src="/img/checkpoints/checkpoints-9.png" alt="Confirmation dialog for restoring checkpoint with files & task" width="300" />
+
+### Limitations and Considerations
+
+- **Scope**: Checkpoints only capture changes made during active Roo Code tasks
+- **External changes**: Modifications made outside of tasks (manual edits, other tools) aren't included
+- **Large files**: Very large binary files may impact performance
+- **Unsaved work**: Restoration will overwrite any unsaved changes in your workspace
+
+## Technical Implementation
+
+### Checkpoint Architecture
+
+The checkpoint system consists of:
+
+1. **Shadow Git Repository**: A separate Git repository created specifically for checkpoint tracking that functions as the persistent storage mechanism for checkpoint state.
+
+2. **Checkpoint Service**: Handles Git operations and state management through:
+   - Repository initialization
+   - Checkpoint creation and storage
+   - Diff computation
+   - State restoration
+
+3. **UI Components**: Interface elements displayed in the chat that enable interaction with checkpoints.
+
+### Restoration Process
+
+When restoration executes, Roo Code:
+- Runs `git clean` to remove any untracked files
+- Performs a hard reset to the specified checkpoint commit
+- Copies all files from the shadow repository to your workspace
+- Updates internal checkpoint tracking state
+
+### Storage Type
+
+Checkpoints are task-scoped, meaning they are specific to a single task.
+### Diff Computation
+
+Checkpoint comparison uses Git's underlying diff capabilities to produce structured file differences:
+- Modified files show line-by-line changes
+- Binary files are properly detected and handled
+- Renamed and moved files are tracked correctly
+- File creation and deletion are clearly identified
+
+### File Exclusion and Ignore Patterns
+
+The checkpoint system uses intelligent file exclusion to track only relevant files:
+
+#### Built-in Exclusions
+
+The system has comprehensive built-in exclusion patterns that automatically ignore:
+- Build artifacts and dependency directories (`node_modules/`, `dist/`, `build/`)
+- Media files and binary assets (images, videos, audio)
+- Cache and temporary files (`.cache/`, `.tmp/`, `.bak`)
+- Configuration files with sensitive information (`.env`)
+- Large data files (archives, executables, binaries)
+- Database files and logs
+
+These patterns are written to the shadow repository's `.git/info/exclude` file during initialization.
+
+#### .gitignore Support
+
+The checkpoint system respects `.gitignore` patterns in your workspace:
+- Files excluded by `.gitignore` won't trigger checkpoint creation
+- Excluded files won't appear in checkpoint diffs
+- Standard Git ignore rules apply when staging file changes
+
+#### .rooignore Behavior
+
+The `.rooignore` file (which controls AI access to files) is separate from checkpoint tracking:
+- Files excluded by `.rooignore` but not by `.gitignore` will still be checkpointed
+- Changes to AI-inaccessible files can still be restored through checkpoints
+
+This separation is intentional, as `.rooignore` limits which files the AI can access, not which files should be tracked for version history.
+
+#### Nested Git Repositories
+
+The checkpoint system includes special handling for nested Git repositories:
+- Temporarily renames nested `.git` directories to `.git_disabled` during operations
+- Restores them after operations complete
+- Allows proper tracking of files in nested repositories
+- Ensures nested repositories remain functional and unaffected
+
+### Concurrency Control
+
+Operations are queued to prevent concurrent Git operations that might corrupt repository state. This ensures that rapid checkpoint operations complete safely even when requested in quick succession.
+
+## Git Installation
+
+Checkpoints require Git to be installed on your system. The implementation uses the `simple-git` library, which relies on Git command-line tools to create and manage shadow repositories.
+
+### macOS
 
-*   A task is started.
-*   A file is created, modified, or deleted.
-*   A command is executed.
+1. **Install with Homebrew (recommended)**:
+   ```
+   brew install git
+   ```
 
-## Viewing Checkpoints
+2. **Alternative: Install with Xcode Command Line Tools**:
+   ```
+   xcode-select --install
+   ```
 
-You can view the list of checkpoints for a task in the chat history.
+3. **Verify installation**:
+   - Open Terminal
+   - Type `git --version`
+   - You should see a version number like `git version 2.40.0`
 
-## Restoring a Checkpoint
+### Windows
 
-To restore a checkpoint:
+1. **Download Git for Windows**:
+   - Visit https://git-scm.com/download/win
+   - The download should start automatically
 
-1.  **Open the chat view.**
-2.  **Find the checkpoint** you want to restore in the chat history.
-3.  **Click on the restore button**
+2. **Run the installer**:
+   - Accept the license agreement
+   - Choose installation location (default is recommended)
+   - Select components (default options are typically sufficient)
+   - Choose the default editor
+   - Choose how to use Git from the command line (recommended: Git from the command line and also from 3rd-party software)
+   - Configure line ending conversions (recommended: Checkout Windows-style, commit Unix-style)
+   - Complete the installation
 
-This will revert all files in your project to their state at that checkpoint.
+3. **Verify installation**:
+   - Open Command Prompt or PowerShell
+   - Type `git --version`
+   - You should see a version number like `git version 2.40.0.windows.1`
 
-**Note:**  Restoring a checkpoint will overwrite any changes you've made since that checkpoint.  It's recommended to commit your work before restoring a checkpoint.
+### Linux
 
-## Limitations
+**Debian/Ubuntu**:
+```
+sudo apt update
+sudo apt install git
+```
 
-*   Checkpoints are only created during active Roo Code tasks. Changes made outside of a task will not be captured.
+**Fedora**:
+```
+sudo dnf install git
+```
 
-## Enabling/Disabling Checkpoints
+**Arch Linux**:
+```
+sudo pacman -S git
+```
 
-You can enable or disable checkpoints in the Roo Code settings.  Look for the "Enable automatic checkpoints" checkbox under Advanced Settings.
+**Verify installation**:
+- Open Terminal
+- Type `git --version`
+- You should see a version number