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

Usage:
qmlformat [ options ] arguments

Options¶

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!)

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

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!)
`--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 .:

Option

Default Value

Description

-t, --tabs

Use tabs instead of spaces.

-w, --indent-width <width>

4

How many spaces are used when indenting.

-W, --column-width <width>

-1

Breaks the line into multiple lines if it exceeds the specified width. Use -1 to disable line wrapping. (default).

-n, --normalize

Reorders the attributes of the objects according to the QML Coding Guidelines.

-l, --newline <newline>

Override the new line format to use (native macos unix windows).

-S, --sort-imports

Sort imports alphabetically (Warning: this might change semantics if a given name identifies types in multiple modules!).

--objects-spacing

Ensure spaces between objects (only works with normalize option).

--functions-spacing

Ensure spaces between functions (only works with normalize option).

--semicolon-rule

always

Customize the addition of semicolons at the end of JS statements.

Option	Default Value	Description
`-t`, `--tabs`		Use tabs instead of spaces.
`-w`, `--indent-width <width>`	4	How many spaces are used when indenting.
`-W`, `--column-width <width>`	-1	Breaks the line into multiple lines if it exceeds the specified width. Use -1 to disable line wrapping. (default).
`-n`, `--normalize`		Reorders the attributes of the objects according to the QML Coding Guidelines.
`-l`, `--newline <newline>`		Override the new line format to use (native macos unix windows).
`-S`, `--sort-imports`		Sort imports alphabetically (Warning: this might change semantics if a given name identifies types in multiple modules!).
`--objects-spacing`		Ensure spaces between objects (only works with normalize option).
`--functions-spacing`		Ensure spaces between functions (only works with normalize option).
`--semicolon-rule`	always	Customize the addition of semicolons at the end of JS statements.

Arguments¶

Arguments:

filenames

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!

The following settings are available in the .qmlformat.ini file:

Setting

Default Value

Description

UseTabs

false

Uses tabs instead of spaces.

IndentWidth

4

How many spaces are used when indenting.

NewlineType

native

Overrides the new line format to use (native, macos, unix, windows).

NormalizeOrder

false

Reorders the attributes of the objects according to the QML coding guidelines.

FunctionsSpacing

false

Ensures spaces between functions (only works with normalize option).

ObjectsSpacing

false

Ensures spaces between objects (only works with normalize option).

MaxColumnWidth

-1

Breaks the line into multiple lines if it exceeds the specified width. Use -1 to disable line wrapping (default).

SortImports

false

Sorts imports alphabetically.

Note

This might change semantics if a given name identifies types in multiple modules.

SemicolonRule

always

Customizes the addition of semicolons at the end of JS statements (always, essential).

Note

See Semicolon Rule for more details.

Setting	Default Value	Description
UseTabs	false	Uses tabs instead of spaces.
IndentWidth	4	How many spaces are used when indenting.
NewlineType	native	Overrides the new line format to use (`native`, `macos`, `unix`, `windows`).
NormalizeOrder	false	Reorders the attributes of the objects according to the QML coding guidelines.
FunctionsSpacing	false	Ensures spaces between functions (only works with normalize option).
ObjectsSpacing	false	Ensures spaces between objects (only works with normalize option).
MaxColumnWidth	-1	Breaks the line into multiple lines if it exceeds the specified width. Use -1 to disable line wrapping (default).
SortImports	false	Sorts imports alphabetically. Note This might change semantics if a given name identifies types in multiple modules.
SemicolonRule	always	Customizes the addition of semicolons at the end of JS statements (`always`, `essential`). Note See Semicolon Rule for more details.

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.