Skip to main content

README

EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs. The EditorConfig project consists of a file format for defining coding styles and a collection of text editor plugins 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. What's an EditorConfig file look like? Example file Below is an example .editorconfig file setting end of line and indentation styles for Python and JavaScript files. ; EditorConfig is awesome: http://EditorConfig.org

root = true ; top-most EditorConfig file

; Unix-style newlines with a newline ending every file[*]end_of_line = lfinsert_final_newline = true

; 4 space indentation[*.py]indent_style = spaceindent_size = 4

; Tab indentation (no size specified)[*.js]indent_style = tab

; Indentation override for all JS under lib directory[lib/**.js]indent_style = spaceindent_size = 2 Check the Wiki for some real world examples of projects using EditorConfig files. Where are these files stored? When opening a file, EditorConfig plugins look for a file named .editorconfig in the directory of the opened file and in every parent directory. A search for .editorconfig files will stop if the root filepath is reached or an EditorConfig file with root=true is found. EditorConfig files are read top to bottom and the closest EditorConfig files are read last. Properties from matching EditorConfig sections are applied in the order they were read, so properties in closer files take precedence. File Format Details EditorConfig files use an INI format with section names as filepath globs, similar to the format accepted bygitignore. Forward slashes (/) are used as path separators and semicolons (;) or octothorpes (#) are used for comments. Filepath glob patterns and currently-supported EditorConfig properties are explained below. Wildcard Patterns Special characters recognized in section names for wildcard matching:

  • Matches any string of characters, except path separators (/) ** Matches any string of characters ? Matches any single character [seq] Matches any single character in seq [!seq] Matches any single character not in seq Special characters can be escaped with a backslash so they will not be interpreted as wildcard patterns. Supported Properties Note that not all properties are supported by every plugin. indent_style: set to tab or space to use hard tabs or soft tabs respectively. indent_size: a whole number defining the number of columns used for each indentation level and the width of soft tabs (when supported). When set to tab, the value of tab_width (if specified) will be used. tab_width: a whole number defining the number of columns used to represent a tab character. This defaults to the value of indent_size and should not usually need to be specified. end_of_line: set to lf, cr, or crlf to control how line breaks are represented. charset: set to latin1, utf-8, utf-8-bom, utf-16be or utf-16le to control the character set. Use of utf-8-bom is discouraged. trim_trailing_whitespace: set to true to remove any whitespace characters preceeding newline characters and false to disable this feature. insert_final_newline: set to true ensure file ends with a newline when saving and false to disable this feature. root: special property that should be specified at the top of the file outside of any sections. Set totrue to stop .editorconfig files search on current file. It is acceptable and often prefered to leave certain EditorConfig properties unspecified. For exampletab_width need not be specified unless it differs from the value of indent_size. Also when indent_style is set to tab it may be desireable to leave indent_size unspecified so readers may view the file using their prefered indentation format. Additionally if a property is not standardized in your project (end_of_line for example) it may be best to leave it blank. Download a Plugin EditorConfig plugins are currently available for: ● Code::Blocks ● Emacs ● Geany ● Gedit ● jEdit ● Notepad++ ● Sublime Text 2 ● TextMate ● Vim ● Visual Studio Contributing to EditorConfig Give us your feedback 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 mailing list to send an email to the EditorConfig team and use the issue tracker to submit bugs. Also feel free to tweet at us. Create a plugin EditorConfig plugins can be developed by using one the EditorConfig core libraries. The EditorConfig core libraries accept as input the file being edited, find and parse relevant .editorconfig 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. Currently there is a C library and a Python library, and a Java binding for the Python library. If you are planning on creating a new plugin, use the mailing list 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 C library documentation, Python library documentation or Java binding documentation may be helpful. More details could be found on the Plugin-How-To wiki page. Authors and Contributors EditorConfig core code and current plugins (unless otherwise stated) were co-created by Trey Hunner and Hong Xu. Visual Studio plugin was created by William Swanson. Sublime Text 2 plugin was created by Sindre Sorhus. TextMate plugin was created by Rob Brackett. EditorConfig logo and illustrations are drawn by Kat On.