2.3 Implementing Built-in Version Control: Tracking and Managing Code History

When you’re building an application, especially with AI assistance, it’s vital to have a reliable way to save your progress, track changes, and even go back to earlier versions if needed. Onlook integrates a complete version control system directly into its platform, giving you this power without needing any external tools or complex setups. This means you can confidently save your work, experiment with new ideas, and easily review how your project has evolved, all within Onlook.

This chapter explains how Onlook’s built-in version control operates. We will cover how this system works right inside your browser, how it records your project’s development steps through different “saves” and “paths,” and how it makes understanding your project’s history straightforward.

2.3.1 In-Browser Git: How Onlook Manages Your Project’s Versions

Onlook provides you with the full power of version control, traditionally known as Git, without you ever having to leave your web browser. This means you don’t need to install any special software or learn complex command-line tools. You get all the benefits of tracking changes, right where you’re working.

This capability is made possible by a specialized technology called isomorphic-git. Think of it as a complete Git engine that runs entirely within Onlook’s web environment. Onlook’s internal system uses this engine to perform all the necessary version control actions on your project files.

Here’s what this means for managing your project:

• Your Personal Project History: Onlook can initiate a version-controlled space for each of your projects. This sets up the foundation for tracking every change you make.
• Saving Changes: You can easily tell Onlook to record your modifications, new files, or deletions. These are prepared as a set of changes to be included in your next saved version.
• Fundamental Actions: Onlook’s system performs all the core actions you’d expect from version control:
  • Initializing a project: Setting up a new project for version tracking.
  • Adding files: Including specific files or all changes in your next saved version.
  • Saving versions (Committing): Creating a definitive snapshot of your project at a specific moment.
  • Creating parallel paths (Branching): Making separate copies of your project to work on different features independently.
  • Switching versions (Checking out): Easily moving between different saved versions or development paths.
  • Viewing history: Looking at a record of all saved changes over time.

By building on isomorphic-git, Onlook’s system seamlessly integrates powerful version control, working efficiently behind the scenes to let you focus on creating.

2.3.2 Commits and Branches: Recording Your Project’s Development Steps

Two central ideas define how Onlook keeps track of your project’s journey: commits and branches. These concepts allow you to organize your work, save progress, and explore different ideas without worry.

• Commits: Your Project’s Saved Moments:

  • A commit is essentially a saved snapshot of your entire project at a particular point in time. When you decide to “save” your work in Onlook, you are creating a commit. It’s like taking a dated photograph of your application’s complete state.
  • Each commit is uniquely identified by a technical code, and it includes a brief message describing what changes were made since the last save. Onlook automatically records changes from both your manual edits and AI’s contributions with these messages, building a precise timeline of your project’s development.
  • This system ensures that no matter how many changes you make, you always have a saved version to look back on. If you ever need to see how something looked before, or even revert a change, commits provide that safety net.

• Branches: Exploring Different Development Paths:

  • A branch represents a separate, independent line of work within your project. Imagine you have a main project, and you want to try a completely new design or feature without affecting that main version. You would create a new branch. This new branch starts as an exact copy of your project at a chosen commit.
  • Onlook allows you to easily create new branches and switch between them. For example, you might create a branch called “Experimental Design” to test out a radical UI idea. All work on this “Experimental Design” branch remains separate from your “main” project until you explicitly choose to combine them.
  • This capability is incredibly useful for experimenting, developing multiple features at once, or isolating work until it’s fully ready. It gives you the freedom to explore without risking your stable project.

Together, commits and branches empower you to manage your project’s development with clarity and flexibility, ensuring that every step is recorded and every idea can be explored.

2.3.3 User-Friendly History: Making Your Project’s Timeline Easy to Understand

While commits precisely track every technical change in your project, their raw technical identifiers can be difficult for anyone without a coding background to understand. Onlook solves this by making your project’s history clear and intuitive through the use of Git Notes.

• Clear Project Milestones: Git Notes are a standard Git feature that allows you to attach additional, descriptive text to any commit without changing the commit itself. Onlook uses this feature to store easy-to-understand names for your saved versions.
• Beyond Technical Codes: Instead of seeing a series of obscure technical codes in your project’s history, Onlook presents you with a readable timeline. For example, a commit might be displayed with a descriptive title like “Initial Homepage Layout,” “Added Contact Form,” or “Implemented Dark Mode.” These names help you instantly grasp the purpose and impact of each saved version.
• Simple Review and Navigation: This user-friendly history means you can quickly review your project’s development journey, understand the major changes at each step, and easily navigate back to specific functional states. It bridges the gap between the technical details of code changes and the product’s evolving features.

By integrating Git Notes, Onlook ensures that its powerful version control system is not only technically robust but also intuitively understandable, providing a clear narrative of your project’s growth.

Related Technical Files