--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/checkpoints.md - https://sourcecraft.dev/portal/docs/ru/code-assistant/operations/agent/checkpoints.md title: Checkpoints in SourceCraft Code Assistant description: How to use checkpoints in SourceCraft Code Assistant to safely experiment with changes and restore previous file versions. --- > **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt # Checkpoints in SourceCraft Code Assistant {% note warning %} This feature is only available in Visual Studio Code. {% endnote %} While you are running tasks in Code Assistant, checkpoints automatically create file versions in your workspace, allowing you to safely explore AI suggestions and easily restore previous file versions. With checkpoints, you can: * Safely experiment with AI-suggested changes. * Easily restore previous file versions. * Compare various implementation methods. * Revert to earlier project states without losing progress. {% note info %} * Checkpoints are enabled by default. * You need Git installed to work with checkpoints. Follow [this installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). * The system auxiliary Git repository operates separately from your project's Git configuration. {% endnote %} ## Configuration settings {#configuration-settings} To enable checkpoints: 1. In the chat's top panel, click **Settings**. 1. On the left-hand panel, navigate to **Checkpoints**. 1. Select **Enable automatic checkpoints**. ## How checkpoints work {#how-checkpoints-work} Code Assistant creates snapshots of your project using an auxiliary Git repository, independent from your main version control system. These snapshots, called checkpoints, are created automatically prior to any file modifications to allow undoing of unwanted changes. Checkpoints are saved at task start and before file modifications. They are not created automatically before running commands. The system auxiliary repository stores checkpoints as Git commits, capturing: * File content changes * New files * Deleted files * Renamed files * Binary file changes ## Working with checkpoints {#working-with-checkpoints} The chat interface integrates checkpoints directly into your workflow. You can see checkpoints directly in the chat history: * The task's first checkpoint ( **Initial Checkpoint**) captures the initial state of your project. * Before modifying files, the system creates current checkpoints ( **Checkpoint**), allowing you to roll back easily. Each checkpoint allows you to [view](#viewing-differences) the differences between the current project state and the previous checkpoint, and [restore](#restoring-checkpoints) the project to that earlier state. ### Viewing differences {#viewing-differences} To compare the current state of files with the previous checkpoint: 1. Find the checkpoint in the chat history. 1. Click **View Diff** on its right. 1. View differences in comparison mode: * New lines are highlighted in green. * Deleted lines are highlighted in red. * Modified files are listed with detailed descriptions. * File renames may sometimes go undetected as differences primarily show file content changes between commits. * New or deleted files are clearly highlighted. ### Restoring checkpoints {#restoring-checkpoints} To restore your project to the state of a previous checkpoint: 1. Find the checkpoint at hand in the chat history. 1. Click **Restore Checkpoint** on its right. 1. Select a restore option: * **Restore files**: Only restores the workspace files to the checkpoint state, leaving the chat history unchanged. This option is perfect for comparing alternative implementations while keeping the chat context, so you can switch between project states seamlessly and quickly with no confirmation needed. * **Restore Files & Task**: Restores workspace files and deletes all subsequent chat messages. Use this option to fully revert your code and chat to the checkpoint state. This action requires confirmation in a dialog box since it cannot be undone. ## Technical implementation {#technical-implementation} ### Checkpoint architecture {#checkpoints-architecture} The checkpoint system features the following components: * System auxiliary Git repository: Separate repository created specifically to track checkpoints, serving as a permanent storage for checkpoint states. * Checkpoint service: Handles Git operations and manages states by: * Initializing the repository * Creating and saving checkpoints * Computing differences * Restoring the state * UI components: Chat interface elements that enable working with checkpoints. ### Restoring {#restoration-process} While restoring, Code Assistant: * Performs a hard reset to the specified checkpoint commit. * Copies all files from the system auxiliary repository to your workspace. * Updates the internal checkpoint tracking state. ### Storage type {#storage-type} Checkpoints are linked to tasks, meaning they are task-specific. ### Computing differences {#difference-calculation} Checkpoint comparison uses Git's built-in features to compute differences and generate structured file changes: * Modified files display changes line by line. * Binary files are accurately recognized and processed. * File renames may sometimes go undetected as differences primarily focus on file content changes between checkpoints. * File creation and deletion are clearly tracked. ### File exclusion and ignore patterns {#file-exclusion-and-ignore-patterns} The checkpoint system uses intelligent file exclusion to track only relevant files: #### Built-in exclusions {#built-in-exclusions} The system offers extensive built-in exclusion patterns that automatically ignore: * Build artifacts and dependency directories (`node_modules/`, `dist/`, and `build/`). * Media and binary files (images, video, and audio). * Cache and temporary files (`.cache/`, `.tmp/`, and `.bak`). * Configuration files with confidential information (`.env`). * Large data files (archives, executables, and binary files). * Database files and logs. The system writes these patterns to the `.git/info/exclude` file in the auxiliary repository during initialization. #### .gitignore support {#gitignore-support} The checkpoint system factors in `.gitignore` patterns in your workspace: * Files excluded via `.gitignore` will not initiate checkpoint creation. * Excluded files will not be listed among checkpoint differences. * Git's standard ignore rules apply when staging changes. #### Git LFS patterns {#git-lfs-patterns} Patterns specified in `.gitattributes` of your workspace for Git LFS are read and added to checkpoint exclusions. This helps exclude large LFS-managed files from tracking in the system auxiliary repository. #### .codeassistantignore behavior {#codeassistantignore-behavior} The `.codeassistantignore` file that manages AI access to your files is kept separate from checkpoint tracking. * Files excluded via `.codeassistantignore` but not via `.gitignore` will still be tracked in checkpoints. * You can still use checkpoints to restore changes in files inaccessible to the AI. This separation is intentional because `.codeassistantignore` manages AI access, not file version tracking. #### Nested Git repositories {#nested-git-repositories} If the system detects nested Git repositories in your workspace, it disables checkpoints. To enable checkpoints, delete or move all nested repositories. ### Managing parallelism {#parallelism-management} A dedicated extension keeps checkpoints from being created multiple times within one streaming operation. There is no special queue for Git operations.