format-index Git Command Guide
The git format-index format is the binary file format that stores Git’s staging area information. It tracks cached file states, file modes, object IDs, and timestamps for all files in the working directory.
Index File Format Specification
Section titled “Index File Format Specification”Header Structure:
Section titled “Header Structure:”| Field | Size | Description |
|---|---|---|
| Signature | 4 bytes | ’D’, ‘I’, ‘R’, ‘C’ |
| Version | 4 bytes | Version number (2, 3, or 4) |
| Entry Count | 4 bytes | Number of index entries |
Index Entry Format:
Section titled “Index Entry Format:”| Field | Size | Description |
|---|---|---|
| ctime | 8 bytes | Last change time (creation time for index) |
| mtime | 8 bytes | Last modification time |
| dev | 4 bytes | Device ID |
| ino | 4 bytes | Inode number |
| mode/perm | 4 bytes | File permissions and type |
| uid | 4 bytes | User ID |
| gid | 4 bytes | Group ID |
| file size | 4 bytes | File size on disk |
| object ID | 20-32 bytes | SHA-1 or SHA-256 hash |
| flags | 2 bytes | Name length and flags |
| file name | variable | NUL-terminated file path |
Version Differences:
Section titled “Version Differences:”Version 2 (Basic):
Section titled “Version 2 (Basic):”- Core functionality with stat information
- Basic conflict detection for merging
Version 3 (Extensions Support):
Section titled “Version 3 (Extensions Support):”- Support for file system capabilities (e.g., symlinks)
- Optional extension data
- Enhanced merge conflict tracking
Version 4 (Enhanced):
Section titled “Version 4 (Enhanced):”- Optimized for broken filesystems
- Skip-worktree and assume-unchanged bits
- Improved performance for large index files
Extension Types:
Section titled “Extension Types:”| Extension | Signature | Purpose |
|---|---|---|
| TREE | ’T’, ‘R’, ‘E’, ‘E’ | Cached tree object information |
| REUC | ’R’, ‘E’, ‘U’, ‘C’ | Rename conflict information |
| LINK | ’l’, ‘i’, ‘n’, ‘k’ | Split index information |
| UNTR | ’U’, ‘N’, ‘T’, ‘R’ | Untracked cache information |
Examples of git index operations:
Section titled “Examples of git index operations:”Check index status
Section titled “Check index status”git statusShows current index state vs working directory.
Add file to index
Section titled “Add file to index”git add <file>Stages file changes in the index.
Remove from index but keep file
Section titled “Remove from index but keep file”git rm --cached <file>Unstages file but keeps it in working directory.
Update index stat information
Section titled “Update index stat information”git update-index --refreshRefreshes stat information for tracked files.
Clear index and checked-out tree
Section titled “Clear index and checked-out tree”git reset --hard HEADResets index and working tree to HEAD.
Show index content
Section titled “Show index content”git ls-files --stageDisplays all files in index with metadata.
Skip-worktree setting
Section titled “Skip-worktree setting”git update-index --skip-worktree <path>Marks path to not watch for changes.
Resolve merge conflicts
Section titled “Resolve merge conflicts”git add <file>Resolves conflicts by staging resolved content.
How does the index differ from staging area?
Section titled “How does the index differ from staging area?”The index (staging area) is where files are prepared for commit. It’s a binary file containing file states, object hashes, and metadata.
What happens during git add?
Section titled “What happens during git add?”git add hashes files, creates objects if needed, and updates index entries with new object IDs and stat information.
How do merge conflicts appear in the index?
Section titled “How do merge conflicts appear in the index?”Merge conflicts store multiple versions (stage 1 = common ancestor, 2 = ours, 3 = theirs) in index. Files aren’t readable until resolved.
What are skip-worktree and assume-unchanged?
Section titled “What are skip-worktree and assume-unchanged?”skip-worktree ignores files in git status/update checks; assume-unchanged tells Git files haven’t changed (potentially unsafe).
How do I recover from corrupted index?
Section titled “How do I recover from corrupted index?”For corrupted index, try git status --porcelain to recreate or use rm .git/index && git reset to rebuild from HEAD.
Why doesn’t Git track empty directories?
Section titled “Why doesn’t Git track empty directories?”Index only stores file entries; empty directories don’t get entries. Use .gitkeep files to track empty directory placeholders.
How does the index enable staging?
Section titled “How does the index enable staging?”Index lets you interactively build commits: stage some changes now, others later, by comparing HEAD vs index vs working tree.
What’s the filesystem monitor extension?
Section titled “What’s the filesystem monitor extension?”Recent Git versions (experimental) use FSMonitor to watch for file changes, avoiding full directory scans and speeding up large repos.
Applications of the index format
Section titled “Applications of the index format”- Staging Control: Enables selective staging of changes before commit
- Merge Conflict Resolution: Stores multiple file versions during conflicts
- Performance Optimization: Caches file metadata to avoid repeated stats
- Sparse Repository Support: Skip-worktree bits for large working directories
- Advanced Workflows: Interactive amending and selective reverting
- Build System Integration: Provides stable snapshot for automated testing