ls-files Git Command Guide

The git ls-files command shows information about files in the index (staging area) and the working tree. It provides detailed file state information, including cached, modified, untracked, and ignored files, with filtering options.

git ls-files Syntax:

git ls-files [-z] [-t] [-v] [-f]
               [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored]
               [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified]
               [--resolve-undo]
               [--directory [--no-empty-directory]] [--eol]
               [--deduplicate]
               [-x <pattern>|--exclude=<pattern>]
               [-X <file>|--exclude-from=<file>]
               [--exclude-per-directory=<file>]<environment_details>

File Selection Options:

Option	Description
-c, --cached	Show cached files (tracked files in index)
-d, --deleted	Show deleted files
-o, --others	Show other (untracked) files
-i, --ignored	Show ignored files only
-s, --stage	Show staged contents hash and merge info
-u, --unmerged	Show unmerged files
-k, --killed	Show files killed in work tree
-m, --modified	Show modified files
--resolve-undo	Show resolve-undo information

Output Control Options:

Option	Description
-z	Use NUL line termination
-t	Show file status
-v	Show verbose output
-f	Show FSMonitor valid bit
--directory	Show directories instead of contents
--no-empty-directory	Don’t show empty directories
--eol	Show line ending information
--deduplicate	Suppress duplicate entries

Exclusion Options:

Option	Description
-x <pattern>	Skip files matching pattern
-X <file>	Exclude patterns from file
--exclude-per-directory=<file>	Read exclude file per directory

Parameters:

Parameter	Description
<file>...	Specific files to show information for

Basic Usage Examples:

View Tracked Files:

# Show all tracked files
git ls-files

# Show cached (staged) files only
git ls-files --cached

# Show untracked files
git ls-files --others

File State Analysis:

# Show modified files in working directory
git ls-files --modified

# Show unmerged files after merge conflict
git ls-files --unmerged

# Show deleted files
git ls-files --deleted

Detailed Information:

# Show stage information (mode, object hash, stage number)
git ls-files --stage

# Verbose status information
git ls-files -t

# Show line ending information
git ls-files --eol

Filtering and Exclusion:

# Exclude files matching pattern
git ls-files -x "*.tmp"

# Exclude files in directory
git ls-files -x "build/"

# Use exclusion patterns from file
git ls-files -X .gitignore

Advanced Usage Scenarios:

Repository Analysis:

# Count total tracked files
git ls-files | wc -l

# Find all files of specific type
git ls-files | grep "\.java$" | wc -l

# Check for large files in repository
git ls-files -s | awk '$2 > 1048576 {print $4 ": " $2 " bytes"}' | sort -k2 -rn

Backup and Synchronization:

# Create backup manifest
git ls-files > backup-manifest.txt

# Verify backup contents
git ls-files | xargs -I {} diff {} /backup/{} 2>/dev/null || echo "File {} differs"

CI/CD Integration:

# Ensure no binary files in source
if git ls-files | xargs file | grep -E ":[[:space:]]*[A-Z][a-z]* binary"; then
    echo "Binary files found in repository"
    exit 1
fi

# Check for files larger than threshold
git ls-files -s | awk '$2 > 10485760 {print "Large file: " $4 " (" $2 " bytes)"}'

Merge Conflict Handling:

# Show all conflicted files
git ls-files --unmerged

# Detailed merge information
git ls-files --stage | grep "^100644\|120000\|^100755"

Directory Structure Analysis:

# Show directory structure (without contents)
git ls-files --directory

# Find empty tracked directories
git ls-files --directory | while read dir; do
    if [ -z "$(find "$dir" -maxdepth 1 -type f)" ]; then
        echo "Empty directory: $dir"
    fi
done

Exclusion Pattern Analysis:

# Show all ignored files
git ls-files --ignored --others

# Verify .gitignore effectiveness
git ls-files --ignored --exclude-standard | head -20

# Show files that would be ignored but are tracked
git ls-files | while read file; do
    if git check-ignore -q "$file" 2>/dev/null; then
        echo "Should be ignored but tracked: $file"
    fi
done

Working Tree vs Index Analysis:

File State Comparison:

# Files in index but not in working directory
comm -23 <(git ls-files) <(find . -type f -print | sed 's|^\./||')

# Files in working directory but not in index
comm -13 <(git ls-files) <(find . -type f -print | sed 's|^\./||' | grep -v '^\.git')

Untracked File Discovery:

# New untracked files
git ls-files --others --exclude-standard

# All untracked files including ignored
git ls-files --others

# New directories
git ls-files --others --directory

