Format command

Formats SysML v2 models according to a consistent style. Useful when working in a team and using version control systems to prevent whitespace-only changes in history. --check reports what would change without writing anything, which is the form a pipeline or a commit hook wants.

Basic usage

  • Format specific files

    syside format /path/to/formatted_model.sysml /path/to/formatted_model_2.sysml

  • Format all files in current directory recursively

    syside format

    Note

    When using syside format without explicitly listing out the files, Syside ignores hidden files and files from hidden directories (starting with ., e.g. .venv or .git). To format files from these directories, list them explicitly.

Output

After running the format command, you should see output similar to:

$ syside format
/path/to/formatted_model.sysml: formatted
1 file reformatted, 0 files left unchanged

The output shows the path of the file(s) that were reformatted, as well as the number of files that did not need reformatting.

Check mode

The syside format --check command can act as a quality gate without editing the files. When a file needs reformatting, the output names it:

/path/to/formatted_model.sysml: would be formatted
1 file would be reformatted, 0 files already formatted

The command exits with the following codes:

Code

Meaning

0

Success, every file is already formatted

1

Failure, at least one file needs reformatting

2

Failure due to syntax errors in the files

Note

For semantic validation, use syside check command. The format command only checks syntax errors.

Available options

Option

Description

-h, --help

Display the help message with all available flags and short descriptions

-c, --check

Check whether files need reformatting without editing them

-q, --quiet

Suppress main output

--line-width <WIDTH>

Maximum line length the formatter will target

--tabs

Indent using tabs instead of spaces

--tab-width <WIDTH>

Number of spaces per indentation level. Only applies if not using --tabs (default: 4)

--config <FILE>

Path to a syside.toml configuration file

-j <THREADS>

Concurrency level, 1 to 8 (default: 4)

-e, --exclude <PATTERN>

Paths or glob patterns to exclude from formatting

--crash-reports <ACTION>

Automatic crash report handling: ignore (default) or upload. More information at What data we collect

Usage examples

Use in Git pre-commit hooks to prevent commits with bad formatting:

#!/bin/bash
# .git/hooks/pre-commit

syside format --check

For more information about Git hooks, see Git documentation.