-
Notifications
You must be signed in to change notification settings - Fork 42
/
index.html
259 lines (204 loc) · 21.4 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
---
layout: default
description: EditorConfig is a file format and collection of text editor plugins for maintaining consistent coding styles between different editors and IDEs.
---
<section id="overview">
<h2>What is EditorConfig?</h2>
<p>EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. The EditorConfig project consists of <strong>a file format</strong> for defining coding styles and a collection of <strong>text editor plugins</strong> that enable editors to read the file format and adhere to defined styles. EditorConfig files are easily readable and they work nicely with version control systems.</p>
</section>
<section id="file-format">
<h2>What's an EditorConfig file look like?</h2>
<p><em>(A <a href="https://spec.editorconfig.org/">formal specification of EditorConfig</a> is also available.)</em></p>
<section id="example-file">
<h3>Example file</h3>
<p>Below is an example <code>.editorconfig</code> file setting end-of-line and indentation styles for Python and JavaScript files.</p>
<div class="code-container">
{% highlight ini %}
# EditorConfig is awesome: https://editorconfig.org
# top-most EditorConfig file
root = true
# Unix-style newlines with a newline ending every file
[*]
end_of_line = lf
insert_final_newline = true
# Matches multiple files with brace expansion notation
# Set default charset
[*.{js,py}]
charset = utf-8
# 4 space indentation
[*.py]
indent_style = space
indent_size = 4
# Tab indentation (no size specified)
[Makefile]
indent_style = tab
# Indentation override for all JS under lib directory
[lib/**.js]
indent_style = space
indent_size = 2
# Matches the exact files either package.json or .travis.yml
[{package.json,.travis.yml}]
indent_style = space
indent_size = 2
{% endhighlight %}
</div>
<p>Check the Wiki for some real-world examples of <a href="https://github.com/editorconfig/editorconfig/wiki/Projects-Using-EditorConfig">projects using EditorConfig files</a>.</p>
</section>
<section id="file-location">
<h3>Where are these files stored?</h3>
<p>When opening a file, EditorConfig plugins look for a file named <code>.editorconfig</code> in the directory of the opened file and in every parent directory. A search for <code>.editorconfig</code> files will stop if the root filepath is reached or an EditorConfig file with <code>root=true</code> is found.</p>
<p>EditorConfig files are read top to bottom and the most recent rules found take precedence. Properties from matching EditorConfig sections are applied in the order they were read, so properties in closer files take precedence.</p>
<p><strong>For Windows Users:</strong> To create an <code>.editorconfig</code> file within Windows Explorer, you need to create a file named <code>.editorconfig.</code> (note the trailing dot), which Windows Explorer will automatically rename to <code>.editorconfig</code> for you.</p>
</section>
<section id="file-format-details">
<h3>File Format Details</h3>
<p>EditorConfig files use an INI format that is compatible with the format used by <a href="https://docs.python.org/2/library/configparser.html">Python ConfigParser Library</a>, but <code>[</code> and <code>]</code> are allowed in the section names. The section names are filepath <a href="https://en.wikipedia.org/wiki/Glob_(programming)">globs</a> (case sensitive), similar to the format accepted by <a href="https://git-scm.com/docs/gitignore#_pattern_format">gitignore</a>. Only forward slashes (<code>/</code>, not backslashes) are used as path separators and octothorpes (<code>#</code>) or semicolons (<code>;</code>) are used for comments. Comments should go on their own lines. EditorConfig files should be UTF-8 encoded, with either <code><abbr title="Carriage Return Line Feed">CRLF</abbr></code> or <code><abbr title="Line Feed">LF</abbr></code> line separators. EditorConfig files are read top to bottom and the most recent rules found take precedence.</p>
<p>Filepath glob patterns and currently-supported EditorConfig properties are explained below.</p>
</section>
<section id="wildcards">
<h4>Wildcard Patterns</h4>
<p>Special characters recognized in section names for wildcard matching:</p>
<table>
<tr><td><code>*</code></td><td>Matches any string of characters, except path separators (<code>/</code>)</td></tr>
<tr><td><code>**</code></td><td>Matches any string of characters</td></tr>
<tr><td><code>?</code></td><td>Matches any single character</td></tr>
<tr><td><code>[name]</code></td><td>Matches any single character in <em>name</em></td></tr>
<tr><td><code>[!name]</code></td><td>Matches any single character not in <em>name</em></td></tr>
<tr><td><code>{s1,s2,s3}</code></td><td>Matches any of the strings given (separated by commas) (<strong>Available since EditorConfig Core 0.11.0</strong>)</td></tr>
<tr><td><code>{num1..num2}</code></td><td>Matches any integer numbers between <em>num1</em> and <em>num2</em>, where num1 and num2 can be either positive or negative</td></tr>
</table>
<p>Special characters can be escaped with a backslash so they won't be interpreted as wildcard patterns.</p>
</section>
<section id="supported-properties">
<h4>Supported Properties</h4>
<p>Note that not all properties are supported by every plugin. The wiki has a <a href="https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties">complete list of properties</a>.</p>
<ul class="property-definitions">
<li><dfn><code>indent_style</code></dfn>: set to <q>tab</q> or <q>space</q> to use hard tabs or soft tabs respectively.</li>
<li><dfn><code>indent_size</code></dfn>: a whole number defining the number of columns used for each indentation level and the width of soft tabs (when supported). When set to <q>tab</q>, the value of <strong><code>tab_width</code></strong> (if specified) will be used.</li>
<li><dfn><code>tab_width</code></dfn>: a whole number defining the number of columns used to represent a tab character. This defaults to the value of <strong><code>indent_size</code></strong> and doesn't usually need to be specified.</li>
<li><dfn><code>end_of_line</code></dfn>: set to <q>lf</q>, <q>cr</q>, or <q>crlf</q> to control how line breaks are represented.</li>
<li><dfn><code>charset</code></dfn>: set to <q>latin1</q>, <q>utf-8</q>, <q>utf-8-bom</q>, <q>utf-16be</q> or <q>utf-16le</q> to control the character set.</li>
<li><dfn><code>trim_trailing_whitespace</code></dfn>: set to <q>true</q> to remove any whitespace characters preceding newline characters and <q>false</q> to ensure it doesn't.</li>
<li><dfn><code>insert_final_newline</code></dfn>: set to <q>true</q> to ensure file ends with a newline when saving and <q>false</q> to ensure it doesn't.</li>
<li><dfn><code>root</code></dfn>: special property that should be specified at the top of the file outside of any sections. Set to <q>true</q> to stop <code>.editorconfig</code> files search on current file.</li>
</ul>
<p>Currently all properties and values are case-insensitive. They are lowercased when parsed. Generally, if a property is not specified, the editor settings will be used, i.e. EditorConfig takes no effect on that part. For any property, a value of <q>unset</q> is to remove the effect of that property, even if it has been set before. For example, add <code>indent_size = unset</code> to undefine <strong><code>indent_size</code></strong> property (and use editor default).</p>
<p>It is acceptable and often preferred to leave certain EditorConfig properties unspecified. For example, <strong><code>tab_width</code></strong> need not be specified unless it differs from the value of <strong><code>indent_size</code></strong>. Also, when <strong><code>indent_style</code></strong> is set to <q>tab</q>, it may be desirable to leave <strong><code>indent_size</code></strong> unspecified so readers may view the file using their preferred indentation width. Additionally, if a property is not standardized in your project (<strong><code>end_of_line</code></strong> for example), it may be best to leave it blank.</p>
</section>
</section>
<section id="pre-installed">
<h2>No Plugin Necessary</h2>
<p>These editors come bundled with native support for EditorConfig. Everything should just work.</p>
<ul class="editor-logos">
<li><a href="http://barebones.com/support/technotes/editorconfig.html"><img src="logos/bbedit.png" alt="BBEdit"><span>BBEdit</span></a></li>
<li><a href="https://sourceforge.net/projects/codecrusader/"><img src="logos/code-crusader.png" alt="Code Crusader"><span>Code Crusader</span></a></li>
<li><a href="https://github.com/eranif/codelite/tree/master/EditorConfigPlugin"><img src="logos/codelite.png" alt="CodeLite"><span>CodeLite</span></a></li>
<li><a href="https://github.com/elementary/code#readme"><img src="logos/elementary-code.png" alt="elementary Code"><span>elementary Code</span></a></li>
<li><a href="https://www.emeditor.com/text-editor-features/coding/editorconfig-support/"><img src="logos/emeditor.svg" alt="EmEditor"><span>EmEditor</span></a></li>
<li><a href="https://www.datatable.online/en/document/editor.html#editorconfig-profile"><img src="logos/kangaroo.svg" alt="Kangaroo"><span>Kangaroo</span></a></li>
<li><a href="https://wiki.gnome.org/Apps/Builder/Features#EditorConfig"><img src="logos/gnome-builder.png" alt="GNOME Builder" title="GNOME Builder"><span>GNOME Builder</span></a></li>
<li><a href="https://gitea.io/"><img src="logos/Gitea.png" alt="Gitea"><span>Gitea</span></a></li>
<li><a href="https://github.com/RReverser/github-editorconfig#readme"><img src="logos/github.png" alt="GitHub" title="GitHub (code viewer and editor)"><span>GitHub</span></a></li>
<li><a href="https://docs.gitlab.com/ee/user/project/web_ide/index.html#configure-the-web-ide"><img src="logos/gitlab.png" alt="GitLab" title="GitLab"><span>GitLab</span></a></li>
<li><a href="https://gitbucket.github.io/"><img src="logos/gitbucket.png" alt="GitBucket"><span>GitBucket</span></a></li>
<li><a href="https://gogs.io"><img src="logos/gogs.png" alt="Gogs"><span>Gogs</span></a></li>
<li><a href="https://plugins.jetbrains.com/plugin/7294-editorconfig/"><img src="logos/intellijIDEA.png" alt="intelliJ logo"><span>intelliJ</span></a></li>
<li><a href="https://gitlab.com/JakobDev/jdTextEdit"><img src="logos/jdTextEdit.png" alt="jdTextEdit logo"><span>jdTextEdit</span></a></li>
<li><a href="https://api.kde.org/frameworks/ktexteditor/html/"><img src="logos/ktexteditor.png" alt="KTextEditor"><span>KTextEditor</span></a></li>
<li><a href="https://www.activestate.com/blog/2015/07/editorconfig-your-komodo"><img src="logos/komodo.png" alt="Komodo"><span>Komodo</span></a></li>
<li><a href="https://github.com/mawww/kakoune/wiki/EditorConfig/"><img src="logos/kakoune.png" alt="Kakoune"><span>Kakoune</span></a></li>
<li><a href="https://docs.microsoft.com/en-us/visualstudio/releasenotes/vs2017-mac-relnotes-v7.5"><img src="logos/monodevelop.png" alt="MonoDevelop"><span>MonoDevelop</span></a></li>
<li><a href="https://neovim.io/"><img src="logos/neovim.png" alt="Neovim"><span></span></a></li>
<li><a href="https://nova.app/"><img src="logos/nova.png" alt="Nova"><span>Nova</span></a></li>
<li><a href="https://plugins.jetbrains.com/plugin/7294-editorconfig/"><img src="logos/phpStorm.png" alt="PHPStorm"><span>PHPStorm</span></a></li>
<li><a href="https://plugins.jetbrains.com/plugin/7294-editorconfig/"><img src="logos/pyCharm.png" alt="PyCharm"><span>PyCharm</span></a></li>
<li><a href="https://plugins.jetbrains.com/plugin/7294-editorconfig/"><img src="logos/reSharper.png" alt="ReSharper"><span>ReSharper</span></a></li>
<li><a href="https://plugins.jetbrains.com/plugin/7294-editorconfig/"><img src="logos/rider.png" alt="Rider"><span>Rider</span></a></li>
<li><a href="https://plugins.jetbrains.com/plugin/7294-editorconfig/"><img src="logos/rubyMine.png" alt="RubyMine"><span>RubyMine</span></a></li>
<li><a href="https://sourcehut.org/"><img src="logos/sourcehut.png" alt="sourcehut"><span>sourcehut</span></a></li>
<li><a href="https://www.sourcelair.com/features/editorconfig"><img src="logos/sourcelair.png" alt="SourcLair"><span>SourcLair</span></a></li>
<li><a href="https://tortoisegit.org/"><img src="logos/TortoiseGit.png" alt="TortoiseGit"><span>TortoiseGit</span></a></li>
<li><a href="https://www.vim.org/"><img src="logos/vim.png" alt="Vim"><span>Vim</span></a></li>
<li><a href="https://docs.microsoft.com/en-us/visualstudio/releasenotes/vs2017-relnotes-v15.0#coding-convention-support-through-editorconfig"><img src="logos/visualstudio-pro.png" alt="Visual Studio Pro"><span>Visual Studio Professional</span></a></li>
<li><a href="https://plugins.jetbrains.com/plugin/7294-editorconfig/"><img src="logos/webStorm.png" alt="WebStorm"><span>WebStorm</span></a></li>
<li><a href="https://workingcopy.app/"><img src="logos/working-copy.png" alt="Working Copy"><span>Working Copy</span></a></li>
<li><a href="https://developer.apple.com/xcode/"><img src="logos/xcode.png" alt="Xcode"><span>Xcode</span></a></li>
</ul>
<div style="clear: both;"></div>
</section>
<section id="download">
<h2 id="editor-plugins">Download a Plugin</h2>
<h3>Editor</h3>
<p>To use EditorConfig with one of these editors, you will need to install a plugin.</p>
<ul class="editor-logos">
<li><a href="https://plugins.jetbrains.com/plugin/7294-editorconfig/"><img src="logos/appCode.png" alt="AppCode"><span>AppCode</span></a></li>
<li><a href="https://github.com/sindresorhus/atom-editorconfig#readme"><img src="logos/atom.png" alt="Atom"><span>Atom</span></a></li>
<li><a href="https://github.com/kidwm/brackets-editorconfig/"><img src="logos/brackets.png" alt="Brackets"><span>Brackets</span></a></li>
<li><a href="https://plugins.jetbrains.com/plugin/7294-editorconfig/"><img src="logos/clion.png" alt="CLion"><span>CLion</span></a></li>
<li><a href="https://panic.com/coda/plugins.php#Plugins"><img src="logos/coda.png" alt="Coda"><span>Coda</span></a></li>
<li><a href="https://github.com/editorconfig/editorconfig-codeblocks#readme"><img src="logos/codeblocks.png" alt="Code::Block"><span>Code::Block</span></a></li>
<li><a href="https://github.com/ncjones/editorconfig-eclipse#readme"><img src="logos/eclipse.png" alt="Eclipse"><span>Eclipse</span></a></li>
<li><a href="https://github.com/editorconfig/editorconfig-emacs#readme"><img src="logos/emacs.png" alt="Emacs"><span>Emacs</span></a></li>
<li><a href="https://github.com/nightroman/FarNet/tree/master/EditorKit"><img src="logos/far-manager.png" alt="Far Manager"><span>Far Manager</span></a></li>
<li><a href="https://github.com/editorconfig/editorconfig-geany#readme"><img src="logos/geany.png" alt="Geany"><span>Geany</span></a></li>
<li><a href="https://github.com/editorconfig/editorconfig-gedit#readme"><img src="logos/gedit.png" alt="Gedit"><span>Gedit</span></a></li>
<li><a href="https://github.com/editorconfig/editorconfig-jedit#readme"><img src="logos/jedit.png" alt="jEdit"><span>jEdit</span></a></li>
<li><a href="https://github.com/skalogryz/editorConfig/tree/master/lazideext"><img src="logos/lazarus.png" alt="Lazarus"><span>Lazarus</span></a></li>
<li><a href="https://github.com/10sr/editorconfig-micro#readme"><img src="logos/micro.png" alt="Micro"><span>Micro</span></a></li>
<li><a href="https://github.com/welovecoding/editorconfig-netbeans#readme"><img src="logos/NetBeans.png" alt="NetBeans"><span>NetBeans</span></a></li>
<li><a href="https://github.com/editorconfig/editorconfig-notepad-plus-plus#readme"><img src="logos/notepad.png" alt="Notepad++"><span>Notepad++</span></a></li>
<li><a href="https://github.com/fszymanski/pluma-plugins/tree/master/editorconfig"><img src="logos/pluma.png" alt="Pluma"><span>Pluma</span></a></li>
<li><a href="https://github.com/sindresorhus/editorconfig-sublime#readme"><img src="logos/sublimetext.png" alt="Sublime Text"><span>Sublime Text</span></a></li>
<li><a href="https://github.com/editorconfig/editorconfig-textadept#readme"><img src="logos/textadept.png" alt="Textadept"><span>Textadept</span></a></li>
<li><a href="https://github.com/Mr0grog/editorconfig-textmate#readme"><img src="logos/textmate.png" alt="TextMate"><span>TextMate</span></a></li>
<li><a href="https://open-vsx.org/extension/EditorConfig/EditorConfig"><img src="logos/vscodium.png" alt="VSCodium"><span>VSCodium</span></a></li>
<li><a href="https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig"><img src="logos/visualstudio-code.png" alt="Visual Studio Code"><span>Visual Studio Code</span></a></li>
</ul>
<div style="clear: both;"></div>
<h3>Headless Tool</h3>
<p>To use EditorConfig with one of these headless tools, you will need to install a plugin.</p>
<ul class="editor-logos">
<li><a href="https://github.com/ec4j/editorconfig-ant-tasks"><img src="logos/apache-ant.png" alt="Apache Ant"><span>Apache Ant</span></a></li>
<li><a href="https://github.com/ec4j/editorconfig-gradle-plugin"><img src="logos/gradle.png" alt="Gradle"><span>Gradle</span></a></li>
<li><a href="https://ec4j.github.io/editorconfig-maven-plugin/"><img src="logos/maven.png" alt="Maven"><span>Maven</span></a></li>
</ul>
<div style="clear: both;"></div>
</section>
<section id="contributing">
<h2>Contributing to EditorConfig</h2>
<section id="feedback">
<h3>Give us your feedback</h3>
<p>This project is greatly in need of feedback from other developers. We want to hear ideas about how to make this project better. Please use the <a href="http://groups.google.com/group/editorconfig">mailing list</a> to send an email to the EditorConfig team (subscribe by shooting an email to <a href="mailto:[email protected]">[email protected]</a>) and use the <a href="https://github.com/editorconfig/editorconfig/issues">issue tracker</a> to submit bugs (but please take a look at the <a href="https://github.com/editorconfig/editorconfig/wiki/FAQ">FAQ</a> first). Also feel free to <a href="https://twitter.com/EditorConfig">tweet at us</a>.</p>
</section>
<section id="create-a-plugin">
<h3>Create an editor plugin</h3>
<p>
EditorConfig editor plugins must follow the <a href="https://spec.editorconfig.org">specifications</a>. They can be developed with the help from one of the EditorConfig core libraries.
The EditorConfig core libraries accept as input the file being edited, find and parse relevant <code>.editorconfig</code> files, and pass back the properties that should be used.
Please ignore any unrecognized properties and property values in your editor plugin for future compatibility, since new properties and permitted values will be added in the future.
</p>
<p>
EditorConfig core libraries exist for many programming languages:
</p>
<ul id="core-libraries">
<li><a href="https://github.com/editorconfig/editorconfig-core-c#readme">C library</a></li>
<li><a href="https://github.com/editorconfig/editorconfig-core-py#readme">Python library</a></li>
<li><a href="https://github.com/editorconfig/editorconfig-core-js#readme">JavaScript library</a></li>
<li>Java libraries: <a href="https://github.com/editorconfig/editorconfig-core-java#readme">EditorConfig Core Java</a> and <a href="https://github.com/ec4j/ec4j#readme">ec4j</a></li>
<li><a href="https://github.com/editorconfig/editorconfig-core-lua#readme">Lua library</a></li>
<li><a href="https://github.com/editorconfig/editorconfig-core-net#readme">.NET library</a></li>
<li><a href="https://github.com/editorconfig/editorconfig-core-ruby">Ruby library</a></li>
<li><a href="https://github.com/editorconfig/editorconfig-core-go">Go library</a></li>
<li><a href="https://github.com/TheDaemoness/ec4rs">Rust library</a></li>
</ul>
<p>If you are planning on creating a new plugin, use the <a href="https://groups.google.com/group/editorconfig">mailing list</a> to let us know so we can help out and link to your plugin once it's created. If you plan on using one of the EditorConfig cores as a library or command line interface, the <a href="http://docs.editorconfig.org">C library documentation</a>, <a href="http://pydocs.editorconfig.org">Python library documentation</a> or <a href="http://javadocs.editorconfig.org">Java library documentation</a> may be helpful.</p>
<p>More details can be found on the <a href="https://github.com/editorconfig/editorconfig/wiki/Plugin-How-To">Plugin-How-To wiki page</a>.</p>
</section>
<section id="contributors">
<h3>Main Contributors</h3>
<p>We have many awesome contributors contributing to the specification, core library, and plugins. For an up-to-date list, please see the <a href="https://github.com/editorconfig/editorconfig/wiki/Board-Member">Board Members page</a> and the <a href="https://docs.github.com/en/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors">contributor pages</a> of the <a href="https://github.com/editorconfig/specification/graphs/contributors">specification</a>, <a href="#core-libraries">core libraries</a>, and <a href="#editor-plugins">plugins</a>.</p>
<p>
Most of of EditorConfig logos were drawn by <a href="https://squirrelmuffins.com">Kat On</a> and <a href="https://pittankopta.net/">Amon Keishima</a>. Website were mainly by <a href="https://treyhunner.com">Trey Hunner</a> and <a href="https://www.topbug.net">Hong Xu</a>.
</p>
</section>
</section>