qmlformat

A tool that automatically formats QML files according to QML coding convention.

qmlformat

qmlformat is a tool that automatically formats QML files in accordance with the QML Coding Conventions.

Usage:
qmlformat [ options ] arguments

Options and settings

qmlformat can be configured via command line options. There are two groups of options: Those which are directly related to formatting, and those which control the behavior of the tool.

The following options only affect the tool behavior:

Command Line Option	Description
-h, --help	Displays help on commandline options.
--help-all	Displays help, including generic Qt options.
-v, --version	Displays version information.
-V, --verbose	Verbose mode. Outputs more detailed information.
--write-defaults	Writes defaults settings to .qmlformat.ini and exits (Warning: This will overwrite any existing settings and comments!)
--output-options
--ignore-settings	Ignores all settings files and only takes command line options into consideration
-i, --inplace	Edit file in-place instead of outputting to stdout.
-f, --force	Continue even if an error has occurred.
-F, --files <file>	Format all files listed in file, in-place

The next group of options controls how files should be formatted, and can additionally also be controlled via a settings file .:

Command Line Option	Setting Name	Default State/Value	Description
-t, --tabs	UseTabs	disabled/false	Use tabs instead of spaces. In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to “true”.
-w, --indent-width <width>	IndentWidth	4	How many spaces are used when indenting.
-W, --column-width <width>	MaxColumnWidth	-1	Breaks the line into multiple lines if it exceeds the specified width. Use -1 to disable line wrapping. (default).
-n, --normalize	NormalizeOrder	disabled/false	Reorders the attributes of the objects according to the QML Coding Guidelines. In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to “true”.
-l, --newline <newline>	NewlineType	native	Overrides the new line format to use (native, macos, unix, windows).
-S, --sort-imports	SortImports	disabled/false	Sort imports alphabetically (Warning: this might change semantics if a given name identifies types in multiple modules!). In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to “true”.
--objects-spacing	ObjectsSpacing	disabled/false	Ensure spaces between objects (only works with normalize). In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to “true”.
--functions-spacing	FunctionsSpacing	disabled/false	Ensure spaces between functions (only works with normalize). In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to “true”.
--group-attributes-together	GroupAttributesTogether	disabled/false	Reorders and groups the attributes of the objects according to the QML Coding Guidelines. Implies --normalize. In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to “true”.
--single-line-empty-objects	SingleLineEmptyObjects	disabled/false	Write empty objects on a single line (only works with normalize). In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to “true”.
--semicolon-rule	SemicolonRule	always	Customizes the addition of semicolons at the end of JS statements (always, essential). Note See Semicolon Rule for more details.

Arguments

Arguments:
filenames

Details

qmlformat is flexible and can be configured according to your needs.

Output

qmlformat writes the formatted version of the file to stdout. If you wish to have your file updated in-place specify the -i flag.

Grouping Properties, Functions, and Signals Together

With -n or --normalize flag, qmlformat groups all properties, functions, and signals together, instead of retaining the order you specified.

Settings File

You can configure qmlformat by including a settings file .qmlformat.ini in your project source or in the parent directories of your project source folder. A default settings file can be obtained by passing the --write-defaults flag. This generates the .qmlformat.ini file in the current working directory.

Warning

--write-defaults will overwrite any existing settings and comments!

Formatting a List of Files

While you can pass a list of files to be formatted as arguments, qmlformat provides -F option to format a set of files stored in a file. In this case, formatting will happen inplace.

// FileList.txt
main.qml
mycomponent.qml

Then, use it like

qmlformat -F FileList.txt

Note

If the file contains an invalid entry, for example, a file path that doesn’t exist or a valid file path but the content is an invalid qml document, then qmlformat will error out for that particular entry. It will still format the valid file entries in place.

Warning

If you provide -F option, qmlformat will ignore the positional arguments.

Semicolon Rule

The --semicolon-rule option allows you to customize the addition of semicolons at the end of JS statements. The following values are accepted:

• always - Always add semicolons (default).

• essential - Remove semicolons unless omitting them would cause issues.

Disabling Formatting with Comments

You can temporarily disable qmlformat using special comments.

• // qmlformat off turns off formatting from that line onward

• // qmlformat on turns on formatting after you turned it off

This lets you preserve hand-tuned code or complex structures without qmlformat changing their layout. Formatting remains off until the next // qmlformat on comment, or until the end of the file if no re-enable is found.

Note

Directives must be on their own line.

Note

Nested directives are not supported. Only the first // qmlformat off and the next // qmlformat on are considered. Any additional directives inside a disabled region are ignored.

Note

The directives are ignored in normalized formatting mode, when sortImports is enabled, or when any option that reorders the original document is used. In these cases, formatting is always applied.