git-ls-files

Show deleted files

$ git ls-files [[-d|--deleted]]

$ git ls-files [[-m|--modified]]

$ git ls-files [[-o|--others]]

$ git ls-files [[-o|--others]] --exclude-standard

git ls-files [--cached | --deleted | --others | --modified | --unmerged] [--stage] [-z] [--exclude=<pattern>] [--exclude-from=<file>] [--full-name] [--] [<file>...]

--cached
    Shows only files that are currently in the index (staged).

--deleted
    Shows only files that have been deleted from the working tree and are marked for removal in the index.

--others
    Shows only untracked files not in the index. These are files present in the working tree but not yet added to Git.

--ignored
    Shows files that are ignored by Git. Requires --others to be effective.

--modified
    Shows only files that have been modified in the working tree compared to their indexed version.

--unmerged
    Shows only files that have unmerged changes from a Git merge operation. These files are typically in conflict.

--stage
    Shows the mode, object name (SHA-1), and stage number in addition to the path. Useful for understanding merge conflicts.

--debug
    Shows even more detailed information, primarily for debugging Git internals.

-z
    Prints file paths null-terminated (instead of newline-terminated), useful for scripting to handle filenames with spaces or special characters.

--exclude=<pattern>
    Excludes files matching the given pattern. Can be specified multiple times.

--exclude-from=<file>
    Reads exclude patterns from the specified file, similar to .gitignore rules.

--full-name
    When run from a subdirectory, prints paths relative to the top-level directory instead of the current directory.

--error-unmatch
    Exits with a non-zero status if any specified file pattern does not match any file.

<file>...
    Optional file paths or patterns to limit the output to specific files.

The git ls-files command is a low-level 'plumbing' command used to inspect and list files in Git's index (staging area) and the working tree. It provides detailed information about tracked, untracked, ignored, and deleted files, as well as those currently in merge conflicts. Unlike the higher-level git status, git ls-files is designed for scripting and provides raw data like file modes, object SHA-1s, and stage numbers for each entry. It's invaluable for debugging repository states, verifying index contents, and building custom Git tools or scripts that need precise control over file listings and statuses. By default, it only lists files currently tracked by Git, offering specific options to reveal untracked, ignored, or modified files.

git ls-files is a 'plumbing' command; its output is designed for programmatic parsing rather than human readability. By default, it only lists tracked files and explicitly excludes ignored and untracked files unless the --others or --ignored options are used. Be mindful of its default behavior regarding ignored files, as it can lead to confusion if you expect it to behave like git status.

In Git, 'plumbing' commands are low-level commands that are primarily used by other Git commands or by scripts. They are designed to be stable and provide raw data outputs. git ls-files is a classic example, providing the building blocks for higher-level commands like git status.

The Git index, also known as the staging area, is a crucial intermediate layer between your working directory and your repository's history. git ls-files directly queries this index, showing which files are prepared to be committed, their modes, and their object IDs, giving you granular control over what goes into your next commit.

git ls-files has been a core component of Git since its inception, providing a foundational way to interact with the Git index. Its design reflects Git's philosophy of providing low-level, composable commands that can be used to build more complex workflows and tools. It remains essential for advanced scripting and understanding the precise state of tracked and untracked files.

git status(1), git add(1), git rm(1), git check-ignore(1), git diff-index(1)