← Back to Mission Control

Refs and Reflog Mastery

10 min read

Git Internals

Deep Space Navigation Protocol

You are entering the core navigation systems of Git. Understanding references and reflog is essential for advanced repository management and emergency recovery operations.

Mission Briefing

Commander, every spacecraft needs a sophisticated navigation system to track its position, trajectory, and maintain logs of all movements for emergency recovery. In Git, this navigation system consists of references (refs) and the reference log (reflog) - the internal mechanisms that track every commit, branch, and state change in your repository.

While cadets use Git through simple commands, commanders understand the underlying reference system. This knowledge enables advanced operations like recovering "lost" commits, understanding Git's internal structure, and performing sophisticated repository maintenance that would be impossible without deep systems knowledge.

Mission Objectives

  • Master Git's reference system: branches, tags, HEAD, and symbolic refs
  • Understand the .git directory structure and object database
  • Utilize reflog for commit recovery and history tracking
  • Perform advanced ref management and repository maintenance
  • Recover from catastrophic repository states using ref knowledge
  • Implement custom reference workflows for enterprise scenarios
Estimated Time: 15 minutes
Complexity: Advanced
Hands-on Labs: 5

Section 1: Git References Foundation

4 minutes

Understanding Git References

In the spacecraft analogy, references are like navigation beacons that point to specific coordinates (commits) in your mission history. Every branch name, tag, and HEAD pointer is a reference stored as a simple file containing a SHA-1 hash.

Reference Types in Git 
# View all references
git show-ref

# Branch references (refs/heads/)
git show-ref --heads

# Tag references (refs/tags/)  
git show-ref --tags

# Remote references (refs/remotes/)
git show-ref | grep remotes

Commander Insight

References are stored in .git/refs/ as plain text files. Each file contains a single SHA-1 hash pointing to a commit object. This simple system enables Git's powerful branching and history management.

Lab 1: Exploring the Reference System

Scenario: Investigate your repository's reference structure

  1. Navigate to your Git repository
  2. Examine reference files directly: 
    # Look at branch reference
cat .git/refs/heads/main

# Check HEAD reference  
cat .git/HEAD

# List all reference directories
ls -la .git/refs/
  3. Compare direct file content with Git commands: 
    # Should match the file content
git rev-parse HEAD
git rev-parse main

# Show what HEAD points to
git symbolic-ref HEAD
Expected Result: You'll see how Git stores references as simple files and understand the relationship between branches, HEAD, and commit objects.

Section 2: HEAD and Symbolic References

3 minutes

The HEAD Reference

HEAD is Git's most important reference - it's your current position in the repository timeline. Think of it as your spacecraft's current coordinates that determine what you see in your working directory.

HEAD State Points To Meaning Working Directory
Normal refs/heads/branch-name On a branch Latest commit of branch
Detached commit SHA-1 Not on any branch Specific commit content
HEAD Manipulation Commands 
# Check current HEAD status
git status
git log --oneline -1

# Create detached HEAD state
git checkout [commit-hash]

# Return to branch
git checkout main

# Move HEAD without changing working directory
git reset --soft HEAD~1

# Move HEAD and update working directory
git reset --hard HEAD~1

Lab 2: HEAD State Management

Scenario: Practice navigating different HEAD states

  1. Check your current HEAD state: 
    git status
cat .git/HEAD
  2. Create a detached HEAD state: 
    git log --oneline -5
git checkout HEAD~2
git status
  3. Examine what changed: 
    cat .git/HEAD  # Should be a SHA-1 now
git branch     # Shows detached state
  4. Return to your branch: 
    git checkout main
cat .git/HEAD  # Should be ref: refs/heads/main
Expected Result: You understand how HEAD changes between symbolic reference (branch) and direct reference (commit hash) states.

Section 3: The Reflog System

4 minutes

Understanding Reflog

The reflog (reference log) is Git's flight recorder - it tracks every movement of references, especially HEAD. Unlike the commit history which can be rewritten, reflog maintains a complete log of where your references have pointed, making it invaluable for recovery operations.

Critical Knowledge

Reflog is local only - it doesn't get pushed or pulled. It's your personal navigation history, typically kept for 90 days by default.

Reflog Commands 
# View HEAD reflog
git reflog

# View reflog for specific branch
git reflog show branch-name

# View reflog with timestamps
git reflog --date=iso

# Find commits from specific time
git reflog --since="2 days ago"

# Show reflog entries as patches
git log -g -p

Example Reflog Output

abc123f HEAD@{0}: commit: Add new feature
def456a HEAD@{1}: checkout: moving from feature-branch to main  
ghi789b HEAD@{2}: commit: Fix bug in authentication
def456a HEAD@{3}: checkout: moving from main to feature-branch
jkl012c HEAD@{4}: reset: moving to HEAD~1

