restore Git Command Guide

The git restore command restores specified paths in the working tree with contents from a restore source. It can restore files from the index, HEAD, or any commit, and can operate on the working tree, index (staging area), or both.

git restore Syntax:

git restore [<options>] [--source=<tree>] [--staged] [--worktree] [--] <pathspec>...
git restore [<options>] [--source=<tree>] [--staged] [--worktree] --pathspec-from-file=<file> [--pathspec-file-nul]
git restore (-p|--patch) [<options>] [--source=<tree>] [--staged] [--worktree] [--] [<pathspec>...]

Target Options:

Option	Description
--staged	Restore from index to HEAD (unstages changes)
--worktree	Restore from index to working tree (default)
--staged --worktree	Restore both index and working tree

Source Options:

Option	Description
--source=<tree>	Restore from specified commit/tree (default: HEAD for —staged, index for —worktree)
-s <tree>	Short form of —source

Selection Options:

Option	Description
--patch, -p	Interactively select hunks to restore
--pathspec-from-file=<file>	Read pathspec from file
--pathspec-file-nul	Use NUL delimiter for pathspec file
-q, --quiet	Suppress output
--progress	Show progress
--no-progress	Hide progress

Parameters:

Parameter	Description
<pathspec>	Files/directories to restore
<tree>	Source commit/tree for restoration

Understanding Restore Operations:

Restore vs Other Commands:

Command Comparison:
├── git restore --worktree: Restore working tree (like git checkout <commit> <file>)
├── git restore --staged: Unstage changes (like git reset HEAD <file>)
├── git restore --staged --worktree: Reset file completely (like git checkout HEAD <file>)
├── git checkout <file>: Older way to restore working tree
├── git reset HEAD <file>: Older way to unstage

Restore Sources:

Available Sources:
├── Index: Default for --worktree operations
├── HEAD: Default for --staged operations
├── Any commit: Specified with --source=<commit>
├── Branch names: --source=main
├── Relative refs: --source=HEAD~1
└── Tree objects: Direct tree SHA-1

Safe File Operations:

Restore Safety:
├── Never affects branch history
├── Only modifies working tree or index
├── Preserves untracked files
├── Can be undone with git checkout
└── No risk of detached HEAD state

Basic Restore Examples:

Working Tree Restoration:

# Restore file to match index (discard working tree changes)
git restore file.txt

# Restore multiple files
git restore file1.txt file2.txt

# Restore directory
git restore src/

# Restore with pattern
git restore "*.tmp"

Index Restoration (Unstaging):

# Unstage file (restore index to HEAD)
git restore --staged file.txt

# Unstage multiple files
git restore --staged file1.txt file2.txt

# Unstage all changes
git restore --staged .

# Unstage specific directory
git restore --staged src/

Complete File Reset:

# Reset file completely (index + working tree to HEAD)
git restore --staged --worktree file.txt

# Reset multiple files
git restore --staged --worktree file1.txt file2.txt

# Reset entire directory
git restore --staged --worktree src/

Advanced Restore Scenarios:

Selective Restoration:

# Restore from specific commit
git restore --source=HEAD~1 file.txt

# Restore from different branch
git restore --source=main file.txt

# Restore from tag
git restore --source=v1.0 file.txt

# Restore from specific commit
git restore --source=abc123 file.txt

Interactive Restoration:

# Interactively restore hunks
git restore --patch file.txt

# Interactively unstage hunks
git restore --patch --staged file.txt

# Choose hunks to restore
# y: restore this hunk
# n: do not restore this hunk
# s: split into smaller hunks
# q: quit

Batch Operations:

# Restore from file list
git restore --pathspec-from-file=files-to-restore.txt

# Restore with NUL delimiters
git restore --pathspec-from-file=files.txt --pathspec-file-nul

# Combine with find
find . -name "*.tmp" -print0 | xargs -0 git restore

Conflict Resolution:

# Restore conflicted file to pre-merge state
git restore --source=HEAD file.txt  # Restore to our side
git restore --source=MERGE_HEAD file.txt  # Restore to their side

# Reset merge conflict markers
git restore --staged --worktree file.txt  # Reset to HEAD

# Clean up after conflict resolution
git restore --staged file.txt  # Unstage resolved file

Configuration and Best Practices:

Git Configuration for Restore:

# Configure restore behavior
git config restore.default untracked  # Handle untracked files
git config restore.default ignored    # Handle ignored files

