Local docs

lit is local git for one computer.

lit is a lightweight, offline-only version control prototype. It keeps repository data inside a local .lit/ folder and does not depend on accounts, remotes, cloud sync, or network access.

Quick start Commands Limitations

What it is

A simple Git-like local checkpoint tool

lit is designed for local history on a single machine. The goal is a practical command-line workflow that feels familiar if you know Git, but stays much narrower in scope.

  • Local-only repository format
  • Offline-only workflow
  • Deterministic .lit/ storage layout
  • Minimal Python-based CLI prototype

Why use it?

Use lit when you want fast local checkpoints without setting up a remote host, account, token, or sync service.

Design boundary

Local-only and offline-only by design

No remote workflow

No push, pull, fetch, or clone.

No account system

No login, identity, permissions, or hosted collaboration model.

No cloud dependency

Once installed, the tool is meant to work without network access.

One machine focus

The repository lives in one working folder on one computer.

Setup

Install and run lit locally

lit currently targets Python 3.12+.

macOS / Linux

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
lit init my-project

Windows PowerShell

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e .
lit init my-project

You can also run python -m lit init my-project if you prefer the module entry point.

Quick start

What works today

mkdir demo-project
cd demo-project
lit init

That command creates a local .lit/ directory with config, refs, object folders, and merge/rebase state files.

Current verified behavior

lit init works. The rest of the Git-like command set is present as reserved CLI names but is not implemented yet.

Commands

Main commands and prototype status

Command Status Meaning
lit init [path] Working Create a deterministic local repository layout.
lit add Reserved Planned staging command.
lit commit Reserved Planned checkpoint creation command.
lit log Reserved Planned history viewer.
lit status Reserved Planned working tree summary.
lit diff Reserved Planned local comparison command.
lit restore Reserved Planned file restore command.
lit checkout Reserved Planned branch or commit switch.
lit branch Reserved Planned branch management.
lit merge Reserved Planned local merge command.
lit rebase Reserved Planned local rebase command.

Today, reserved commands print a not-implemented message and exit with code 2.

Workflow

Beginner-friendly roadmap example

This is the intended Git-like local workflow once the reserved commands are implemented:

  1. lit init to create the repository.
  2. lit add to stage files.
  3. lit commit to save a checkpoint.
  4. lit branch to create a side branch.
  5. lit checkout to switch branches.
  6. lit merge to combine local work.
  7. lit rebase to replay local work on another branch.
  8. lit restore to discard a local file change.
lit init
lit add journal.txt
lit commit -m "Create first note"
lit branch experiment
lit checkout experiment
lit merge experiment
lit rebase main
lit restore journal.txt

Read that example as a roadmap. In this revision, only lit init is operational.

Comparison

How lit is similar to Git, and how it differs

Similarities

  • CLI-first workflow
  • Repository metadata stored inside the project folder
  • Planned add, commit, branch, merge, rebase, and restore flow
  • Object and ref storage for local history

Differences

  • Strictly local-only and offline-only
  • No hosted remote features
  • No collaboration model
  • Simpler, smaller on-disk format and project scope

Storage

Current repository layout

.lit/
  HEAD
  config.json
  index.json
  objects/
    blobs/
    commits/
    trees/
  refs/
    heads/
    tags/
  state/
    merge.json
    rebase.json

The current bootstrap uses sorted JSON files, a branch ref in HEAD, and SHA-256 object identifiers for stored bytes.

Honest status

Current limitations and non-goals

Limitations

  • Only lit init is implemented today.
  • No verified add, commit, log, status, diff, restore, branch, merge, or rebase behavior yet.
  • Workflow examples beyond init are roadmap examples, not current functionality.

Non-goals

  • Remote repositories
  • Cloud sync
  • Accounts and authentication
  • Multi-user collaboration features
  • Heavy background infrastructure

Run locally

How to open this website

This site is plain static HTML and CSS. Open website/index.html directly in a browser, or run: 

python -m http.server

Then open the local URL shown by Python.