---
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`:

```sh
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:

```sh
# 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:

```toml
[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:

```sh
# 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:

```sh
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](/fundamentals/command-line-interface.md). Remember to
specify global options **before** the `list-files` command.
:::

```sh
Usage: mago list-files [OPTIONS]
```

### Options

| Flag, Alias(es)           | Description                                                                                                    |
| :------------------------ | :------------------------------------------------------------------------------------------------------------- |
|       `--command`         | Select for which command the file list should be generated. <br/>**Values:** `linter`, `formatter`, `analyzer`, `guard` |
| `-0`, `--zero-terminate`  | Use NUL bytes instead of newlines to terminate the filenames.                                                  |
| `-h`, `--help`            | Print help information.                                                                                        |