# Configure progress display
git config restore.progress true
git config restore.quiet false

Safe Restore Practices:

# Check what will be restored
git status
git diff file.txt  # See working tree changes
git diff --staged file.txt  # See staged changes

# Backup before complex restores
cp file.txt file.txt.backup

# Verify restore result
git status
git diff file.txt

Restore Strategy Guidelines:

# Choose restore type based on situation:
# - git restore file.txt: Discard working tree changes
# - git restore --staged file.txt: Unstage changes
# - git restore --staged --worktree file.txt: Complete reset
# - git restore --source=<commit> file.txt: Restore from specific version

# General rule: Use --staged for unstaging, --worktree for discarding changes

Integration with Development Workflows:

File State Management:

#!/bin/bash
# Safe file state management with restore

manage_file_state() {
    local file="$1"
    local action="$2"

    case "$action" in
        "backup")
            # Create backup before changes
            cp "$file" "${file}.backup"
            echo "Backup created: ${file}.backup"
            ;;
        "restore")
            # Restore from backup
            if [ -f "${file}.backup" ]; then
                git restore "$file"
                mv "${file}.backup" "$file"
                echo "File restored from backup"
            else
                echo "No backup found"
            fi
            ;;
        "clean")
            # Clean up backup
            rm -f "${file}.backup"
            echo "Backup cleaned up"
            ;;
    esac
}

manage_file_state "important.txt" "backup"
# Make changes...
manage_file_state "important.txt" "restore"

Development Workflow Integration:

# Integrate restore into development workflow
development_restore() {
    local branch="${1:-main}"

    echo "Restoring development environment..."

    # Stash current work
    git stash push -m "Pre-restore stash"

    # Restore to clean branch state
    git restore --staged --worktree .

    # Switch to target branch
    git checkout "$branch"

    # Restore working directory
    git restore .

    echo "Development environment restored"
}

development_restore "feature-branch"

Automated Cleanup:

# Automated file cleanup with restore
automated_cleanup() {
    echo "Performing automated cleanup..."

    # Restore config files to repository versions
    git restore --staged --worktree "*.config" "*.ini" "*.json"

    # Unstage generated files
    find . -name "*.generated" -exec git restore --staged {} \;

    # Clean up temporary files
    find . -name "*.tmp" -exec git restore {} \;

    echo "Automated cleanup complete"
}

automated_cleanup

Troubleshooting Common Issues:

Unexpected File Changes:

# Check what restore will do
git status
git diff file.txt
git diff --staged file.txt

# Preview restore impact
git restore --dry-run file.txt  # If supported

# Recover from mistaken restore
git checkout HEAD file.txt  # Restore from HEAD
git checkout @ file.txt     # Alternative syntax

Restore Conflicts:

# Handle restore during merge conflicts
resolve_restore_conflicts() {
    echo "Resolving restore conflicts..."

    # Check conflict state
    git status

    # Choose restore source
    git restore --source=HEAD file.txt      # Restore to our version
    git restore --source=MERGE_HEAD file.txt # Restore to their version

    # Mark as resolved
    git add file.txt
}

resolve_restore_conflicts

Permission and Access Issues:

# Handle permission issues during restore
fix_restore_permissions() {
    echo "Fixing restore permission issues..."

    # Check file permissions
    ls -la file.txt

    # Fix ownership
    sudo chown $(whoami) file.txt

    # Fix permissions
    chmod 644 file.txt

    # Retry restore
    git restore file.txt
}

fix_restore_permissions

Large File Handling:

# Handle large files efficiently
restore_large_files() {
    echo "Restoring large files..."

    # Check file sizes
    find . -type f -size +100M -exec ls -lh {} \;

    # Restore large files individually
    find . -type f -size +100M -exec git restore {} \;

    # Monitor progress
    echo "Large file restore complete"
}

restore_large_files

Caution

git restore modifies working tree and index but not branch history. Changes can be lost if not committed. Use git status to verify before restore operations.

Real-World Usage Examples:

Code Review Preparation:

# Prepare files for code review
prepare_for_review() {
    echo "Preparing files for code review..."

    # Unstage all changes
    git restore --staged .

    # Restore working tree to HEAD
    git restore .

    # Clean up untracked files
    git clean -fd

    # Verify clean state
    git status

    echo "Files prepared for review"
}

prepare_for_review

Experimental Changes Management:

