Version Control

The Version Control system provides comprehensive change tracking and project history management directly within the browser environment. Using isomorphic-git technology, it delivers full Git functionality without requiring external tools or complex setup, enabling users to safely experiment, track progress, and manage multiple development paths with confidence.

Product Specifications

User Experience Flow

The version control experience in Onlook is seamlessly integrated into the development workflow, automatically tracking all changes while providing intuitive controls for managing project history. Users work naturally with AI and visual tools, while the system maintains a comprehensive record of their project’s evolution through commits, branches, and meaningful history visualization.

Functional Requirements

Feature	End-to-End Business Logic and Rules
Automatic Change Tracking	User Intent: To have all development activities automatically recorded without manual intervention, ensuring no work is ever lost and providing a complete audit trail of project evolution. End-to-End Flow: 1. System - Continuous Monitoring: As users work with AI tools, visual editors, or direct code editing, the system continuously monitors all file operations including creation, modification, deletion, and renaming activities. 2. Backend - Change Detection: The Git service automatically detects when files have been modified, using isomorphic-git’s status checking capabilities to identify differences between the current state and the last committed version. 3. Frontend - Visual Indicators: The interface provides clear visual indicators showing which files have been changed, added, or removed since the last commit, helping users understand the scope of their current work session. 4. System - Staging Preparation: All detected changes are automatically prepared for inclusion in the next commit, with the system organizing changes logically and providing summaries of modifications. Key Rules & Constraints: - Change tracking must be completely automatic and transparent to maintain workflow efficiency. - The system must handle all types of file operations including complex scenarios like file renaming and directory restructuring. - Change detection must be accurate and reliable to ensure no modifications are lost or incorrectly tracked.
Commit Changes	User Intent: To create a safe, recoverable snapshot of the project’s state at a specific point in time, marked with a meaningful description. End-to-End Flow: 1. Frontend - Tracking Changes: As the user or AI makes changes to files, the editor UI automatically detects and displays a list of modified, new, or deleted files. 2. Frontend - User Action: The user types a descriptive message into the “Commit Message” input field and clicks the “Commit” button. 3. Frontend - API Request: The client sends a tRPC API request to the backend, containing the commit message. 4. Backend - Staging and Committing: The backend service calls the Git service (`packages/git/src/git.ts`), which orchestrates a sequence of `isomorphic-git` operations: a. It first runs a `status` check to confirm there are changes to commit. b. It then stages all changes using the equivalent of `git add .`. c. Finally, it executes the `commit` command with the user’s provided message. The author for all commits is hardcoded to “Onlook.” 5. Backend - Response: The Git service returns the SHA hash of the new commit to the backend, which is then sent back to the frontend in a success response. 6. Frontend - UI Update: The editor UI receives the success response. It clears the list of pending changes and adds the new commit to the top of the project’s history log. Key Rules & Constraints: - A commit message is mandatory. - The “Commit” button must be disabled if there are no pending file changes.
User-Friendly History (via Git Notes)	User Intent: To see a commit history with clear, human-readable names instead of cryptic technical hashes. End-to-End Flow: 1. Business Logic - Augmenting Commits: This process is an extension of the “Commit Changes” flow. After a standard Git commit is created and its SHA hash is generated, the system performs an additional step. 2. Backend - Git Note Creation: The Git service (`packages/git/src/git.ts`) uses a special feature of Git called “notes.” It calls the `note` function from `isomorphic-git` to attach a note to the newly created commit SHA. The user’s commit message is used as the content of this note, stored under a specific reference (`refs/notes/onlook-display-name`). 3. Backend - History Retrieval: When the frontend requests the project history, the backend Git service first fetches the standard commit log. It then iterates through each commit and uses the Git `note` functionality to retrieve the associated friendly display name from the notes ref. 4. Frontend - Display: The frontend receives a list of commit objects, each containing both the technical SHA and the user-friendly display name. The UI then displays this user-friendly name in the history log. Key Rules & Constraints: - This mechanism is crucial for user experience. It keeps the underlying Git history technically pure while providing a much more accessible and readable view for non-technical users.
Branch Creation	User Intent: To create a separate line of development to experiment with new ideas without affecting the main version of the project. End-to-End Flow: 1. Frontend - User Action: From the project history or a dedicated branches UI, the user initiates the “Create Branch” action, often from a specific existing commit. 2. Frontend - API Request: The client prompts for a new branch name and sends a tRPC API request to the backend with the new name and the source commit SHA. 3. Backend - Branching Operation: The backend service calls the `branch` function in the Git service. This uses `isomorphic-git` to create a new branch pointer at the specified commit SHA. 4. Backend - Database Update: A new record for the branch is created in the database, linking it to the parent project. 5. Frontend - UI Update: The UI updates to show the new branch in the list of available branches, and the editor may automatically switch to the new branch. Key Rules & Constraints: - Branch names must be unique within a project. - A new branch must be based on a valid, existing commit.
Comprehensive History Management	User Intent: To view the chronological evolution of a project and to revert the workspace to any previous state with complete confidence and clarity. End-to-End Flow: 1. Frontend - History Access: Users access the project history through the branches panel in the left sidebar, where they can view a comprehensive timeline of all project changes and milestones. 2. System - Rich History Display: The system presents commit history with user-friendly display names (stored via Git Notes), timestamps, change summaries, and visual indicators of the scope and impact of each commit. 3. Frontend - Interactive Timeline: Users can browse through the project timeline, compare different versions, and see detailed information about what changed in each commit, including files affected and the nature of modifications. 4. System - Safe Restoration: When users select a previous version to restore, the system safely updates the entire project state to match that historical point, including all files, dependencies, and configurations. 5. Frontend - Seamless Transition: The editor interface and live preview automatically update to reflect the restored state, allowing users to immediately see and interact with their project as it existed at that point in time. Key Rules & Constraints: - History display must be intuitive and accessible to non-technical users through meaningful commit names and descriptions. - Restoration operations must be safe and reversible, allowing users to experiment with confidence. - The system must handle complex history scenarios including branched development and merged changes.
Advanced Branch Management	User Intent: To manage multiple development paths, experiment with different features independently, and organize work across various project aspects without conflicts. End-to-End Flow: 1. Frontend - Branch Creation Interface: Users can create new branches from any commit point through the branches panel, with the system providing clear context about the source point and intended purpose. 2. System - Isolated Development Paths: Each branch maintains its own complete project state, including all files, dependencies, and configurations, ensuring that experimental work doesn’t affect the main development line. 3. Frontend - Branch Switching: Users can seamlessly switch between different branches, with the entire editor environment (including live preview) updating to reflect the selected branch’s current state. 4. System - Branch Coordination: The system manages branch relationships, tracks divergence from the main branch, and provides clear indicators of differences between branches to help users understand their development landscape. 5. Frontend - Branch Integration Options: Users have options for merging successful experiments back to the main branch or keeping branches separate for different feature development or client variations. Key Rules & Constraints: - Branch names must be unique and descriptive to avoid confusion in complex projects. - Branch switching must be instant and preserve the current work state appropriately. - The system must clearly indicate which branch is currently active and provide easy navigation between branches.

