Git Overview

Relevant source files

Purpose and Scope

This document provides a high-level introduction to Git's architecture and the major subsystems that comprise the Git version control system. It explains how commands are dispatched, how data is stored and accessed, and how the various layers interact. This overview is intended to provide context for the more detailed documentation that follows.

For detailed information on specific subsystems, see:

Build system and command execution: Build System and Command Execution
Data storage details: Index and Cache Management, Object Storage and Packfiles, Reference Management
Operations: Revision Walking and History, Diff and Comparison, Rebase and History Editing, Remote Operations

System Architecture Overview

Git is organized into five major architectural layers that build upon each other. Each layer has distinct responsibilities and interfaces with the layers above and below it.

Architecture Layers

Layer	Key Files	Responsibilities
User Interface	git.c1-900	Command parsing, dispatch to built-in commands, alias resolution
Configuration & Build	Makefile1-3000 config.c1-3000	Platform detection, compilation, runtime configuration management
Core Data	read-cache.c1-3000 packfile.c1-2000 refs.c1-2000	Index/staging area, object database, reference storage
Operations	diff.c revision.c sequencer.c	High-level Git operations like diff, log, rebase
Network	transport.c fetch-pack.c send-pack.c	Remote repository communication

Sources: Makefile1-100 git.c1-900 read-cache.c1-200 packfile.c1-100 refs.c1-100

Command Dispatch System

When a user runs a Git command, it flows through a well-defined dispatch mechanism that handles options, aliases, and routing to the appropriate implementation.

Command Dispatch Table

The command dispatch table in git.c529-700 maps command names to implementation functions:

Key dispatch flags defined in git.c21-31:

RUN_SETUP - Requires a Git repository
RUN_SETUP_GENTLY - Try to find a repository but don't fail
USE_PAGER - Automatically paginate output
NEED_WORK_TREE - Requires a working tree (not bare repo)

Sources: git.c1-100 git.c157-366 git.c368-464 git.c466-527 builtin.h1-120

Core Data Layer

Git's data layer consists of three primary storage systems: the index (staging area), the object database (packfiles and loose objects), and the reference system.

Index Structure

The index is managed by read-cache.c and contains:

struct index_state - Main index state at read-cache.c111-200
struct cache_entry - Individual file entries with stat info
Extensions: cache-tree (fast tree writing), untracked-cache (performance), split-index (partial updates)

Object Database

Objects are stored in two formats:

Loose objects: Individual files at .git/objects/??/*, created by object-file.c
Packfiles: Compressed and deltified objects in .pack files, accessed via packfile.c

The packfile system uses:

struct packed_git at packfile.h13-51 - Represents a single packfile
Pack indices (.idx files) for fast object lookup via packfile.c159-187
Multi-pack index (.midx files) to aggregate multiple packs via midx.c96-175
Reverse indices (.rev files) for offset-to-object mapping via pack-revindex.c

Reference System

References (branches, tags, HEAD) are managed through a pluggable backend architecture:

Abstract interface: struct ref_store at refs.c44-50
Files backend: refs/files-backend.c83-94 stores refs as files in .git/refs/
Reftable backend: refs/reftable-backend.c uses reftable format for scalability
Packed-refs: refs/packed-backend.c provides compressed reference storage

Sources: read-cache.c1-200 packfile.c1-300 packfile.h13-51 midx.c1-175 refs.c1-100 refs/files-backend.c83-130 refs/reftable-backend.c1-100

Object Storage Hierarchy

Object Lookup Process

Check multi-pack index if available via midx.c330-400
Search individual pack indices via packfile.c2015-2100
Fall back to loose object lookup in .git/objects/

The packfile system uses:

Fanout table for fast first-byte lookup
Binary search within fanout bucket
CRC32 checksums for corruption detection (v2 indices)
Large offset table for objects >2GB (v2 indices)

Sources: packfile.c159-300 packfile.c2000-2100 midx.c330-500

Reference Backend Architecture

Reference Storage Formats

The reference system at refs.c39-66 defines a pluggable backend with two implementations:

Files Backend refs/files-backend.c83-130
- Stores refs as individual files under .git/refs/
- Maintains a cache via refs/ref-cache.c for performance
- Can pack refs into .git/packed-refs via refs/packed-backend.c
- Supports per-worktree refs (.git/refs/worktree/, .git/refs/bisect/)
Reftable Backend refs/reftable-backend.c38-60
- Stores refs in compact, immutable tables under .git/reftable/
- Provides better performance for repositories with many refs
- Supports atomic multi-ref updates
- Includes reflog as part of the table format

Key Reference Operations

refs_resolve_ref_unsafe() at refs.c390-399 - Resolve symbolic refs recursively
refs_read_ref() at refs.c418-421 - Read a ref value
ref_transaction_commit() - Atomic multi-ref updates

Sources: refs.c39-100 refs.h1-100 refs/files-backend.c83-204 refs/reftable-backend.c38-60 refs/ref-cache.c1-100

Build and Configuration System

Build System

The Makefile1-3000 orchestrates:

Platform detection via config.mak.uname
Compilation of built-in commands into git binary
Generation of command metadata via generate-cmdlist.sh
Version detection via GIT-VERSION-GEN using git describe or version file

Configuration Precedence

Configuration is loaded in order (later overrides earlier) by config.c2000-3000:

Built-in defaults
System config: /etc/gitconfig
Global config: ~/.gitconfig or $XDG_CONFIG_HOME/git/config
Repository config: .git/config
Worktree config: .git/config.worktree
Environment variables: GIT_*
Command-line: -c key=value

Key functions:

git_config() at config.c2000-2100 - Read and parse config files
git_config_get_value() - Query a config key
git_config_set() - Write config values

Sources: Makefile1-1000 config.c1-3000 generate-cmdlist.sh1-100 git.c157-280

Command Execution Flow

Common Operation Pattern

Most Git commands follow this pattern implemented in git.c466-527:

Setup: Call setup_git_directory() if RUN_SETUP flag set
Configuration: Load config via git_config()
Index: Load staging area via read_index() at read-cache.c2300-2500
References: Resolve refs via refs_resolve_ref_unsafe() at refs.c390-399
Objects: Access objects via packfile or loose object APIs
Operation: Execute command-specific logic
Write: Update index/refs/objects as needed

Sources: git.c466-527 read-cache.c2300-2500 refs.c390-421 packfile.c2000-2100

Key Data Structures

Index Entry

Defined in cache.h and managed by read-cache.c95-227

Packed Git

Defined at packfile.h13-51 and accessed via packfile.c300-500

Reference Store

Defined in refs/refs-internal.h200-250 with backends in refs/files-backend.c83-94 and refs/reftable-backend.c38-60

Sources: read-cache.c95-227 packfile.h13-51 refs/refs-internal.h200-250

Summary

Git's architecture is organized into five distinct layers, each with clear responsibilities:

User Interface Layer: Command dispatch and parsing via git.c
Configuration & Build: Platform adaptation and runtime configuration via Makefile and config.c
Core Data Layer: Storage management (index, objects, refs) via read-cache.c packfile.c refs.c
Operations Layer: High-level Git operations via diff.c revision.c sequencer.c
Network Layer: Remote communication via transport.c

The system uses a consistent pattern: commands flow through the dispatch layer, load configuration and repository state, perform operations using the data layer, and write results. The pluggable backend architecture (especially for references) allows Git to scale to different repository sizes and use cases.

Sources: git.c1-900 Makefile1-1000 config.c1-500 read-cache.c1-500 packfile.c1-500 refs.c1-500