editorconfig / specification

Specification of EditorConfig file format

EditorConfig Specification

This repository hosts the specification of EditorConfig. A built version is available at https://spec.editorconfig.org/.

Build

To build, first install Sphinx, and then, in the same directory as this file, run

make html

The built HTML files should be in _build.

Making changes

• Alter the content in index.rst
• Update the version and release numbers in conf.py
• Submit a GitHub pull request to the specification repo.

specification's Issues

Use editorconfig.org subdomain

It is possible on readthedocs to use a custom (sub)domain to host the specification. Something like specifications.editorconfig.org or just specs.editorconfig.org would make it clearer that the specifications are officially linked to the project.

Not sure who has access to the DNS of editorconfig.org, but I guess @xuhdev should be able to add the required CNAME record.

Clarify behavior of trim_trailing_whitespace

One of the things that need to be clarified is how trim_trailing_whitespace = true is expected to work.

At the moment almost all implementations I use trim all the trailing whitespaces that exist in a file on save. IMHO that is the expected behavior.

The native Visual Studio implementation only trims whitespaces when enter is pressed at the end of a line. That seems fairly odd and unexpected behavior to me, but "it works as designed" they say: https://developercommunity.visualstudio.com/content/problem/134457/editorconfig-trim-trailing-whitespace-only-applies.html

In their case it even means that when you are at the end of a line, press space or tab followed by any arrow key (or alike) the trailing whitespace remains in the file, despite the setting trim_trailing_whitespace = true.

By clarifying the expected behavior we can strive for more consistent between the various implementations. Right now on our website it says:

trim_trailing_whitespace: set to "true" to remove any whitespace characters preceding newline characters and "false" to ensure it doesn't.

I would suggest to add something like "in the file" after "whitespace characters".

Clarification on insert_final_newline behavior for empty files

POSIX requires non-empty files to feature a final end of line (e.g. \n line feed) terminator, and in general EditorConfig does a good job of helping users to enforce this.

For blank files, however, POSIX does allow for the omission of final end of line terminators. In the event that EditorConfig encounters a file with absolutely no content, it should not warn (and text editor plugins should not auto-insert) about end of line terminators.

In Atom for example, saving a blank file with EditorConfig and insert_final_newline rule enabled, does not present an extra end of line terminator. Neither does Vim. That is acceptable and storage-optimal behavior as far as POSIX is concerned. Not sure about how other EditorConfig toolsets behave.

If we ignore backwards compatibility, then EditorConfig should clarify final eol rule behavior. EditorConfig plugins and linters should go ahead and check for empty files before warning or auto-inserting final eol terminators. This could temporarily break some CI configurations, though the end result is that user data is more POSIX compliant.

However, if backwards compatibility is preeminent, then we may want to create a new option for this rule, something like blank_files_skip_eol, which takes values true, false, or none (not enforced). And encourage the community of EditorConfig tools to update and encourage good form.

Clarify glob matching

Taking the specification literally, the glob *.py would not match foo/bar.py since foo/bar includes the slash character. The C library for editorconfig adds **/ to the start of the glob if it does not have a slash in it (see editorconfig.c:260), but this should really be in the spec.

How is this going to work?

What are the plans with this repository. Obviously it will contain the official specifications for EditorConfig file.

But how will they be served to the audience?

Will it contain markdown file that are served as GitHub Pages in the main website like https://editorconfig.org/specification? This seems to me a very handy and logical addition to the website.

Or are there other plans?

How to have a multiline value

Per the current specification, I don't see how (if possible) to include a key-value pair whose value is a multiline string.

If it's not currently possible, is it possible to update the spec to have a way for that?

Clarify that spelling_language strings must be exactly two or five characters

Per #41,

The format [of a spelling_language value] is ss or ss-TT.

I intended ss to stand for exactly two characters and TT to stand for exactly two characters. However, as @gustaphe commented in editorconfig/editorconfig-vim#210 (comment) , TT could be read as a variable standing for any ISO 3166 code.

Update the specification to clarify that ss represents exactly two characters and TT represents exactly the two characters of an ISO 3166-1 alpha-2 code. Therefore, a spelling_lanugage string as a whole must be exactly two chars (ss) or exactly five chars (ss-TT).

Odd grammatical syntax at supported-properties/root

The text at the aforementioned point reads:

root: special property that should be specified at the top of the file outside of any sections. Set to "true" to stop .editorconfig files search on current file.

As a L1 english speaker, I cannot read the above point, "to stop .editorconfig files search" lacks a definite article, perhaps the author meant ""to stop the .editorconfig files searching the current file"? What is exactly meant by "current file"?

I'm happy to file a pull request, I just lack the context of what it's referring to, hence why I filed an issue first.

Enhancement: Light comment style preference

Users attempting to quickly toggle on and off code commenting, e.g. for YAML, Python and other whitespace sensitive file formats, will find that the resulting uncommented code may not align with the rest of the file, resulting in errors. EditorConfig could minimize this risk, by allowing for a rule on code comments: How many ASCII space characters to insert between # and the beginning of the snippet to comment.

Examples:

my:
  # car:
  #   color: "red"

vs.

my:
  #car:
  #  color: "red"

Either style would be fine, as long as our text editors can pick up the fact that a certain number of spaces are treated as leading comment characters, when toggling comments back off.

Clarify behavior of ; and # within values

The specification contains the following language:

Inserting a # or ; after non-whitespace characters in a line (i.e., inline) shall neither be parsed as a comment nor as part of the section name, pair (defined below) key or value in which it was inserted. This may change in the future; thus, is not recommended.

