Git Restore: AI-Optimized Technical Reference

Critical Context

Safety Improvement: Git restore eliminates the ambiguous behavior of git checkout that destroyed files when branch names matched filenames. This is the single most important safety improvement Git has made in years.

Stability Timeline: Introduced as experimental in Git 2.23 (August 2019), graduated to stable in Git 2.51 (August 18, 2025) - took 6 years due to extensive edge case testing.

Failure Consequence: git restore . permanently destroys ALL uncommitted changes with no recovery mechanism except IDE local history.

Command Comparison Matrix

Command	Risk Level	Use Case	Critical Limitation
git restore	Medium	File restoration only	Requires Git 2.23+, permanent data loss
git checkout	High	Legacy file operations	Ambiguous behavior destroys files
git reset --hard	Critical	Commit manipulation	Nuclear option, destroys everything
git revert	Low	Shared repository fixes	Creates ugly commit history

Core Operations

Working Directory Restoration

# Single file restoration
git restore README.md

# Multiple files
git restore src/main.js package.json .gitignore

# Nuclear option - destroys ALL changes
git restore .

Critical Warning: git restore . has no confirmation prompt and no undo mechanism.

Staging Area Management

# Unstage files
git restore --staged config/secrets.json

# Unstage everything
git restore --staged .

# Restore and unstage simultaneously
git restore --staged --worktree --source=HEAD~1 package.json

Source-Specific Restoration

# From specific commit
git restore --source=HEAD~3 README.md

# From branch
git restore --source=main config/config.json

# From commit hash
git restore --source=a1b2c3d package.json

# From tag
git restore --source=v2.1.0 src/

Performance Characteristics

Repository Size	Single File	Full Restore	Scaling Factor
Small React app (~800 files)	15-30ms	0.8s	Linear with file count
Medium Node.js (~5,000 files)	45-80ms	3.2s	File size dependent
Enterprise (~25,000 files)	150-300ms	12+s	History depth impact

Critical Failure Modes

Silent Failures (No Error Messages)

• File doesn't exist in commit: Git produces no output, no error, file unchanged
• Typo in filename: Command ignored completely
• Untracked files: Git pretends command never happened
• Wrong working directory: Pathspec errors with cryptic messages

Destructive Operations

• Uncommitted changes: Permanently lost unless IDE has local history
• Wrong commit source: File reverted to months-old version, breaking deployments
• Binary file corruption: Network filesystems cause apparent corruption due to caching

Platform-Specific Issues

Windows:

• Paths >260 characters cause cryptic failures
• Windows Defender locks files during operations
• WSL2 path corruption between filesystems

macOS:

• Case-insensitive filesystem confusion
• M1 path encoding issues with non-ASCII filenames
• Gatekeeper quarantines restored executables

Linux:

• SELinux context violations block operations
• Network filesystem caching corruption
• Docker volume mount permission failures

Debugging Procedures

# Verify Git repository status
git status

# Check file existence at commit
git show HEAD:filename

# Examine file staging status
git ls-files --stage filename

# Debug Git operations
GIT_TRACE=1 git restore filename

Conflict Resolution During Merges

# Keep local version
git restore --ours conflicted-file.txt

# Accept remote version
git restore --theirs conflicted-file.txt

# Recreate conflict markers
git restore --merge conflicted-file.txt

Limitation: These flags only work during active merges, produce errors otherwise.

Interactive Mode

# Selective chunk restoration
git restore --patch src/component.js

Interface Reality: 1990s-era text interface with cryptic controls:

• y = restore chunk
• n = skip chunk
• q = quit
• ? = help

Safety Mechanisms

Prevention Strategies

1. Always commit before major operations - even broken code with "WIP" messages
2. Use git status before restoration - verify what will be destroyed
3. Enable IDE local history - 5-day safety net in most IDEs
4. Create safety alias with confirmation prompts

Recovery Options

• IDE local history: IntelliJ IDEA, VS Code Timeline view
• Git reflog: Find previous HEAD positions for commits
• No recovery for uncommitted changes except IDE history

Resource Requirements

Time Investment

• Learning curve: 2-4 hours to replace muscle memory from git checkout
• Debugging failures: 15-30 minutes per ambiguous error
• Recovery from mistakes: 1-3 hours manual recreation if no backups

Expertise Prerequisites

• Understanding Git's three trees (working directory, staging area, repository)
• Knowledge of pathspec patterns for complex file selection
• Familiarity with commit history navigation (HEAD~, branch names, hashes)

Migration Strategy

From git checkout

1. Replace git checkout <file> with git restore <file>
2. Replace git checkout -- <file> with git restore <file>
3. Use git switch for branch operations
4. Update team documentation and scripts

Risk Mitigation

• Test on non-critical repositories first
• Ensure all team members understand the differences
• Update CI/CD scripts that use legacy commands
• Monitor for silent failures during transition

Production Deployment Considerations

Critical Warnings

• Environment variable mismatches: Restored config files may be missing new variables
• Dependency version conflicts: Restored package files may break builds
• Binary file corruption: Network filesystems require sync operations
• Permission issues: Container deployments may break file permissions

Best Practices

• Always verify file timestamps after restoration
• Run dependency installation after restoring package files
• Test configuration files in staging before production
• Monitor for permission changes in containerized environments