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 setup and versioning, see:
Git is a distributed version control system built on a layered architecture. The system consists of primary layers: the user interface layer that handles command dispatch, the command layer implementing porcelain operations, the core subsystems providing reusable functionality, and the storage layer managing persistent data.
Overall Git Architecture - Layer View
Architecture Layers
| Layer | Key Components | Responsibilities |
|---|---|---|
| User Interface | git.c | Command parsing, dispatching to built-in commands, alias resolution git.c157-366 |
| Command Layer | builtin.h sequencer.c | High-level porcelain commands defined in commands[] table git.c33-37 |
| Core Subsystems | read-cache-ll.h object-file.h refs.h | Reference management, index/staging area, object storage |
| Storage Layer | packfile.h shallow.h | Packfile compression, object database, shallow clone support |
| Platform Abstraction | git-compat-util.h compat/mingw.c | Cross-platform compatibility, safe system call wrappers |
| Build System | Makefile GIT-VERSION-GEN | Platform detection, compilation orchestration, version generation |
Sources: git.c1-45 Makefile1-100 git-compat-util.h1-100 GIT-VERSION-GEN1-107
When a user runs a Git command, it flows through a dispatch mechanism in git.c that handles options, aliases, and routing to the appropriate implementation.
Command Dispatch Table
The command dispatch mechanism uses struct cmd_struct git.c33-37 to map command strings to implementation functions. Each entry includes flags that determine the environment setup required for the command.
Key dispatch flags defined in git.c21-31:
RUN_SETUP - Requires a Git directory to work on; aborts if not found builtin.h32-38RUN_SETUP_GENTLY - Attempts to find a Git directory but continues if not found builtin.h39-43USE_PAGER - Automatically spawns a pager if output is a TTY builtin.h44-48NEED_WORK_TREE - Ensures a working tree is present (disallows bare repos) builtin.h49-53Sources: git.c21-37 git.c157-250 builtin.h9-113
Git's data layer manages repository state through the object database, the index, and references.
The object database (ODB) manages persistent content storage. The index, often referred to as the "cache", acts as the staging area.
The index management API is primarily defined in read-cache-ll.h It tracks file metadata to detect changes in the working tree without re-reading entire files.
References (branches, tags, HEAD) are managed through a pluggable backend system. The system supports multiple storage formats, including the traditional files backend and the high-performance reftable format.
Sources: git.c11 RelNotes50-52 RelNotes100-101
Git maintains high portability through a compatibility layer that abstracts POSIX and platform-specific differences.
The core of this layer is git-compat-util.h which includes platform-specific headers like compat/mingw.h git-compat-util.h159 and defines portability macros like ARRAY_SIZE git-compat-util.h84 Platform-specific logic, such as Windows error code translation, is handled in compat/mingw.c43-160
Sources: git-compat-util.h1-165 compat/mingw.c43-160 compat/mingw.h1-10
Git uses a Makefile based build system that supports auto-detection of platform capabilities via config.mak.uname config.mak.uname1-15 and optional autoconf support via configure.ac configure.ac1-152
Version strings are dynamically generated by the GIT-VERSION-GEN script. It attempts to use git describe to find the most recent tag and the number of commits since that tag GIT-VERSION-GEN40-58 If not in a repository, it falls back to a default version GIT-VERSION-GEN3
For details on building and versioning, see Getting Started and Build System.
Sources: Makefile1-20 GIT-VERSION-GEN1-61 INSTALL1-30