forked from dart-lang/site-www
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Refactor dart format (dart-lang#5845)
Fixes dart-lang#4440 --------- Co-authored-by: Marya <[email protected]>
- Loading branch information
1 parent
aedb1e6
commit 463b252
Showing
1 changed file
with
56 additions
and
30 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,73 +1,99 @@ | ||
--- | ||
title: dart format | ||
description: Command-line tool for formatting Dart source code. | ||
toc: false | ||
--- | ||
|
||
Use the `dart format` command to replace the whitespace in your program | ||
with formatting that follows | ||
[Dart guidelines](/effective-dart/style#formatting). | ||
This is the same formatting that you can get | ||
when using an IDE or editor that has Dart support. | ||
To update your code to follow the | ||
[Dart formatting guidelines][dart-guidelines], | ||
use the `dart format` command. | ||
This formatting follows what you get | ||
when using an IDE or editor with Dart support. | ||
|
||
{% render 'tools/dart-tool-note.md' %} | ||
|
||
Provide a list of files or directories to the `dart format` command. | ||
For example, here's how to format all the Dart files | ||
in or under the current directory: | ||
## Specify files to format | ||
|
||
To reformat one or more Dart files, | ||
provide a list of paths to the desired files or directories. | ||
|
||
### Specify one path | ||
|
||
Provide the path to one file or directory. | ||
If you specify a directory, `dart format` affects only the files in the | ||
immediate directory; it doesn't recurse through subdirectories. | ||
|
||
**Example:** To format all the Dart files in or under the current directory: | ||
|
||
```console | ||
$ dart format . | ||
``` | ||
|
||
To specify multiple files or directories, | ||
use a space-delimited list. | ||
The following command formats all Dart files under the `lib` directory, | ||
### Specify multiple paths | ||
|
||
To specify multiple files or directories, use a space-delimited list. | ||
|
||
**Example:** To format all Dart files under the `lib` directory, | ||
plus one Dart file under the `bin` directory: | ||
|
||
```console | ||
$ dart format lib bin/updater.dart | ||
``` | ||
|
||
:::warning Notice | ||
### Prevent overwriting Dart files | ||
|
||
By default, `dart format` **overwrites** the Dart files. | ||
::: | ||
|
||
If you don't want to overwrite the files, | ||
add the `--output` or `-o` flag. | ||
Use `-o show` or `-o json` to get the contents of the formatted files, | ||
or `-o none` to see only which files would change. | ||
* To not overwrite the files, add the `--output` or `-o` flag. | ||
* To get the contents of the formatted files, add `-o show` or `-o json`. | ||
* To see only which files _would_ change, add `-o none`. | ||
|
||
```console | ||
$ dart format -o show bin/my_app.dart | ||
``` | ||
|
||
To make the command have an exit code of `1` | ||
if any formatting changes occur, | ||
## Notify when changes occur | ||
|
||
To make `dart format` return an exit code when formatting changes occur, | ||
add the `--set-exit-if-changed` flag. | ||
This exit code is often used with continuous integration (CI) | ||
to indicate that a check should fail. | ||
|
||
* If changes occur, the `dart format` command returns an exit code of `1`. | ||
* If changes don't occur, the `dart format` command returns an exit code of `0`. | ||
|
||
Use exit codes with continuous integration (CI) systems | ||
so they can trigger another action in response to the exit code. | ||
|
||
```console | ||
$ dart format -o none --set-exit-if-changed bin/my_app.dart | ||
``` | ||
|
||
For information on additional command-line options, | ||
use the `dart help` command or see the documentation for the | ||
[dart_style package.]({{site.pub-pkg}}/dart_style) | ||
## Use trailing commas | ||
|
||
```console | ||
$ dart help format | ||
``` | ||
Use optional trailing commas for better automatic formatting. | ||
Add a trailing comma at the end of parameter lists in functions, methods, | ||
and constructors. | ||
This helps the formatter insert the appropriate amount of line breaks for | ||
Dart-style code. | ||
|
||
## Affects whitespace only | ||
|
||
:::tip | ||
To avoid making changes that might be unsafe, | ||
`dart format` only affects whitespace. | ||
|
||
There's a lot more to writing readable and | ||
consistent code than just whitespace, though. | ||
To learn more about best practices for writing and styling Dart code, | ||
check out the [Dart style guide][]. | ||
::: | ||
|
||
## Learn more | ||
|
||
To learn about additional command-line options, | ||
use the `dart help` command or see the documentation for the | ||
[dart_style package][dart_style] | ||
|
||
```console | ||
$ dart help format | ||
``` | ||
|
||
[Dart style guide]: /effective-dart/style | ||
[dart_style]: {{site.pub-pkg}}/dart_style | ||
[dart-guidelines]: /effective-dart/style#formatting |