Introduction

Listing only untracked files in Git is useful for cleanup scripts, onboarding checks, and pre-commit tooling. The command exists, but teams often need extra filtering: include directories, ignore generated artifacts, or expose output for custom shell aliases.

The core command is git ls-files --others --exclude-standard. From there, you can compose custom commands for your workflow.

Core Sections

1. Basic command for untracked files

git ls-files --others --exclude-standard

Meaning:

• --others: show files not tracked by Git
• --exclude-standard: respect .gitignore, .git/info/exclude, global ignore

2. Include ignored files when needed

If you want all untracked files, even ignored ones:

git ls-files --others --exclude-standard --ignored --cached

For ignored-only view, prefer:

git status --ignored -s

3. Machine-safe output for scripts

Use null-delimited output for filenames with spaces/newlines:

git ls-files --others --exclude-standard -z | xargs -0 -n1 echo

This is safer than newline splitting in automation.

4. Define a custom Git alias

git config --global alias.untracked "ls-files --others --exclude-standard"

Then run:

git untracked

You can also make shell functions for richer formatting.

5. Compare with porcelain status

git status --porcelain

Lines starting with ?? are untracked. Useful if you also need staged/modified state in one command.

Common Pitfalls

• Using git status parsing in scripts without stable porcelain format.
• Forgetting --exclude-standard and getting noisy output from ignored files.
• Breaking on filenames with spaces due to non-null-delimited parsing.
• Confusing untracked files with unstaged tracked modifications.
• Creating aliases that depend on shell features unavailable in CI environments.

Summary

To list only untracked files, use git ls-files --others --exclude-standard as the baseline. Add null-delimited output for scripting safety and define aliases for recurring workflows. For broader state inspection, combine with porcelain status output. With these patterns, untracked-file handling becomes reliable in both local and automated Git workflows.

A practical way to make this guidance durable is to convert it into a small runbook that includes prerequisites, expected environment versions, and a short verification sequence. Even strong teams lose time when troubleshooting steps live only in memory or chat history. A runbook should explicitly answer three questions: what to check first, what output confirms healthy behavior, and what output indicates a known failure mode. This level of clarity helps both experienced maintainers and newer contributors, and it reduces repeated investigation during incidents.

It is also valuable to create a tiny reproducible fixture for this topic. The fixture can be a minimal script, test case, sample request, or small dataset that demonstrates the correct behavior in isolation. When regressions appear after dependency upgrades, infrastructure changes, or framework migrations, that fixture becomes the fastest way to isolate whether the issue is environmental or logic-related. Keeping a focused fixture in source control gives you a stable benchmark across branches and release cycles.

For long-term reliability, pair documentation with one automated guardrail in CI. The guardrail should be narrow and fast: an import check, schema validation, endpoint contract test, deterministic unit test, or lightweight performance threshold. Avoid broad flaky checks that hide real signals. The goal is early, actionable feedback before code reaches production. If the same category of issue appears repeatedly, promote the manual troubleshooting step into automation so the system catches it first. Over time, this shifts effort from reactive debugging to preventive quality control and keeps the knowledge article relevant in real engineering workflows.

As a final hardening step, periodically rerun the sample code in a clean environment image and record results in version control. This catches ecosystem drift early and keeps implementation guidance aligned with real runtime behavior.