# Manage experimental changes safely
experimental_changes() {
    local file="$1"

    echo "Managing experimental changes for $file..."

    # Create backup
    cp "$file" "${file}.experimental"

    # Make experimental changes
    # ... edit file ...

    # Test changes
    if run_tests; then
        echo "✓ Experimental changes successful"
        # Keep changes
    else
        echo "✗ Experimental changes failed"
        # Restore original
        git restore "$file"
        echo "Original file restored"
    fi

    # Clean up backup
    rm -f "${file}.experimental"
}

experimental_changes "config.txt"

Selective Commit Preparation:

# Prepare selective commits with restore
selective_commit_prep() {
    echo "Preparing selective commit..."

    # Stage all changes
    git add .

    # Interactively unstage unwanted changes
    git restore --patch --staged

    # Review staged changes
    git diff --staged

    # Commit selected changes
    git commit -m "Selective commit"

    echo "Selective commit prepared"
}

selective_commit_prep

Repository State Cleanup:

# Clean up repository state
repository_cleanup() {
    echo "Cleaning up repository state..."

    # Restore tracked files to HEAD
    git restore --staged --worktree .

    # Remove untracked files
    git clean -fd

    # Reset submodules if any
    git submodule foreach git restore --staged --worktree .

    # Verify clean state
    if [ -z "$(git status --porcelain)" ]; then
        echo "✓ Repository state cleaned"
    else
        echo "⚠ Some files still modified"
        git status
    fi
}

repository_cleanup

Backup and Recovery:

# Backup and recovery with restore
backup_recovery_workflow() {
    local action="$1"
    local file="$2"

    case "$action" in
        "backup")
            # Create backup before risky operations
            git restore --source=HEAD "$file"
            cp "$file" "${file}.backup"
            echo "Backup created for $file"
            ;;
        "restore")
            # Restore from backup
            if [ -f "${file}.backup" ]; then
                cp "${file}.backup" "$file"
                git add "$file"
                echo "File restored from backup"
            else
                echo "No backup found"
            fi
            ;;
        "cleanup")
            # Clean up backups
            find . -name "*.backup" -delete
            echo "Backups cleaned up"
            ;;
    esac
}

backup_recovery_workflow "backup" "important.txt"
# ... do risky operations ...
backup_recovery_workflow "restore" "important.txt"
backup_recovery_workflow "cleanup"

Tip

Use git restore for safe file operations without affecting branch history. Combine —staged and —worktree for complete file resets. Always check git status before and after restore operations.

What’s the difference between restore and checkout?

git restore is modern command for file operations; git checkout can also restore files but has multiple purposes and can accidentally create detached HEAD.

How do I unstage a file with restore?

git restore —staged unstages the file, equivalent to git reset HEAD .

Can I restore a file from a specific commit?

Yes, git restore —source= restores the file to the state from that commit.

What’s the difference between restore and reset?

restore operates on files without changing branch history; reset changes branch pointers and can affect multiple commits.

How do I discard working tree changes?

git restore discards working tree changes for that file, restoring it to match the index.

Can I restore multiple files at once?

Yes, git restore file1.txt file2.txt or git restore *.txt for pattern matching.

How do I restore a deleted file?

git restore will restore the file from the index if it was tracked.

What’s the safest way to use restore?

Always check git status first, use —staged for unstaging, and create backups for important files.

Can restore work with directories?

Yes, git restore restores all files in that directory recursively.

How do I preview what restore will do?

Check git status and git diff to see current changes before using restore.

Can I restore from a remote branch?

Yes, git restore —source=origin/main restores from remote branch (must be fetched first).

What’s the difference between restore and revert?

restore affects individual files; revert creates new commits that undo changes to multiple files.

How do I restore a file to a previous version?

git restore —source= restores the file to that commit’s version.

Can restore handle binary files?

Yes, restore works with all file types, including binary files.

How do I restore all files in working tree?

git restore . restores all files in current directory recursively.

Can I use restore in scripts?

Yes, restore is script-friendly with predictable behavior and clear exit codes.

Applications of the git restore command

1. File State Management: Safely restore files to previous states without affecting branch history
2. Staging Area Control: Unstage files and changes selectively before committing
3. Working Tree Cleanup: Discard unwanted changes and restore clean file states
4. Commit Preparation: Prepare selective commits by unstaging unwanted changes
5. Conflict Resolution: Restore files during merge conflict resolution
6. Development Workflow: Manage experimental changes and file backups safely