Lab 3: Reflog Recovery Operations

Scenario: Recover a "lost" commit using reflog

  1. Create a commit and then "lose" it: 
    # Make a test commit
echo "test file" > recovery-test.txt
git add recovery-test.txt
git commit -m "Test commit for recovery"

# Note the commit hash
git log --oneline -1

# "Lose" the commit with hard reset
git reset --hard HEAD~1
  2. The commit appears lost from normal history: 
    git log --oneline  # Commit not visible
ls                # File is gone
  3. Use reflog to find and recover: 
    git reflog           # Find the lost commit
git show HEAD@{1}    # Should show your test commit
git reset --hard HEAD@{1}  # Recover it
  4. Verify recovery: 
    ls                # File should be back
git log --oneline # Commit visible again
Expected Result: You've successfully recovered a commit that was "lost" due to a hard reset, demonstrating reflog's power for disaster recovery.

Section 4: Git Internals Deep Dive

3 minutes

The .git Directory Structure

Understanding Git's internal structure is like knowing your spacecraft's engineering systems. The .git directory contains all the repository data, and refs are just one part of this sophisticated system.

.git Directory Layout

.git/
├── HEAD                 # Current branch reference
├── config              # Repository configuration
├── description         # Repository description
├── hooks/              # Git hook scripts
├── info/               # Additional repository info
├── objects/            # Git object database
│   ├── [0-9a-f][0-9a-f]/  # Object storage (by hash)
│   ├── info/           # Object database info
│   └── pack/           # Packed objects
└── refs/               # Reference storage
    ├── heads/          # Branch references
    ├── tags/           # Tag references
    └── remotes/        # Remote references
Exploring Git Objects 
# See all objects
find .git/objects -type f

# Examine object type and content
git cat-file -t [hash]   # Show object type
git cat-file -p [hash]   # Show object content

# Show object size
git cat-file -s [hash]

# List all references with their objects
git for-each-ref

Lab 4: Git Objects and References

Scenario: Explore the relationship between refs and objects

  1. Find the current commit object: 
    git rev-parse HEAD
git cat-file -t HEAD     # Should be "commit"
git cat-file -p HEAD     # Show commit details
  2. Explore the commit's tree object: 
    # Get tree hash from commit
git cat-file -p HEAD | grep tree
git cat-file -p [tree-hash]  # Show directory contents
  3. Create and examine a new reference: 
    # Create a tag pointing to HEAD
git tag test-tag HEAD
cat .git/refs/tags/test-tag

# Create a branch reference manually
echo $(git rev-parse HEAD) > .git/refs/heads/manual-branch
git branch  # Should show manual-branch
Expected Result: You understand how Git stores objects and how references point to these objects, enabling manual reference manipulation.

Section 5: Advanced Reference Operations

1 minute

Enterprise Reference Management

Advanced Git operations often require direct reference manipulation for repository maintenance, migration, and custom workflows.

Advanced Reference Commands 
# Update reference safely
git update-ref refs/heads/branch-name [commit-hash]

# Delete a reference  
git update-ref -d refs/heads/old-branch

# Create symbolic reference
git symbolic-ref HEAD refs/heads/main

# Expire reflog entries
git reflog expire --expire=30.days --all

# Prune unreachable reflog entries
git reflog expire --expire-unreachable=7.days --all

# Force reflog expiration
git gc --prune=now

Enterprise Best Practices

  • Always use git update-ref instead of direct file manipulation
  • Configure reflog retention based on your recovery requirements
  • Regular git gc maintains optimal repository performance
  • Monitor reflog size in large repositories with frequent operations
  • Document custom reference workflows for team consistency

Lab 5: Reference Maintenance

Scenario: Perform repository maintenance using reference tools

  1. Check current reflog size and entries: 
    git reflog | wc -l
git reflog --date=iso | head -5
  2. Clean up old reflog entries (be careful in real repos): 
    git reflog expire --expire=1.day --all
git reflog | wc -l  # Should be fewer entries
  3. Verify repository integrity: 
    git fsck --full
git gc --aggressive
Expected Result: You've performed repository maintenance operations and understand how to manage Git's internal reference system.

Mission Complete: Refs and Reflog Mastery

Reference System Master

Mastered Git's reference system including branches, tags, and HEAD management

Reflog Recovery Expert

Can recover lost commits and navigate repository history using reflog

Git Internals Specialist

Understands .git directory structure and object database relationships

Repository Maintenance Pro

Can perform advanced repository maintenance and reference operations

Next Mission

You've completed the Advanced Git Workflows phase. Next, advance to Phase 2: Automation & CI/CD Integration to learn how to automate Git operations and integrate with continuous integration pipelines.

Previous: History Analysis Next: Git Hooks & Automation