Technical Solution

Natural Language Technical Solution

The Version Control system operates as a complete browser-based Git implementation that provides all the functionality of traditional version control systems without requiring any external software or complex setup. This system seamlessly integrates with Onlook’s visual development environment to provide automatic change tracking, intuitive history management, and powerful branching capabilities.

The Automatic Change Detection system continuously monitors all development activities, from AI-generated code changes to visual edits to direct code modifications. This monitoring happens transparently in the background, ensuring that users never lose work and always have a complete record of their project’s evolution.

The User-Friendly History System transforms technical Git operations into an intuitive, visual timeline that non-technical users can easily understand and navigate. Instead of cryptic commit hashes, users see meaningful milestone names and descriptions that clearly communicate what changed and why.

The Branch Management System enables users to create isolated development paths for experimentation, feature development, or client variations. Each branch maintains its own complete project state, allowing users to work on multiple ideas simultaneously without conflicts or interference.

All version control operations are seamlessly integrated with the CodeSandbox environment, ensuring that branch switches, history restoration, and other version control actions are immediately reflected in the live preview and development environment.

End-to-end Execution Sequence Diagram

AI Replication & Reference

Version Control Replication Guide

Prompt

You are an expert full-stack developer. Your task is to create a comprehensive browser-based version control system that integrates seamlessly with a visual development environment.
 
