Editorconfig (/)
Total Page:16
File Type:pdf, Size:1020Kb
EditorConfig (/) What is EditorConfig? (/#overview) What is EditorConfig? Example File (/#example-file) EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs. The EditorConfig project consists of a file File Location (/#file- format for defining coding styles and a collection of text editor plugins that location) enable editors to read the file format and adhere to defined styles. EditorConfig File Format Details files are easily readable and they work nicely with version control systems. (/#file-format-details) Download a Plugin (/#download) What's an EditorConfig file look like? Contributing (/#contributing) Example file Blog (/blog) Below is an example .editorconfig file setting end-of-line and indentation styles for Python and JavaScript files. Project Page on GitHub # EditorConfig is awesome: http://EditorConfig.org # top-most EditorConfig file root = true (https://github.com/editorconfig/) # Unix-style newlines with a newline ending every file Follow Us [*] on Twitter 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 (https://twitter.com/EditorConfig) [*.py] (/blog/feed.xml) indent_style = space Tweet 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 Check the Wiki for some real-world examples of projects using EditorConfig files (https://github.com/editorconfig/editorconfig/wiki/Projects-Using- EditorConfig). 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. For Windows Users: To create an .editorconfig file within Windows Explorer, you need to create a file named .editorconfig., which Windows Explorer will automatically rename to .editorconfig. File Format Details EditorConfig files use an INI format that is compatible with the format used by Python ConfigParser Library (https://docs.python.org/2/library/configparser.html), but [ and ] are allowed in the section names. The section names are filepath globs (https://en.wikipedia.org/wiki/Glob_(programming)) (case sensitive), similar to the format accepted by gitignore (http://manpages.ubuntu.com/manpages/intrepid/man5/gitignore.5.html#contenttoc2). Only forward slashes (/, not backslashes) are used as path separators and octothorpes (#) or semicolons (;) are used for comments. Comments should go on their own lines. EditorConfig files should be UTF-8 encoded, with either CRLF (Carriage Return Line Feed) or LF (Line Feed) line separators. 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 [name] Matches any single character in name [!name] Matches any single character not in name {s1,s2,s3} Matches any of the strings given (separated by commas) (Available since EditorConfig Core 0.11.0) {num1..num2} Matches any integer numbers between num1 and num2, where num1 and num2 can be either positive or negative Special characters can be escaped with a backslash so they won't be interpreted as wildcard patterns. SUPPORTED PROPERTIES Note that not all properties are supported by every plugin. The wiki has a complete list of properties (https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties). 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 doesn't 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. trim_trailing_whitespace: set to “true” to remove any whitespace characters preceding newline characters and “false” to ensure it doesn't. insert_final_newline: set to “true” to ensure file ends with a newline when saving and “false” to ensure it doesn't. 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. 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. It is acceptable and often preferred to leave certain EditorConfig properties unspecified. For example, tab_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 desirable to leave indent_size unspecified so readers may view the file using their preferred indentation width. Additionally, if a property is not standardized in your project (end_of_line for example), it may be best to leave it blank. For any property, a value of “unset” is to remove the effect of that property, even if it has been set before. For example, add “indent_size = unset” to undefine indent_size property (and use editor default). No Plugin Necessary These editors come bundled with native support for EditorConfig. Everything should just work. (http://barebones.co(mh/tstpusp:p//ogritth/tuebc.hcnoomte/es(r/heatdntpitfso/c:r/oc/wdoeinklfii.tgge.n/htortemmele)/m.o(arhgstt/peAsrp/:Ep//sdg/iBtohuruCilbdo.ecnrof/imFgeP/RalutRugerienvs)e#rsEedri/tgoirtChuobn-fig) editorconfig#readme) (https://gogs.io) (https://github.com/J(ehttBtpras:in//sa/pini.tkedlleij.-org/fr(ahmttpesw:/o/wrkwsw/k.taecxttievedsittoart/eh.tcmolm/) /blog/2015/07/editorconfig- community/tree/master/plugins/editorconyfoigu)r-komodo) (https://plugins.jetbra(hinttsp.cso:/m/g/itphlugbi.nc/o7m29/J4(eh)ttBtpras:in//sw/winwte.lslioj-urcel(ahirt.tcposm:///tfoeratotuisreegsi/te.odritgo/r)config) community/tree/master/plugins/editorconfig) (https://github.com/e(dhitttoprsc:o//ngfiitgh/uebd.ictoormco/JnefitgB-rains/intellij- visualstudio#readmec)ommunity/tree/master/plugins/editorconfig) Download a Plugin Editor To use EditorConfig with one of these editors, you will need to install a plugin. (https://plugins.jetbra(hinttsp.cso:/m/g/itphlugbi.nc/o7m29/s4(ihn)tdtpress:/o/grhituhsu/ba.tcoomm-/k(ihdtwtpms/:b//rgaitchkuebts.c-om/JetBrains/intellij- editorconfig#readmee)ditorconfig/) community/tree/master/plugins/editorconfig) (https://panic.com/co(hdtatp/psl:u//gginiths.upbh.pco#mPl/ue(gdhiintttospr)sc:o//ngfiitgh/uebd.ictoormco/nn(chfijgtot-pnse:s//geidthituobrc.coonmfig/e- ditorconfig/editorconfig- codeblocks#readmee) clipse#readme) emacs#readme) (https://github.com/e(dhitttoprsc:o//ngfiitgh/uebd.ictoormco/en(dhfiigttto-prsc:o//ngfiitgh/uebd.ictoormco/en(dhfiigttto-prsc:o//ngfiitgh/uebd.ictoormco/1n0fisgr-/editorconfig- geany#readme) gedit#readme) jedit#readme) micro#readme) (https://github.com/w(hetlotpvse:c//ogditihnugb/e.cdoitmor/ce(odhnitttfopigrsc-:o//npfliugg/eindsit.ojertcborna(hfiingtts-p.cso:/m/g/itphlugbi.nc/o7m29/s4in) dresorhus/editorconfig- netbeans#readme) notepad-plus- sublime#readme) plus#readme) (https://github.com/e(dhitttoprsc:o//ngfiitgh/uebd.ictoormco/Mnfri0gg- rog/editorconfig- textadept#readme) textmate#readme) (https://github.com/e(dhitttoprsc:o//nmfiagr/keedtiptolarccoen.(vhfiigtst-upas:ls//tguidthiou.bc.ocmom/it/eMmasrc?oSero/EditorConfig- vim#readme) itemName=EditorCoXncfiogd.Eed)itorConfig) Headless Tool To use EditorConfig with one of these headless tools, you will need to install a plugin. (https://ec4j.github.io/editorconfig- maven-plugin/) 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 (http://groups.google.com/group/editorconfig) to send an email to the EditorConfig team (subscribe by shooting an email to [email protected] (mailto:[email protected])) and use the issue tracker (https://github.com/editorconfig/editorconfig/issues) to submit bugs (but please take a look at the FAQ (https://github.com/editorconfig/editorconfig/wiki/FAQ) first). Also feel free to tweet at us (https://twitter.com/#!/EditorConfig). Create a plugin EditorConfig plugins can be developed by using one of 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