feat: Create snapshots when running notebooks

README.md

@@ -16,7 +16,6 @@ A powerful [Visual Studio Code](https://marketplace.visualstudio.com/items?itemN
 
 ![Deepnote Projects](./assets/deepnote-projects.png)
 
-
 Run Deepnote locally inside your IDE and unlock the next generation of data workflows:
 
 - **Rich block types:** Combine Python, Markdown, data visualizations, tables, and more — all in one place
@@ -66,6 +65,7 @@ Open the Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`) and type `Deepnote` t
 | `Deepnote: Import Notebook`        | Import an existing notebook into your project      |
 | `Notebook: Select Notebook Kernel` | Select or switch kernels within your notebook      |
 | `Notebook: Change Cell Language`   | Change the language of the cell currently in focus |
+| `Deepnote: Enable Snapshots`       | Enable snapshot mode for the current workspace     |
 
 ### Database integrations
 
@@ -89,6 +89,24 @@ SELECT * FROM users WHERE created_at > '2024-01-01'
 
 Results are displayed as interactive tables that you can explore and export.
 
+### Snapshot mode
+
+Snapshot mode gives you a historical, portable record of all notebook executions without polluting your main project files. This makes it easier to work with Git since outputs are stored separately from your source code.
+
+**How it works:**
+
+- Execution outputs are saved to a `snapshots/` folder alongside your project
+- Your main `.deepnote` file stays clean (no outputs), making diffs readable
+- Each "Run All" execution creates a timestamped snapshot for historical tracking
+- Running individual cells updates only the latest snapshot
+
+**To enable:**
+
+1. Open Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
+2. Run `Deepnote: Enable Snapshots`
+
+Once enabled, snapshots are automatically created when you execute notebooks. You can add the `snapshots/` folder to `.gitignore` to keep outputs local, or commit them to share execution history with your team.
+
 ## Need help?
 
 - Join our [Community](https://github.com/deepnote/deepnote/discussions)!

package.json

@@ -93,6 +93,16 @@
                 "category": "Deepnote",
                 "icon": "$(reveal)"
             },
+            {
+                "command": "deepnote.enableSnapshots",
+                "title": "%deepnote.commands.enableSnapshots.title%",
+                "category": "Deepnote"
+            },
+            {
+                "command": "deepnote.disableSnapshots",
+                "title": "%deepnote.commands.disableSnapshots.title%",
+                "category": "Deepnote"
+            },
             {
                 "command": "deepnote.environments.create",
                 "title": "%deepnote.commands.environments.create.title%",
@@ -1629,6 +1639,12 @@
                     "description": "Disable SSL certificate verification (for development only)",
                     "scope": "application"
                 },
+                "deepnote.snapshots.enabled": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "When enabled, outputs are saved to separate snapshot files in a 'snapshots' folder instead of the main .deepnote file.",
+                    "scope": "resource"
+                },
                 "deepnote.experiments.enabled": {
                     "type": "boolean",
                     "default": true,

package.nls.json

@@ -250,6 +250,8 @@
     "deepnote.commands.openNotebook.title": "Open Notebook",
     "deepnote.commands.openFile.title": "Open File",
     "deepnote.commands.revealInExplorer.title": "Reveal in Explorer",
+    "deepnote.commands.enableSnapshots.title": "Enable Snapshots",
+    "deepnote.commands.disableSnapshots.title": "Disable Snapshots",
     "deepnote.commands.manageIntegrations.title": "Manage Integrations",
     "deepnote.commands.newProject.title": "New Project",
     "deepnote.commands.importNotebook.title": "Import Notebook",

src/kernels/execution/cellExecutionQueue.ts

@@ -324,5 +324,14 @@ export class CellExecutionQueue implements Disposable {
                 break;
             }
         }
+
+        // Notify snapshot service that execution is complete
+        if (this.snapshotService && this.notebook) {
+            try {
+                await this.snapshotService.onExecutionComplete(this.notebook.uri.toString());
+            } catch (error) {
+                logger.warn('[CellExecutionQueue] Failed to handle execution complete for snapshots', error);
+            }
+        }
     }
 }

src/notebooks/deepnote/deepnoteActivationService.ts

@@ -10,6 +10,7 @@ import { DeepnoteExplorerView } from './deepnoteExplorerView';
 import { IIntegrationManager } from './integrations/types';
 import { DeepnoteInputBlockEditProtection } from './deepnoteInputBlockEditProtection';
 import { ISnapshotMetadataService, ISnapshotMetadataServiceFull } from './snapshotMetadataService';
+import { ISnapshotFileService } from './snapshotFileServiceTypes';
 
 /**
  * Service responsible for activating and configuring Deepnote notebook support in VS Code.
@@ -30,7 +31,8 @@ export class DeepnoteActivationService implements IExtensionSyncActivationServic
         @inject(IDeepnoteNotebookManager) private readonly notebookManager: IDeepnoteNotebookManager,
         @inject(IIntegrationManager) integrationManager: IIntegrationManager,
         @inject(ILogger) private readonly logger: ILogger,
-        @inject(ISnapshotMetadataService) @optional() private readonly snapshotService?: ISnapshotMetadataServiceFull
+        @inject(ISnapshotMetadataService) @optional() private readonly snapshotService?: ISnapshotMetadataServiceFull,
+        @inject(ISnapshotFileService) @optional() private readonly snapshotFileService?: ISnapshotFileService
     ) {
         this.integrationManager = integrationManager;
     }
@@ -40,7 +42,11 @@ export class DeepnoteActivationService implements IExtensionSyncActivationServic
      * Called during extension activation to set up Deepnote integration.
      */
     public activate() {
-        this.serializer = new DeepnoteNotebookSerializer(this.notebookManager, this.snapshotService);
+        this.serializer = new DeepnoteNotebookSerializer(
+            this.notebookManager,
+            this.snapshotService,
+            this.snapshotFileService
+        );
         this.explorerView = new DeepnoteExplorerView(this.extensionContext, this.notebookManager, this.logger);
         this.editProtection = new DeepnoteInputBlockEditProtection(this.logger);
 

src/notebooks/deepnote/deepnoteNotebookCommandListener.ts

@@ -1,6 +1,7 @@
 import { injectable, inject } from 'inversify';
 import {
     commands,
+    ConfigurationTarget,
     window,
     NotebookCellData,
     NotebookCellKind,
@@ -14,7 +15,7 @@ import z from 'zod';
 
 import { logger } from '../../platform/logging';
 import { IExtensionSyncActivationService } from '../../platform/activation/types';
-import { IDisposableRegistry } from '../../platform/common/types';
+import { IConfigurationService, IDisposableRegistry } from '../../platform/common/types';
 import { Commands } from '../../platform/common/constants';
 import { notebookUpdaterUtils } from '../../kernels/execution/notebookUpdater';
 import { WrappedError } from '../../platform/errors/types';
@@ -139,7 +140,10 @@ export function getNextDeepnoteVariableName(cells: NotebookCell[], prefix: 'df'
  */
 @injectable()
 export class DeepnoteNotebookCommandListener implements IExtensionSyncActivationService {
-    constructor(@inject(IDisposableRegistry) private readonly disposableRegistry: IDisposableRegistry) {}
+    constructor(
+        @inject(IConfigurationService) private readonly configurationService: IConfigurationService,
+        @inject(IDisposableRegistry) private readonly disposableRegistry: IDisposableRegistry
+    ) {}
 
     /**
      * Activates the service by registering Deepnote-specific commands.
@@ -181,6 +185,10 @@ export class DeepnoteNotebookCommandListener implements IExtensionSyncActivation
         this.disposableRegistry.push(
             commands.registerCommand(Commands.AddButtonBlock, () => this.addInputBlock('button'))
         );
+        this.disposableRegistry.push(commands.registerCommand(Commands.EnableSnapshots, () => this.enableSnapshots()));
+        this.disposableRegistry.push(
+            commands.registerCommand(Commands.DisableSnapshots, () => this.disableSnapshots())
+        );
     }
 
     public async addSqlBlock(): Promise<void> {
@@ -368,4 +376,34 @@ export class DeepnoteNotebookCommandListener implements IExtensionSyncActivation
         // Enter edit mode on the new cell
         await commands.executeCommand('notebook.cell.edit');
     }
+
+    private async disableSnapshots(): Promise<void> {
+        try {
+            await this.configurationService.updateSetting(
+                'snapshots.enabled',
+                false,
+                undefined,
+                ConfigurationTarget.Workspace
+            );
+            void window.showInformationMessage(l10n.t('Snapshots disabled for this workspace.'));
+        } catch (error) {
+            logger.error('Failed to disable snapshots', error);
+            void window.showErrorMessage(l10n.t('Failed to disable snapshots.'));
+        }
+    }
+
+    private async enableSnapshots(): Promise<void> {
+        try {
+            await this.configurationService.updateSetting(
+                'snapshots.enabled',
+                true,
+                undefined,
+                ConfigurationTarget.Workspace
+            );
+            void window.showInformationMessage(l10n.t('Snapshots enabled for this workspace.'));
+        } catch (error) {
+            logger.error('Failed to enable snapshots', error);
+            void window.showErrorMessage(l10n.t('Failed to enable snapshots.'));
+        }
+    }
 }

src/notebooks/deepnote/deepnoteNotebookCommandListener.unit.test.ts

@@ -18,7 +18,7 @@ import {
     InputBlockType
 } from './deepnoteNotebookCommandListener';
 import { formatInputBlockCellContent, getInputBlockLanguage } from './inputBlockContentFormatter';
-import { IDisposable } from '../../platform/common/types';
+import { IConfigurationService, IDisposable } from '../../platform/common/types';
 import * as notebookUpdater from '../../kernels/execution/notebookUpdater';
 import { createMockedNotebookDocument } from '../../test/datascience/editor-integration/helpers';
 import { WrappedError } from '../../platform/errors/types';
@@ -29,11 +29,21 @@ suite('DeepnoteNotebookCommandListener', () => {
     let commandListener: DeepnoteNotebookCommandListener;
     let disposables: IDisposable[];
     let sandbox: sinon.SinonSandbox;
+    let mockConfigService: IConfigurationService;
+
+    function createMockConfigService(): IConfigurationService {
+        return {
+            getSettings: sinon.stub().returns({}),
+            updateSetting: sinon.stub().resolves(),
+            updateSectionSetting: sinon.stub().resolves()
+        } as unknown as IConfigurationService;
+    }
 
     setup(() => {
         sandbox = sinon.createSandbox();
         disposables = [];
-        commandListener = new DeepnoteNotebookCommandListener(disposables);
+        mockConfigService = createMockConfigService();
+        commandListener = new DeepnoteNotebookCommandListener(mockConfigService, disposables);
     });
 
     teardown(() => {
@@ -78,7 +88,7 @@ suite('DeepnoteNotebookCommandListener', () => {
 
             // Create new instance and activate again
             const disposables2: IDisposable[] = [];
-            const commandListener2 = new DeepnoteNotebookCommandListener(disposables2);
+            const commandListener2 = new DeepnoteNotebookCommandListener(createMockConfigService(), disposables2);
             commandListener2.activate();
 
             // Both should register the same number of commands

src/notebooks/deepnote/deepnoteNotebookManager.ts

@@ -11,8 +11,8 @@ import type { DeepnoteProject } from '../../platform/deepnote/deepnoteTypes';
 export class DeepnoteNotebookManager implements IDeepnoteNotebookManager {
     private readonly currentNotebookId = new Map<string, string>();
     private readonly originalProjects = new Map<string, DeepnoteProject>();
-    private readonly selectedNotebookByProject = new Map<string, string>();
     private readonly projectsWithInitNotebookRun = new Set<string>();
+    private readonly selectedNotebookByProject = new Map<string, string>();
 
     /**
      * Gets the currently selected notebook ID for a project.

src/notebooks/deepnote/deepnoteSerializer.ts

@@ -8,6 +8,7 @@ import { IDeepnoteNotebookManager } from '../types';
 import { DeepnoteDataConverter } from './deepnoteDataConverter';
 import type { DeepnoteNotebook } from '../../platform/deepnote/deepnoteTypes';
 import { ISnapshotMetadataService, ISnapshotMetadataServiceFull } from './snapshotMetadataService';
+import { ISnapshotFileService } from './snapshotFileServiceTypes';
 import { computeHash } from '../../platform/common/crypto';
 
 export type { DeepnoteBlock, DeepnoteFile } from '@deepnote/blocks';
@@ -56,7 +57,8 @@ export class DeepnoteNotebookSerializer implements NotebookSerializer {
 
     constructor(
         @inject(IDeepnoteNotebookManager) private readonly notebookManager: IDeepnoteNotebookManager,
-        @inject(ISnapshotMetadataService) @optional() private readonly snapshotService?: ISnapshotMetadataServiceFull
+        @inject(ISnapshotMetadataService) @optional() private readonly snapshotService?: ISnapshotMetadataServiceFull,
+        @inject(ISnapshotFileService) @optional() private readonly snapshotFileService?: ISnapshotFileService
     ) {}
 
     /**
@@ -114,10 +116,23 @@ export class DeepnoteNotebookSerializer implements NotebookSerializer {
                 throw new Error(l10n.t('No notebook selected or found'));
             }
 
-            const cells = this.converter.convertBlocksToCells(selectedNotebook.blocks ?? []);
+            let cells = this.converter.convertBlocksToCells(selectedNotebook.blocks ?? []);
 
             logger.debug(`DeepnoteSerializer: Converted ${cells.length} cells from notebook blocks`);
 
+            // Merge outputs from snapshot if snapshots are enabled
+            if (this.snapshotFileService?.isSnapshotsEnabled()) {
+                const snapshotOutputs = await this.snapshotFileService.readSnapshot(projectId);
+
+                if (snapshotOutputs) {
+                    logger.debug(`DeepnoteSerializer: Merging ${snapshotOutputs.size} outputs from snapshot`);
+                    const blocksWithOutputs = structuredClone(selectedNotebook.blocks ?? []);
+                    this.snapshotFileService.mergeOutputsIntoBlocks(blocksWithOutputs, snapshotOutputs);
+
+                    cells = this.converter.convertBlocksToCells(blocksWithOutputs);
+                }
+            }
+
             this.notebookManager.storeOriginalProject(deepnoteFile.project.id, deepnoteFile, selectedNotebook.id);
             logger.debug(`DeepnoteSerializer: Stored project ${projectId} in notebook manager`);
 
@@ -199,7 +214,15 @@ export class DeepnoteNotebookSerializer implements NotebookSerializer {
             // Add snapshot metadata to blocks (contentHash and execution timing)
             await this.addSnapshotMetadataToBlocks(blocks, data);
 
-            notebook.blocks = cloneWithoutCircularRefs<DeepnoteBlock[]>(blocks);
+            // Handle snapshot mode: strip outputs from main file (snapshots are created on execution, not save)
+            if (this.snapshotFileService?.isSnapshotsEnabled()) {
+                // Strip outputs from main file blocks - snapshots are created during cell execution
+                notebook.blocks = this.snapshotFileService.stripOutputsFromBlocks(blocks);
+                logger.debug('SerializeNotebook: Stripped outputs from main file (snapshot mode)');
+            } else {
+                // Default behavior: outputs in main file
+                notebook.blocks = cloneWithoutCircularRefs<DeepnoteBlock[]>(blocks);
+            }
 
             logger.debug('SerializeNotebook: Cloned blocks, updating modifiedAt');
 

src/notebooks/deepnote/deepnoteTreeDataProvider.ts

@@ -203,8 +203,9 @@ export class DeepnoteTreeDataProvider implements TreeDataProvider<DeepnoteTreeIt
         for (const workspaceFolder of workspace.workspaceFolders || []) {
             const pattern = new RelativePattern(workspaceFolder, '**/*.deepnote');
             const files = await workspace.findFiles(pattern);
+            const projectFiles = files.filter((file) => !file.path.endsWith('.snapshot.deepnote'));
 
-            for (const file of files) {
+            for (const file of projectFiles) {
                 try {
                     const project = await this.loadDeepnoteProject(file);
                     if (!project) {
@@ -316,16 +317,25 @@ export class DeepnoteTreeDataProvider implements TreeDataProvider<DeepnoteTreeIt
         }
 
         this.fileWatcher.onDidChange((uri) => {
+            if (uri.path.endsWith('.snapshot.deepnote')) {
+                return;
+            }
             // Use granular refresh for file changes
             void this.refreshProject(uri.path);
         });
 
-        this.fileWatcher.onDidCreate(() => {
+        this.fileWatcher.onDidCreate((uri) => {
+            if (uri.path.endsWith('.snapshot.deepnote')) {
+                return;
+            }
             // New file created, do full refresh
             this._onDidChangeTreeData.fire();
         });
 
         this.fileWatcher.onDidDelete((uri) => {
+            if (uri.path.endsWith('.snapshot.deepnote')) {
+                return;
+            }
             // File deleted, clear both caches and do full refresh
             this.cachedProjects.delete(uri.path);
             this.treeItemCache.delete(`project:${uri.path}`);