Checkpoints in SourceCraft Code Assistant

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.

Configuration settings

To enable checkpoints:

1. In the chat's top panel, click Settings.
2. On the left-hand panel, navigate to Checkpoints.
3. Select Enable automatic checkpoints.

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

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 the differences between the current project state and the previous checkpoint, and restore the project to that earlier state.

Viewing differences

To compare the current state of files with the previous checkpoint:

1. Find the checkpoint in the chat history.
2. Click View Diff on its right.
3. 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

To restore your project to the state of a previous checkpoint:

1. Find the checkpoint at hand in the chat history.
2. Click Restore Checkpoint on its right.
3. 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

Checkpoint 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

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

Checkpoints are linked to tasks, meaning they are task-specific.

Computing differences

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

The checkpoint system uses intelligent file exclusion to track only relevant files:

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

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

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

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

If the system detects nested Git repositories in your workspace, it disables checkpoints. To enable checkpoints, delete or move all nested repositories.

Managing parallelism

A dedicated extension keeps checkpoints from being created multiple times within one streaming operation. There is no special queue for Git operations.