# ecformat
A command line tool to keep files correct in respect of your [EditorConfig](https://editorconfig.org).
## Supported EditorConfig properties
The current ecformat version targets the version 0.17.2 of EditorConfig.
Only if a property is set in your `.editorconfig` for a file,
ecformat will handle this property on that file during the `check`,
the `fix` and the `status` command.
When processing file contents, the `charset` of your EditorConfig is respected.
If there is no `charset` configured for a file,
ecformat uses `utf-8` as the fallback to process the other properties.
For line based processing ecformat respects the `end_of_line` of your EditorConfig.
If this is not set for a file, ecformat uses the default of your platform.
In the section `Disable EditorConfig properties` of the command helps
(see `ecformat help check`, `ecformat help fix` or `ecformat help status`)
you can find options to disable the handling of specific properties.
In the following you can find details about how ecformat handles
the [properties of EditorConfig](https://spec.editorconfig.org/#supported-pairs).
They are listed in the order as ecformat processes them
(e.g., `fix` first trims trailing whitespace before
it may insert a final newline).
### `charset`
ecformat determines the actual encoding of a file from its content.
If that mismatch the configured one, the `check` has an error at that file
and `fix` converts the content into the configured encoding.
### `end_of_line`
ecformat considers all end of lines in a file.
If not only the configured style is used, the `check` has an error at that file
and `fix` changes all end of lines to the configured style.
### `trim_trailing_whitespace`
ecformat only handles this property if it is set to `true`.
If there are any trailing whitespace characters,
the `check` has an error at that file
and `fix` removes all this trailing whitespace characters.
### `insert_final_newline`
ecformat only handles this property if it is set to `true`.
If there is no newline at the end of a file
the `check` has an error at that file
and `fix` adds this missing newline.
### Indentation
ecformat handles the properties `indent_style`, `indent_size` and `tab_width` together.
For these indentation related properties the handling
performance **no** syntactic parsing of source code.
Therefore, the changes of the `fix` command for non-trivial cases
should be used with caution.
If they do not fit your needs,
you should consider using a formatter specialist for your programming language.
At least `indent_style` or `indent_size` needs to be set,
otherwise no validation of the settings is possible.
However, it is recommended to use always both.
If `indent_style` is set and none of the other two properties,
the `fix` command assumes a default of `tab_width = 4`.
This implies, that it case of `indent_style = space`
a tab is replaced by 4 spaces.
Otherwise, if `indent_style` is missing,
the `fix` command adjusts an indentation
using the `tab` style if at least one tab is part of the line indentation
and in `space` style otherwise.
### `spelling_language`
ecformat supports this property only for the `check` command.
There it only checks that the `spelling_langauge` values are valid.
For this it considers all `.editorconfig` files
that may apply to the considered files.
Checking the spelling in your files is out of scope for ecformat.
## Installation
[](https://codeberg.org/BaumiCoder/ecformat/releases)
[](https://deps.rs/crate/ecformat)
You can find the installation options for each version
in the respective [release on Codeberg](https://codeberg.org/BaumiCoder/ecformat/releases).
### Rust Crate
[](https://crates.io/crates/ecformat)
[](https://crates.io/crates/ecformat)
You can install the latest version of the crate from
[crates.io](https://crates.io/crates/ecformat)
```sh
cargo install --locked ecformat
```
Make sure you have the
[cargo bin directory](https://doc.rust-lang.org/cargo/guide/cargo-home.html#directories)
(default is `$HOME/.cargo/bin`) in your `PATH` variable.
If you want to remove ecformat from your machine again, run the following:
```sh
cargo uninstall ecformat
```
It is also possible to use the crate as library in your Rust project
(see [Crate documentation](https://docs.rs/ecformat) for usage details).
If you only use it in your build scripts,
you should add it as a
[build dependency](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies):
```sh
cargo add --build ecformat
```
As alternative to crates.io, you can use the
[ecformat Crate package on Codeberg](https://codeberg.org/BaumiCoder/-/packages/cargo/ecformat)
(see there for details).
### Pre-commit hooks
[](https://pre-commit.com)
There are two [pre-commit](https://pre-commit.com)
hooks available for ecformat.
```yaml
repos:
- repo: https://codeberg.org/BaumiCoder/ecformat
rev: vx.y.z # Set exact ecformat version x.y.z here
hooks:
# Entire repository only if a .edtiorconfig file changes
# (also recommended for stage manual)
- id: ecformat_repo
args: ["check", "-v"] # default arguments (optional)
# Only process the changed files
- id: ecformat
args: ["check", "-v"] # default arguments (optional)
```
### Download binary
The binaries of the versions are available for some common platforms
in the [ecformat_bin package on Codeberg](https://codeberg.org/BaumiCoder/-/packages/generic/ecformat_bin).
### Build from source
Another option is to build from source.
If you have [Rust installed](https://rust-lang.org/tools/install),
clone the repository and checkout the version you want to install.
```sh
git checkout tags/vx.y.z
```
For version `x.y.z` or download a source code archive
from the respective [release](https://codeberg.org/BaumiCoder/ecformat/releases).
Make sure you have the
[cargo bin directory](https://doc.rust-lang.org/cargo/guide/cargo-home.html#directories)
(default is `$HOME/.cargo/bin`) in your `PATH` variable.
Then install the crate with the following command inside the repository / unpacked archive:
```sh
cargo install --locked --path .
```
If you want to remove ecformat from your machine again, run the following:
```sh
cargo uninstall ecformat
```
If you only want to create the binary for your platform,
run the following to get it in the directory `target/release`:
```sh
cargo build --locked --release
```
## License
[](https://api.reuse.software/info/codeberg.org/BaumiCoder/ecformat)
The project is licensed under the [Blue Oak Model License 1.0.0](./LICENSES/BlueOak-1.0.0.txt).
A [modern permissive license](https://writing.kemitchell.com/2019/03/09/Deprecation-Notice.html) which is also easier to understand.
You can find a [brief FAQ on the steward's website](https://blueoakcouncil.org/license-faq).
The project uses REUSE for exact license annotations for every file
as some of them have a different license.