Prints cross reference information between modules.

This task is automatically reenabled, so you can print information multiple times in the same Mix invocation.

Xref modes

The xref task expects a mode as first argument:

mix xref MODE

All available modes are discussed below.

callers CALLEE

Prints all callers of the given MODULE. Example:

mix xref callers MyMod

graph

Prints a file dependency graph where an edge from A to B indicates that A (source) depends on B (sink).

mix xref graph --format stats

The following options are accepted:

• --exclude - paths to exclude

• --label - only shows relationships with the given label. By default, it keeps all labels that are transitive. The labels are "compile", "export" and "runtime". See "Dependencies types" section below

• --only-nodes - only shows the node names (no edges). Generally useful with the --sink flag

• --only-direct - the --label option will restrict itself to only direct dependencies instead of transitive ones

• --source - displays all files that the given source file references (directly or indirectly)

• --sink - displays all files that reference the given file (directly or indirectly)

• --min-cycle-size - controls the minimum cycle size on formats like stats and cycles

• --format - can be set to one of:

  • pretty - prints the graph to the terminal using Unicode characters. Each prints each file followed by the files it depends on. This is the default except on Windows;

  • plain - the same as pretty except ASCII characters are used instead of Unicode characters. This is the default on Windows;

  • stats - prints general statistics about the graph;

  • cycles - prints all cycles in the graph;

  • dot - produces a DOT graph description in xref_graph.dot in the current directory. Warning: this will override any previously generated file

The --source and --sink options are particularly useful when trying to understand how the modules in a particular file interact with the whole system. You can combine those options with --label and --only-nodes to get all files that exhibit a certain property, for example:

# To get all files and their direct compile time dependencies
mix xref graph --label compile --only-direct

# To get the tree that depend on lib/foo.ex at compile time
mix xref graph --label compile --sink lib/foo.ex

# To get all files that depend on lib/foo.ex at compile time
mix xref graph --label compile --sink lib/foo.ex --only-nodes

# To get all paths between two files
mix xref graph --source lib/foo.ex --sink lib/bar.ex

# To show general statistics about the graph
mix xref graph --format stats

# To limit statistics only to certain labels
mix xref graph --format stats --label compile

Understanding the printed graph

When mix xref graph runs, it will print a tree of the following format:

lib/a.ex
`-- lib/b.ex (compile)
    `-- lib/c.ex

This tree means that lib/a.ex depends on lib/b.ex at compile time which then depends on lib/c.ex at runtime. This is often problematic because if lib/c.ex changes, lib/a.ex also has to recompile due to this indirect compile time dependency.

The flags --source or --sink does not change how you read the graph. For example, if we use the --sink lib/c.ex flag, we would see the same tree:

lib/a.ex
`-- lib/b.ex (compile)
    `-- lib/c.ex

If the --label compile flag is given with --sink, then lib/c.ex won't be shown, because no module has a compile time dependency on lib/c.ex but lib/a.ex still has an indirect compile time dependency on lib/c.ex via lib/b.ex:

lib/a.ex
`-- lib/b.ex (compile)

Therefore, using a combination of --sink with --label is useful to find all files that will change once the sink changes, alongside the transitive dependencies that will cause said recompilations.

Dependencies types

Elixir tracks three types of dependencies between modules: compile, exports, and runtime. If a module has a compile time dependency on another module, the caller module has to be recompiled whenever the callee changes. Compile-time dependencies are typically added when using macros or when invoking functions in the module body (outside of functions).

Exports dependencies are compile time dependencies on the module API, namely structs and its public definitions. For example, if you import a module but only use its functions, it is an export dependency. If you use a struct, it is an export dependency too. Export dependencies are only recompiled if the module API changes. Note, however, that compile time dependencies have higher precedence than exports. Therefore if you import a module and use its macros, it is a compile time dependency.

Runtime dependencies are added whenever you invoke another module inside a function. Modules with runtime dependencies do not have to be compiled when the callee changes, unless there is a transitive compile or export time dependency between them.

Shared options

Those options are shared across all modes:

• --include-siblings - includes dependencies that have :in_umbrella set to true in the current project in the reports. This can be used to find callers or to analyze graphs between projects

• --no-compile - does not compile even if files require compilation

• --no-deps-check - does not check dependencies

• --no-archives-check - does not check archives

• --no-elixir-version-check - does not check the Elixir version from mix.exs