**Core Feature: Browser-Based Git Version Control**
 
**1. Automatic Change Tracking System:**
- Implement continuous monitoring of all file operations (create, modify, delete, rename)
- Build intelligent change detection that works with AI modifications, visual edits, and direct code changes
- Create visual indicators for pending changes with file-level granularity
- Implement automatic staging preparation for streamlined commit workflows
 
**2. User-Friendly Commit System:**
- Build commit interface with mandatory descriptive messages
- Implement Git Notes system for user-friendly display names instead of technical hashes
- Create commit validation that ensures meaningful snapshots
- Build automatic commit author attribution and timestamp management
 
**3. Comprehensive History Management:**
- Implement rich history display with user-friendly names, timestamps, and change summaries
- Build interactive timeline interface for browsing project evolution
- Create safe restoration capabilities that update entire project state
- Implement history comparison tools for understanding changes between versions
 
**4. Advanced Branch Management:**
- Build branch creation interface with clear source point context
- Implement isolated development paths with complete project state separation
- Create seamless branch switching with instant environment updates
- Build branch coordination system with divergence tracking and relationship management
 
**5. Integration with Development Environment:**
- Ensure version control operations integrate seamlessly with CodeSandbox environment
- Build synchronization between version control state and live preview
- Implement branch-aware file synchronization and environment management
- Create coordinated updates across all editor interfaces when version control operations occur
 
**6. Browser-Based Git Engine:**
- Use isomorphic-git library for complete Git functionality in browser environment
- Implement virtual file system integration for browser-based repository management
- Build performance optimization for large projects and extensive history
- Create reliable operation handling with error recovery and user feedback
 
**Technical Requirements:**
- **Git Implementation:** isomorphic-git library for complete browser-based Git functionality
- **File System:** Virtual file system integration with browser storage and CodeSandbox synchronization
- **User Interface:** Integrated panels within the visual editor for history and branch management
- **API Communication:** tRPC for type-safe version control operations
- **Database Integration:** PostgreSQL with Drizzle ORM for branch and project metadata
- **State Management:** MobX for reactive version control state across editor interfaces
 
**Acceptance Criteria:**
1. All file changes are automatically tracked and visually indicated to users
2. Users can create commits with descriptive messages that appear as user-friendly display names
3. History browsing provides clear timeline with meaningful commit descriptions
4. Branch creation and switching work seamlessly with instant environment updates
5. Version control operations integrate smoothly with CodeSandbox and live preview
6. System handles complex scenarios like branch divergence and history restoration safely
7. All operations provide clear feedback and handle errors gracefully

Functional Role	Code File	Description
Git Operations Core	`packages/git/src/git.ts`	Core Git service that wraps isomorphic-git library, providing simplified version control functions for the application.
Branch Management Interface	`apps/web/client/src/app/project/[id]/_components/left-panel/branches-tab/index.tsx`	User interface for branch management, history viewing, and version control operations within the editor.
Version Control Integration	`apps/web/client/src/components/store/editor/branch/index.ts`	Branch management logic that coordinates version control operations with the editor environment and CodeSandbox integration.
History Management	`apps/web/client/src/components/store/editor/history/index.ts`	Manages commit history, change tracking, and restoration operations with user-friendly display and navigation.
Project Data Models	`packages/models/src/project/project.ts`	Defines the TypeScript interfaces for project information, including version control metadata and history tracking.
Branch Data Models	`packages/models/src/project/branch.ts`	Defines the data structure for branches, detailing their relationship to projects and underlying Git references.
Version Control API	`apps/web/client/src/server/api/routers/project/branch.ts`	Backend API endpoints for version control operations including commit creation, branch management, and history retrieval.
Git Library Foundation	`isomorphic-git` (external dependency)	The foundational JavaScript library that enables complete Git functionality within the browser environment.

Real-time Preview Project Lifecycle & Publishing