Git Basics: Separate Tracked, Untracked, and Ignored Paths

A directory listing mixes files with different Git states. Query the index and the untracked set separately to see what a packaging or inspection script would include.

Prepare a scratch directory

Tested on Linux with Git 2.52.0 and GNU Bash 5.2.37. You need Bash, a text editor, the named runtime, and standard mktemp, rm, and rmdir utilities. The examples use only controlled local data; generated fixture directories are cleaned automatically.

Keep the same terminal open. Stop if setup fails, before saving the source:

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save this as demonstrate-ls-files.sh:

#!/usr/bin/env bash
set -euo pipefail
export LC_ALL=C
fixture_dir="$(mktemp -d)"
trap 'rm -rf -- "$fixture_dir"' EXIT
export GIT_CONFIG_NOSYSTEM=1
export GIT_CONFIG_GLOBAL=/dev/null
export GIT_AUTHOR_NAME='Example Author'
export GIT_AUTHOR_EMAIL='author@example.invalid'
export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
export GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
export GIT_AUTHOR_DATE='2026-10-28T00:00:00+00:00'
export GIT_COMMITTER_DATE="$GIT_AUTHOR_DATE"
git init -q -b main "$fixture_dir/repo"
cd -- "$fixture_dir/repo"
git config commit.gpgsign false
git config core.hooksPath /dev/null
printf '*.tmp\n' > .gitignore
printf 'tracked\n' > tracked.txt
git add .gitignore tracked.txt
git commit -qm 'Track source and ignore rule'
printf 'draft\n' > draft.txt
printf 'cache\n' > cache.tmp
printf 'Tracked:\n'
git ls-files
printf 'Untracked, excluding ignore rules:\n'
git ls-files --others --exclude-standard
printf 'Ignored untracked:\n'
git ls-files --others --ignored --exclude-standard
test "$(git ls-files --others --exclude-standard)" = draft.txt
test "$(git ls-files --others --ignored --exclude-standard)" = cache.tmp

Run it:

bash demonstrate-ls-files.sh

Observed output:

Tracked:
.gitignore
tracked.txt
Untracked, excluding ignore rules:
draft.txt
Ignored untracked:
cache.tmp

Read the result

The default listing reads tracked entries from the index. --others selects untracked paths; --exclude-standard applies normal ignore sources. Combining --ignored with that exclusion source selects the ignored part of the untracked set.

Apply it carefully

An ignored pattern does not untrack files already in the index. For arbitrary filenames, use -z and a NUL-aware consumer instead of parsing lines. The example only lists paths; it does not delete ignored or untracked data. Run this script from an ordinary shell with no repository-selection variables such as GIT_DIR or GIT_WORK_TREE set. All commits and cleanup stay inside the newly created temporary fixture.

The official reference describes the behavior and options. These checks cover the fixture above rather than every input or platform.

Clean up

Remove the saved source, return to the starting directory, then remove the empty practice directory:

rm -- demonstrate-ls-files.sh
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

If the directory is not empty, inspect its remaining contents rather than deleting unknown files.

Acknowledgements

This post was created with assistance from AI.