It also contains the following test inputs:

https://github.com/editorconfig/editorconfig-core-test/blob/70840cfaf6a06766ab61e975b8a1fe3b891ee08e/parser/comments.in#L14-L20

https://github.com/editorconfig/editorconfig-core-test/blob/70840cfaf6a06766ab61e975b8a1fe3b891ee08e/parser/comments.in#L35-L41

With the following tests:

https://github.com/editorconfig/editorconfig-core-test/blob/70840cfaf6a06766ab61e975b8a1fe3b891ee08e/parser/CMakeLists.txt#L83-L85

https://github.com/editorconfig/editorconfig-core-test/blob/70840cfaf6a06766ab61e975b8a1fe3b891ee08e/parser/CMakeLists.txt#L99-L101

This has led me to the following questions:

1. What are the expected results for test6.c and test12.c?
2. The test expectations for test5.c and test11.c appear to be in direct violation of formal specification. Which of these two is expected to be correct?
3. For users wishing to define a .editorconfig value containing a literal ; or # character (dotnet/roslyn#44596), what is the supported mechanism?

Readthedocs link mentioned in README.md not available

The link to the built version as mentioned in the README.md (https://editorconfig-specification.readthedocs.io/en/latest/) just reads "SORRY - This page does not exist yet."

version tags?

According to the specification, this repository is supposed to have tags corresponding to each version of the specification, but the tags do not exist in:

• git commit messages
• git tags
• git branches
• GitHub releases
• Changelog

If the version tags could be published, or otherwise changing the communication structure of versioning, that'd be greatly appreciated.

Clarify 'key containing whitespace' case

According to the spec, whitespaces in keys are not prohibited:

Key: the part before the first = (trimmed of whitespace).

Unfortunately, this behavior is not widely adopted, nor explicitly considered as a legal option. However, JetBrains seems to use this behaviour as an option when exporting .editorconfig:

[{*.http,*.rest}]
ij_http request_call_parameters_wrap = normal

This feature is documented in IDEA documentation, you can actually see implementation cases searching for code samples: https://github.com/search?q=ij_http+request_call_parameters_wrap&type=code

I'm requesting any clarification on legality and acceptability of this use case. This question was originally raised at
ec4j/ec4j#122 (comment) as this behavior may misleadingly be adopted by parser developers. If spacing is considered as allowed, please implement any tests for this in https://github.com/editorconfig/editorconfig-core-test so any other parser developers may have a chance to adapt too

Clarify behavior of formatting (non-"root") properties at top level

Currently there is no mention of what these things should do in neither the simplified nor the formal version of the spec. The example files in official libraries seems to generally avoid doing so, and WebStorm seems to agree that they are in general invalid.

If the current behavior is intended to be kept, I recommend adding this to the spec:

Any property other than root MUST be located under a section to take effect. They are not otherwise recognized.

This, however, can feel counterintuitive to some. It could be more intuitive to do this (at a cost of changing quite a few libraries; we will need a versioning scheme for that):

Formatting (non-root) properties not found under a section are taken to have a section of [*]. The normal precedence rules apply.

The example should probably be changed to illustrate the precedence behavior too. Maybe define a indent under [*] and overwriting it for js will help show the point.

Table of Content

This issue is opened to discuss the table of content for the specification.

Here is a first shot:

Introduction

Introduction of the specification.

File Format

Describes the file format of the .editorconfig files. Also a subsection on parsing the file.

Glob Expressions

Describes the glob syntax used in the section headers in the editorconfig file.

File Processing

Describes the file name, how they are located and the order of processing the content.

Supported Properties

Describes the supported properties.

Recommendations for plugin implementers

How should the plugin behave in certain situations. (e.g ignore unknown
properties, warn on invalid values for known properties).

[Title]

Tell IDE to ignore files

Within projects there is a lot of generated (e.g. test output) or duplicated data (e.g. symlinks or after build process).
This leads to permanent reindex by the IDE for things we won't ever need to lookup.
Therefor IDEs can mark directories or files as "excluded" which should be a property in editorconfig too.

Notes:

• There could be multiple ways to mark a directory like ...
  ** Excluded (no index)
  ** Test Sources (index and special treatment)
  ** Source Root (index and major scope)
• We simply aim for a fully exclusion here
• the index won't be updated
• Searching for files, variables or classes won't show duplicate entries anymore.

Clarify the behavior of leading slash in section title

See the confusion in editorconfig/editorconfig-core-test#37 (comment)

max_line_length is not specified

max_line_length is used in this repo, in various plugins and core. Is there any reason why this specification doesn't describe it?

Introduce AST + validation errors

I propose that we introduce an AST specification that would represent the intermediate state between parsing and applying EditorConfig-specific rules.

1. People can already use the parser in other things not related to EditorConfig, but the AST might be a more manageable data structure for use.
2. EditorConfig can use the same parser, but it remains decoupled and separately-tested.
3. AST opens up doors for validation errors and formatting.
4. The AST data structure must be consistent between cores.

Consider also that EditorConfig, though it only targets supported rules, can technically accept any/all rules you throw at it. This means that the file format and AST are useful outside of the context of EditorConfig.

Versioning with SemVer

IMHO, a specification should always have a revision format where application programmers and users alike can see which version of the specification the corresponding programs support.

I recommend SemVer. As a positive example I'd cite the Matrix.org spec.

Since editorconfig is a pretty small specification, the versioning should be pretty easy. Maybe just slap a v1.0 onto the spec if #2 and #8 are resolved? As there are already implementations of the spec which work somewhat this shouldn't be too risky.