{ "componentChunkName": "component---src-pages-blog-index-js", "path": "/blog/", "result": {"data":{"allMarkdownRemark":{"edges":[{"node":{"frontmatter":{"title":"Building Lit: A Journey Through Distributed Systems","description":"How building a Git clone from scratch illuminates the core principles of distributed computing, from content-addressable storage to eventual consistency.","slug":"/blog/lit","date":"2025-01-14T00:00:00.000Z","tags":["Distributed Systems","Python"],"draft":false},"html":"\n \n \n

Lit is my implementation of Git's core features from scratch in Python. Building it taught me more about distributed systems than any textbook could. This post explores how version control systems embody the fundamental principles of distributed computing.

\n
\n

\"The best way to understand distributed systems is to build one.\"

\n
\n
\n

The Distributed Systems Problem

\n

Before diving into Lit, let's frame the problem. Distributed version control must solve several classic challenges:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ChallengeDistributed SystemsVersion Control
Ordering EventsHow do we know what happened first?Which commit came before which?
ReplicationHow do we keep copies in sync?How do clones stay updated?
ConsistencyWhen do all nodes agree?When is a merge \"complete\"?
Partition ToleranceWhat if nodes can't communicate?What if you're offline?
Conflict ResolutionWhat if two nodes disagree?What if two devs edit the same line?
\n

Git, and by extension Lit, provides elegant solutions to all of these.

\n
\n

Part I: The Object Model

\n

Content-Addressable Storage

\n

At Lit's core is a simple but powerful idea: content-addressable storage. Every piece of data is stored and retrieved using its SHA-1 hash.

\n
class LitObject(ABC):\n    \"\"\"Base class for all Lit objects.\"\"\"\n    \n    def compute_hash(self) -> str:\n        \"\"\"\n        Objects are hashed with a header: <type> <size>\\0<content>\n        The same content always produces the same hash.\n        \"\"\"\n        data = self.serialize()\n        header = f\"{self.type} {len(data)}\\0\".encode()\n        self._hash = hashlib.sha1(header + data).hexdigest()\n        return self._hash
\n

This design has profound implications for distributed systems:

\n
    \n
  • Immutability: Objects never change. The same content always produces the same hash.
    • \n
  • Integrity: Any corruption is immediately detectable. If the hash doesn't match, the data is invalid.
    • \n
  • Deduplication: Identical files across the entire history are stored exactly once.
    • \n
  • Trustless Verification: Any node can verify data authenticity without trusting the source.
    • \n
\n

The Three Object Types

\n

Lit implements three fundamental object types:

\n

1. Blobs store raw file content:

\n
class Blob(LitObject):\n    \"\"\"Raw file content, no metadata.\"\"\"\n    \n    def __init__(self, data: bytes = None):\n        self.data = data or b''
\n

2. Trees represent directory structures:

\n
class Tree(LitObject):\n    \"\"\"Directory structure: list of (mode, name, hash) entries.\"\"\"\n    \n    def __init__(self):\n        self.entries: List[TreeEntry] = []
\n

3. Commits capture snapshots with history:

\n
class Commit(LitObject):\n    \"\"\"Snapshot in time with parent links.\"\"\"\n    \n    def __init__(self):\n        self.tree: str = ''           # Root tree hash\n        self.parents: List[str] = []  # Parent commit hashes\n        self.message: str = ''\n        self.author_time: int = 0     # Timestamp
\n

Together, these form an immutable, content-addressed data structure: a foundation that makes the rest of the distributed system possible.

\n
\n

Part II: Ordering Events: The Commit DAG

\n

The Problem of Time in Distributed Systems

\n

In a centralized system, ordering events is trivial: you have one clock. In a distributed system, each node has its own clock, and clocks can drift. How do we establish ordering?

\n

Traditional distributed systems use logical clocks:

\n
    \n
  • Lamport Clocks: A single counter incremented on each event
    • \n
  • Vector Clocks: A vector of counters, one per node, tracking causality
    • \n
\n

Git takes a different approach: the Directed Acyclic Graph (DAG).

\n

The Commit DAG as a Logical Clock

\n

Each commit in Lit contains pointers to its parent commits:

\n
class Commit(LitObject):\n    def __init__(self):\n        self.parents: List[str] = []  # Links to parent commits
\n

This creates a DAG structure:

\n
        A ← B ← C ← D ← G (main, merge commit)\n             \\         ↗\n              E ← F ──┘ (feature)
\n

The DAG provides causal ordering without synchronized clocks:

\n
    \n
  • If commit B points to A as a parent, A happened before B
    • \n
  • If C and E have no ancestor relationship, they are concurrent
    • \n
  • The structure itself encodes the happens-before relationship
    • \n
\n

Comparing to Vector Clocks

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
AspectVector ClocksGit DAG
SizeO(n) per event, n = nodesO(k) per commit, k = parents
HistoryImplicit in clock valuesExplicit graph structure
ConcurrencyCompare vectorsFind merge base
VisualizationAbstractNatural branching diagram
\n

The DAG is essentially a sparse representation of a vector clock optimized for version control's access patterns.

\n

Finding Common Ancestors

\n

To merge two branches, Lit must find their Lowest Common Ancestor (LCA): the most recent commit both branches share:

\n
def find_merge_base(self, commit1: str, commit2: str) -> Optional[str]:\n    \"\"\"\n    Find the best common ancestor using BFS.\n    This is the merge base, essential for three-way merge.\n    \"\"\"\n    if commit1 == commit2:\n        return commit1\n    \n    ancestors1 = self._get_all_ancestors(commit1)\n    ancestors2 = self._get_all_ancestors(commit2)\n    \n    common = ancestors1 & ancestors2\n    \n    if not common:\n        return None  # Unrelated histories\n    \n    # Find the closest common ancestor\n    return self._find_closest(commit1, commit2, common)
\n

This LCA is crucial: it tells us what both branches started from, enabling intelligent merging.

\n
\n

Part III: Replication: Clone, Fetch, Push

\n

Optimistic Replication

\n

Lit uses optimistic replication: a strategy where replicas can diverge and reconcile later:

\n
    \n
  1. Clone: Create a complete copy of all data
    2. \n
  2. Work Offline: Make changes locally without coordination
    3. \n
  3. Push/Pull: Synchronize changes when ready
    4. \n
  4. Merge: Reconcile any divergence
    5. \n
\n

This is fundamentally different from pessimistic replication (like two-phase commit), which requires coordination before any change.

\n
def clone(self, source_url: str, dest_path: str) -> Repository:\n    \"\"\"\n    Clone creates a complete, independent replica.\n    No coordination with source required after clone completes.\n    \"\"\"\n    # Copy ALL objects: complete history\n    for obj_file in source_objects.rglob('*'):\n        copy_object(obj_file, dest_repo)\n    \n    # Copy refs as remote-tracking branches\n    for branch in source_branches:\n        # refs/heads/main → refs/remotes/origin/main\n        create_remote_tracking_ref(branch, dest_repo)\n    \n    # Set up remote for future sync\n    dest_repo.add_remote('origin', source_url)
\n

The Fetch-Merge Protocol

\n

When synchronizing, Lit separates fetching data from integrating it:

\n
def fetch(self, remote: str = 'origin'):\n    \"\"\"\n    Download new objects WITHOUT modifying local branches.\n    Updates refs/remotes/<remote>/* only.\n    \"\"\"\n    url = self.get_remote_url(remote)\n    \n    # Transfer only missing objects\n    for obj_hash in get_remote_objects(url):\n        if not self.repo.object_exists(obj_hash):\n            download_and_store(obj_hash)\n    \n    # Update remote-tracking refs\n    for branch, commit in get_remote_refs(url):\n        self.update_ref(f'refs/remotes/{remote}/{branch}', commit)
\n

This separation provides:

\n
    \n
  • Safety: Local work is never overwritten automatically
    • \n
  • Visibility: You can inspect remote changes before merging
    • \n
  • Control: You decide when and how to integrate
    • \n
\n

In Lit, this looks like: lit fetch origin followed by lit merge origin/main.

\n

Push and Non-Fast-Forward Rejection

\n
def push(self, remote: str, branch: str):\n    \"\"\"\n    Upload commits to remote.\n    Fails if it would lose commits (non-fast-forward).\n    \"\"\"\n    local_hash = self.get_branch_hash(branch)\n    remote_hash = self.get_remote_branch_hash(remote, branch)\n    \n    # Safety check: ensure we're not losing history\n    if remote_hash and not self.is_ancestor(remote_hash, local_hash):\n        raise Exception(\n            \"Non-fast-forward push rejected. \"\n            \"Pull and merge first.\"\n        )\n    \n    # Transfer missing objects\n    missing = self.find_missing_objects(local_hash, remote_hash)\n    for obj_hash in missing:\n        upload_object(obj_hash)\n    \n    # Update remote ref\n    update_remote_ref(remote, branch, local_hash)
\n

This rejection of non-fast-forward pushes prevents lost updates: a critical property in distributed systems.

\n
\n

Part IV: Consistency Models

\n

The CAP Theorem Perspective

\n

The CAP theorem states that a distributed system can provide at most two of:

\n
    \n
  • Consistency: All nodes see the same data
    • \n
  • Availability: Every request gets a response
    • \n
  • Partition Tolerance: System works despite network failures
    • \n
\n

Where does Lit/Git fall?

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropertyLit's Approach
Consistency❌ Eventual, replicas can diverge
Availability✅ All operations work offline
Partition Tolerance✅ Designed for disconnected operation
\n

Lit is an AP system: it prioritizes Availability and Partition Tolerance, accepting eventual consistency.

\n

Eventual Consistency Through Merge

\n

Git achieves eventual consistency through its merge operation:

\n
def merge(self, branch_name: str) -> MergeResult:\n    \"\"\"\n    Merge is the consistency mechanism.\n    After merge, both branches reflect all changes.\n    \"\"\"\n    theirs = self.resolve_ref(branch_name)\n    ours = self.repo.refs.resolve_head()\n    base = self.find_merge_base(ours, theirs)\n    \n    # If we're already up-to-date\n    if base == theirs:\n        return MergeResult(message=\"Already up to date\")\n    \n    # Fast-forward if possible\n    if base == ours:\n        return self.fast_forward(theirs)\n    \n    # Three-way merge required\n    return self.three_way_merge(base, ours, theirs)
\n

This model accepts that:

\n
    \n
  1. Replicas can diverge (during disconnected work)
    2. \n
  2. Divergence is explicitly reconciled (through merge)
    3. \n
  3. After reconciliation, consistency is restored
    4. \n
\n

Strong vs. Eventual: A Trade-off

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
AspectStrong ConsistencyEventual (Git)
LatencyHigh (coordination)Low (local ops)
AvailabilityLimited during partitionsAlways available
ComplexitySimpler mental modelMust handle divergence
Use CaseBanking, inventoryCollaborative dev
\n

For collaborative software development, eventual consistency is the right choice: developers need to work independently, and merge conflicts are a natural part of the workflow.

\n
\n

Part V: Conflict Resolution: The Three-Way Merge

\n

The Core Algorithm

\n

When two developers modify the same file, Lit must decide what to do. The three-way merge algorithm compares three versions:

\n
    \n
  1. Base: The common ancestor
    2. \n
  2. Ours: The current branch
    3. \n
  3. Theirs: The branch being merged
    4. \n
\n
def three_way_merge_file(self, base: bytes, ours: bytes, theirs: bytes) -> Tuple[bytes, bool]:\n    \"\"\"\n    Merge a single file using three-way merge.\n    Returns (merged_content, had_conflicts).\n    \"\"\"\n    # Case 1: Same in both, no conflict\n    if ours == theirs:\n        return ours, False\n    \n    # Case 2: Only we changed it\n    if base == theirs:\n        return ours, False\n    \n    # Case 3: Only they changed it\n    if base == ours:\n        return theirs, False\n    \n    # Case 4: Both changed, need line-by-line merge\n    return self._merge_lines(base, ours, theirs)
\n

Conflict Detection

\n

When both branches modify the same lines differently, Lit detects a conflict:

\n
def _merge_lines(self, base: bytes, ours: bytes, theirs: bytes) -> Tuple[bytes, bool]:\n    \"\"\"Line-by-line merge with conflict detection.\"\"\"\n    \n    base_lines = base.decode().splitlines(keepends=True)\n    ours_lines = ours.decode().splitlines(keepends=True)\n    theirs_lines = theirs.decode().splitlines(keepends=True)\n    \n    result = []\n    has_conflicts = False\n    \n    for base_line, our_line, their_line in align_lines(base_lines, ours_lines, theirs_lines):\n        if our_line == their_line:\n            result.append(our_line)\n        elif base_line == their_line:\n            result.append(our_line)  # We changed it\n        elif base_line == our_line:\n            result.append(their_line)  # They changed it\n        else:\n            # Both changed differently: CONFLICT\n            has_conflicts = True\n            result.extend([\n                \"<<<<<<< HEAD\\n\",\n                our_line,\n                \"=======\\n\",\n                their_line,\n                \">>>>>>> theirs\\n\"\n            ])\n    \n    return ''.join(result).encode(), has_conflicts
\n

Why Three Versions?

\n

Without the base, you can't distinguish between:

\n
    \n
  • \"A changed X to Y, B kept X\" (take Y)
    • \n
  • \"A changed X to Y, B changed X to Z\" (conflict!)
    • \n
\n

The base provides context for intelligent merging: this is why merge bases matter.

\n

Auto-Merge Strategies

\n

When conflicts arise, Lit offers automatic resolution with lit merge feature --auto. By default, the recent strategy is used, where the most recent commits take precedence. But you have options:

\n
    \n
  • lit merge feature --auto uses recent strategy by default
    • \n
  • lit merge feature --auto=ours keeps the current branch's version
    • \n
  • lit merge feature --auto=theirs takes the incoming branch's version
    • \n
  • lit merge feature --auto=union combines both versions
    • \n
\n

This could particularly be useful in CI/CD pipelines or when you have a clear policy about which branch should \"win\" in conflicts.

\n
\n

Part VI: Consensus Without Coordination

\n

The Illusion of Agreement

\n

Traditional distributed systems achieve consensus through protocols like Paxos or Raft, requiring multiple rounds of communication. Lit achieves something remarkable: the appearance of consensus without real-time coordination.

\n

How? Through deterministic merge semantics:

\n
# If DevA and DevB both merge the same branches...\ndevA: merge(feature, main)  # → produces commit X\ndevB: merge(feature, main)  # → produces commit X'\n\n# X and X' will have:\n# Same tree (same file contents)\n# Same parents (same history links)\n# Different hashes (different timestamps/authors)
\n

The resulting content is identical, even without communication. The merge algorithm is deterministic given the same inputs.

\n

CRDT-like Properties

\n

Git's object model shares properties with Conflict-Free Replicated Data Types (CRDTs):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropertyGit Implementation
CommutativityMerge order doesn't affect content
Associativity(A merge B) merge C = A merge (B merge C)
IdempotencyMerging same branch twice is safe
\n
# Commutativity demonstration:\nmerge(A, B)  # Same content as...\nmerge(B, A)  # this (different commit hash, same tree)\n\n# Idempotency demonstration:\nmerge(feature)\nmerge(feature)  # Second merge is a no-op
\n

These properties ensure that regardless of synchronization order, replicas converge to the same state.

\n
\n

Part VII: Advanced Operations

\n

Stash: Local State Management

\n

The stash saves uncommitted work without creating a commit on any branch. Running lit stash saves your changes and cleans the working directory:

\n
class StashManager:\n    def push(self, message: str = None) -> StashEntry:\n        \"\"\"Save working directory and index state.\"\"\"\n        \n        # Capture current state as trees\n        index_tree = self._build_tree_from_index()\n        work_tree = self._build_tree_from_working_dir()\n        \n        entry = StashEntry(\n            message=message or f\"WIP on {branch}\",\n            branch=self.get_current_branch(),\n            commit=self.repo.refs.resolve_head(),\n            index_tree=index_tree,\n            work_tree=work_tree,\n            timestamp=int(time.time())\n        )\n        \n        # Save to stash stack\n        self._push_to_stack(entry)\n        \n        # Reset working directory\n        self._reset_to_head()\n        \n        return entry
\n

Rebase: Rewriting History

\n

Rebase replays commits on top of a new base, creating new commits with the same changes:

\n
def rebase(self, upstream: str):\n    \"\"\"Replay commits on a new base.\"\"\"\n    \n    onto = self.resolve_ref(upstream)\n    head = self.repo.refs.resolve_head()\n    base = self.find_merge_base(onto, head)\n    \n    # Get commits to replay (base..HEAD)\n    commits = self.get_commits_between(base, head)\n    \n    # Move HEAD to the new base\n    self.reset_hard(onto)\n    \n    # Replay each commit\n    for commit_hash in commits:\n        original = self.repo.read_object(commit_hash)\n        \n        # Apply changes from this commit\n        changes = self.get_commit_changes(commit_hash)\n        self.apply_changes(changes)\n        \n        # Create new commit with same message\n        new_hash = self.create_commit(\n            message=original.message,\n            author=original.author\n        )
\n

Before rebase:

\n
        A ← B ← C (main)\n             \\\n              D ← E (feature)
\n

After lit rebase main on feature:

\n
        A ← B ← C (main)\n                 \\\n                  D' ← E' (feature)
\n

D' and E' are new commits: same changes, different hashes, different parents.

\n
\n

Part VIII: The Architecture

\n

Layered Design

\n

Lit follows a clean separation of concerns:

\n
┌─────────────────────────────────────────────────────────────┐\n│                        CLI Layer                             │\n│    init │ add │ commit │ branch │ merge │ fetch │ push      │\n└────────────────────────────┬────────────────────────────────┘\n                             │\n┌────────────────────────────▼────────────────────────────────┐\n│                    Operations Layer                          │\n│        DiffEngine │ MergeEngine │ StashManager               │\n└────────────────────────────┬────────────────────────────────┘\n                             │\n┌────────────────────────────▼────────────────────────────────┐\n│                       Core Layer                             │\n│    Repository │ Objects │ Index │ Refs │ RemoteManager      │\n└────────────────────────────┬────────────────────────────────┘\n                             │\n┌────────────────────────────▼────────────────────────────────┐\n│                     Storage Layer                            │\n│              .lit/ directory (filesystem)                    │\n└─────────────────────────────────────────────────────────────┘
\n

Repository Structure

\n
.lit/\n├── objects/           # Content-addressable object database\n│   ├── ab/           # Sharded by first 2 hex chars\n│   │   └── cdef...   # Compressed object data\n│   └── ...\n├── refs/\n│   ├── heads/        # Local branches\n│   │   └── main      # → commit hash\n│   ├── tags/         # Tags\n│   └── remotes/      # Remote-tracking branches\n│       └── origin/\n│           └── main\n├── HEAD              # Current branch reference\n├── index             # Staging area (binary format)\n└── config            # Repository configuration
\n
\n

Conclusion: What Building Lit Taught Me

\n

The Elegance of Git's Design

\n

Building a version control system from scratch revealed the brilliance of Git's architecture:

\n
    \n
  1. \n

    Content-addressable storage solves integrity, deduplication, and verification in one elegant abstraction

    \n
    2. \n
  2. \n

    The commit DAG provides causal ordering without synchronized clocks: a distributed systems problem solved through data structure design

    \n
    3. \n
  3. \n

    Three-way merge enables automatic conflict resolution by preserving context through the merge base

    \n
    4. \n
  4. \n

    Optimistic replication with explicit merge gives developers freedom while maintaining consistency

    \n
    5. \n
\n

Distributed Systems Principles in Practice

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ConceptHow Git/Lit Implements It
Logical ClocksCommit DAG encodes happens-before
ReplicationClone creates full replicas
ConsistencyEventual consistency via merge
Partition ToleranceFull offline operation support
Conflict ResolutionThree-way merge with user intervention
ConsensusDeterministic merge = same result
\n

Try It Yourself

\n

Lit implements 27 Git commands and is designed for learning. Check out the Quick Example on GitHub for a hands-on walkthrough of merge conflicts and auto-resolution.

\n

Building your own VCS is one of the best ways to understand both Git and distributed systems. The concepts transfer directly to distributed databases, consensus protocols, and any system where multiple nodes must agree on shared state.

\n
\n

Resources

\n\n
\n

Lit is an educational project demonstrating distributed systems principles. For production use, please use Git.

"}}]}},"pageContext":{}}, "staticQueryHashes": ["1994492073","2009693873","2031412112","2318781110","3825832676"]}