stylua

Auto-format a file or an entire directory

$ stylua [path/to/file_or_directory]

$ stylua --check [path/to/file]

$ stylua --config-path [path/to/config_file] [path/to/file]

$ stylua - < [path/to/file.lua]

$ stylua --indent-type [Spaces] --quote-style [AutoPreferSingle] [path/to/file_or_directory]

stylua [OPTIONS] [FILES...]
stylua --check [OPTIONS] [FILES...]
stylua --stdin [OPTIONS] < FILE

-c, --check
    Checks if the files are formatted correctly without modifying them. Exits with a non-zero code if unformatted files are found.

-f, --force
    Forces formatting even if files contain parsing errors. Use with caution.

-i, --ignore GLOBS...
    Ignores files matching the given glob patterns. Can be specified multiple times.

-o, --output PATH
    Writes the formatted output to a specific file instead of modifying the input file(s) in place. Only valid for a single input file.

-s, --stdin
    Reads Lua code from standard input instead of a file.

--column-width WIDTH
    Sets the maximum column width for formatting (default: 100).

--indent-type TYPE
    Sets the indentation type to Spaces or Tabs (default: Spaces).

--indent-width WIDTH
    Sets the number of spaces or tabs for indentation (default: 2).

--quote-style STYLE
    Sets the quote style to Auto, ForceSingle, or ForceDouble (default: Auto).

--call-parentheses STYLE
    Sets the style for parentheses in function calls to Auto, Always, NoSingleArg, or NoTableOrString.

--table-trailing-comma BOOL
    Enforces or removes trailing commas in tables (true or false).

--collapse-simple-statement BOOL
    Collapses simple statements like local foo = bar onto a single line when possible (true or false).

--config PATH
    Specifies a custom configuration file to use.

--color WHEN
    Controls when to use colored output: Auto, Always, or Never (default: Auto).

--log-level LEVEL
    Sets the logging level: Trace, Debug, Info, Warn, Error, Off (default: Info).

--diff
    Displays a diff of the changes that would be made without applying them.

--error-on-unformatted
    Exits with a non-zero code if files are unformatted (alias for --check).

--stdin-filepath PATH
    Provides a dummy filepath for stdin, used for applying ignore patterns correctly.

-h, --help
    Prints help information and exits.

-v, --version
    Prints version information and exits.

stylua is an opinionated code formatter for the Lua programming language. Written in Rust for performance, it aims to provide a consistent and predictable formatting style for Lua codebases. It automatically re-formats Lua source files according to a predefined set of rules, reducing bikeshedding over style and making code easier to read and maintain across projects and teams. It supports various configuration options to tailor the formatting slightly, such as indentation type, column width, and quote style, allowing users to align it with their preferences or project standards. stylua can format individual files, directories, or read from standard input, making it flexible for integration into development workflows, CI/CD pipelines, and pre-commit hooks. Its "opinionated" nature means it enforces a specific style, which might differ from an existing codebase's style, but it provides a reliable way to ensure future consistency and readability.

stylua is opinionated; its default formatting might not align perfectly with pre-existing codebases without custom configuration. While written in Rust for speed, processing very large files or an extremely high number of files might still take time. It expects valid Lua syntax, though the --force option can attempt formatting even with parsing errors, the output might be unexpected.

stylua automatically looks for a stylua.toml or .stylua.toml file in the current directory or parent directories. This file can be used to set default formatting options like column_width, indent_type, indent_width, and quote_style, among others. This allows project-specific formatting rules to be easily shared and enforced without needing to specify command-line arguments every time.

When run with --check, stylua exits with a status code of 0 if all files are formatted correctly, and a non-zero status code (typically 1) if any files are found to be unformatted. This behavior is crucial for use in CI/CD pipelines or pre-commit hooks to ensure code style compliance.

stylua supports glob patterns for specifying files and directories to format, as well as for ignoring files. It uses a .gitignore-like syntax for ignore patterns, making it flexible for selective formatting of codebases.

stylua was created by Johnny Morgan (JohnnyJayJay) in 2020 as a fast, opinionated code formatter for Lua, inspired by tools like prettier and rustfmt. Its development in Rust aimed to provide high performance and reliability, addressing the lack of a robust, modern, and widely adopted formatter in the Lua ecosystem at the time. It quickly gained traction among Lua developers, especially those using Neovim, due to its speed and ease of integration. The project continues to be actively maintained, with ongoing improvements and new features.

lua(1), luac(1), prettier(1)