Modification Tracking:

# Files with changes
git ls-files --modified

# Files staged for commit
git diff --cached --name-only | xargs git ls-files --stage

# Files that must be manually resolved
git ls-files --unmerged | awk '{print $NF}' | sort | uniq

Performance and Efficiency:

Large Repository Handling:

# Limit output for scripting
git ls-files | head -1000

# Use NUL termination for filename safety
git ls-files -z | xargs -0 process-file

# Parallel processing
git ls-files | parallel -j4 'process-single-file {}'

Caching and Optimization:

# Use git status cache where possible
git status --porcelain | awk '$1 !~ /^D/ {print $2}'

# Batch operations instead of per-file queries
git ls-files -z | xargs -0 rm -f  # Careful with this!

Integration with Other Git Commands:

Complete Status Alternative:

#!/bin/bash
echo "=== TRACKED FILES ==="
git ls-files

echo "=== MODIFIED FILES ==="
git ls-files --modified

echo "=== UNTRACKED FILES ==="
git ls-files --others --exclude-standard

echo "=== IGNORED FILES ==="
git ls-files --others --ignored --exclude-standard

Cleanup Script:

# Remove all ignored files
git ls-files --ignored --others --exclude-standard -z | xargs -0 rm -f

# Archive tracked files
git ls-files -z | xargs -0 tar czf archive.tar.gz

Repository Statistics:

# File type distribution
git ls-files | xargs file -b | sort | uniq -c | sort -rn | head -20

# Biggest files by lines
git ls-files | xargs -I {} sh -c 'echo "$(wc -l < "{}") {}"' | sort -rn | head -10

# Oldest modified files
git ls-files --modified -z | xargs -0 ls -lt | tail -10

Troubleshooting Common Issues:

File Not Showing:

# Check if file exists
ls -la problematic-file

# Check if in index
git ls-files | grep problematic-file

# Check if ignored
git check-ignore -v problematic-file

# Check untracked files
git ls-files --others | grep problematic-file

Performance Problems:

# Disable expensive checks
git ls-files --no-empty-directory

# Use caching commands
git status --porcelain # Faster overview

# Limit directory depth
git ls-files --directory | head -100

Encoding Issues:

# Handle filename encoding
git ls-files | iconv -f utf-8 -t utf-8

# List files with special characters
git ls-files -z | xargs -0 -I {} echo "'{}'"

Permission Issues:

# Check readable files only
git ls-files 2>/dev/null

# Find files with permission issues
git ls-files | xargs ls -l 2>&1 | grep -v "^-" | head -10

Caution

git ls-files operates on repository data. Use -z for scripting with files containing spaces or special characters. Don’t parse output expecting specific format changes.

What’s the difference between git ls-files and find?

git ls-files shows repository-tracked files from index; find shows all filesystem files. ls-files respects .gitignore and Git’s view of repository.

How do I see all files including untracked?

Combine options: git ls-files —others (untracked) + git ls-files (tracked). For all files including ignored: git ls-files —others.

What’s the —stage information?

Shows mode (permissions), SHA-1 hash, stage number (for merges), and filename. Stage numbers: 0=normal, 1=ancestor, 2=ours, 3=theirs.

How do I verify repository health?

git ls-files —unmerged shows unresolved conflicts. Missing expected files might indicate corruption. Compare against git status output.

Can ls-files show file sizes?

Indirectly with —stage: git ls-files —stage | while read mode hash stage file; do echo ”$(git cat-file -s $hash) $file”; done

How do exclusions work?

-x excludes patterns, -X excludes from file. Patterns use shell glob syntax: * ? [ ] etc. Directory exclusions end with /.

What’s the resolve-undo information?

Shows files that can be un-merged using git checkout -m (stage 0 objects from merge resolution that have been automatically saved).

Can ls-files detect file moves?

No, shows current index state. Use git log —follow —name-status to detect renames across history, or git status for recent changes.

How do I list files from a different branch?

Check out branch first: git checkout other-branch && git ls-files. Or use git show :path for single file from specific commit.

What’s the difference between —cached and default?

—cached explicitly shows only index contents. Default shows all tracked files (equivalent to —cached unless specifying other options).

Applications of the git ls-files command

1. Repository Auditing: Verify file inclusion/exclusion according to policies
2. Backup Planning: Generate comprehensive file lists for archiving
3. Performance Analysis: Identify large files impacting repository size
4. CI/CD Validation: Ensure repository contains expected file types/locations
5. Workflow Automation: Build scripts working with repository-tracked files
6. Security Scanning: Apply security checks only to tracked source code