title: Listing files

Listing scanned files

The mago list-files command is a powerful debugging tool that shows you exactly which files Mago will process based on your configuration. This is essential for:

• Verifying your configuration - Ensure paths, includes, and excludes work as expected
• Debugging file selection - Understand why certain files are or aren't being processed
• Tool integration - Generate file lists for external tools or scripts
• Understanding tool-specific excludes - See how different tools process different file sets

Basic Usage

To get a list of all files in your source paths:

mago list-files

This shows files from your paths configuration (your source code that will be analyzed, linted, and formatted). Files from includes (dependencies) are not shown in the basic output.

Tool-Specific File Lists

Each Mago tool (linter, formatter, analyzer, guard) can have its own excludes configuration that applies in addition to the global source.excludes. This means different tools may process different sets of files.

To see which files a specific tool will process:

# Files the linter will check
mago list-files --command linter

# Files the formatter will format
mago list-files --command formatter

# Files the analyzer will analyze
mago list-files --command analyzer

# Files the guard will check
mago list-files --command guard

Example: Why Files Differ Between Tools

Given this configuration:

[source]
paths = ["src", "tests"]
excludes = ["cache/**"]  # Excluded from ALL tools

[analyzer]
excludes = ["tests/**/*.php"]  # Additionally excluded from analyzer

[formatter]
excludes = ["src/**/AutoGenerated/**"]  # Additionally excluded from formatter

The file lists will differ:

# Shows: src/** + tests/** (minus cache/**)
mago list-files

# Shows: src/** only (tests excluded from analyzer)
mago list-files --command analyzer

# Shows: src/** + tests/** (minus AutoGenerated files)
mago list-files --command formatter

As filenames may contain newlines, the default of printing one name per line is prone to errors when passing the list to other tools like xargs. In that case, you can have the filenames be zero-terminated instead:

mago list-files -0 | xargs -0r ls -l

Command reference

:::tip For global options that can be used with any command, see the Command-Line Interface overview. Remember to specify global options before the list-files command. :::

Usage: mago list-files [OPTIONS]

Options