README.md (7783B)
1  2 [](http://melpa.org/#/editorconfig) 3 [](https://stable.melpa.org/#/editorconfig) 4 [](http://elpa.nongnu.org/nongnu/editorconfig.html) 5 6 7 # EditorConfig Emacs Plugin 8 9 This is an [EditorConfig][] plugin for [Emacs][]. 10 11 12 ## Getting Started 13 14 15 ### package.el 16 17 This package is available from [MELPA][], [MELPA Stable][] and [NonGNU ELPA][]. 18 Install from these repositories and enable global minor-mode `editorconfig-mode`: 19 20 ```emacs-lisp 21 (editorconfig-mode 1) 22 ``` 23 24 Normally, enabling `editorconfig-mode` should be enough for this plugin to work: 25 all other configurations are optional. 26 This mode sets up hooks so that EditorConfig properties will be 27 loaded and applied to the new buffers automatically when visiting files. 28 29 30 ### use-package 31 32 If you use [**use-package**][use-package], add the following to your 33 `init.el` file: 34 35 ```emacs-lisp 36 (use-package editorconfig 37 :ensure t 38 :config 39 (editorconfig-mode 1)) 40 ``` 41 42 43 ### Manual installation 44 45 Copy all `.el` files in this repository to `~/.emacs.d/lisp` and add the 46 following: 47 48 ```emacs-lisp 49 (add-to-list 'load-path "~/.emacs.d/lisp") 50 (require 'editorconfig) 51 (editorconfig-mode 1) 52 ``` 53 54 55 56 ## Supported properties 57 58 Current Emacs plugin coverage for EditorConfig's [properties][]: 59 60 * `indent_style` 61 * `indent_size` 62 * `tab_width` 63 * `end_of_line` 64 * `charset` 65 * `trim_trailing_whitespace` 66 * `insert_final_newline = true` is supported 67 * <del>`insert_final_newline = false`</del> is not enforced 68 (as in trailing newlines actually being removed automagically), 69 we just buffer-locally override any preferences that would auto-add them 70 to files `.editorconfig` marks as trailing-newline-free 71 * `max_line_length` 72 * <del>`file_type_ext` (Experimental)</del> (See below) 73 * <del>`file_type_emacs` (Experimental)</del> (See below) 74 * `root` (only used by EditorConfig core) 75 76 Not yet covered properties marked with <del>over-strike</del> 77 – pull requests implementing missing features warmly welcomed! 78 Typically, you will want to tie these to native functionality, 79 or the configuration of existing packages handling the feature. 80 81 As several packages have their own handling of, say, indentation, 82 we might not yet cover some mode you use, but we try to add the 83 ones that show up on our radar. 84 85 86 87 ### <del>File Type (file_type_ext, file_type_emacs)</del> 88 89 File-type feature is currently disabled, because this package is now undergoing 90 big internal refactoring. 91 For those who want this functionality, 92 please consider using [editorconfig-custom-majormode](https://github.com/10sr/editorconfig-custom-majormode-el). 93 94 95 ## Customize 96 97 `editorconfig-emacs` provides some customize variables. 98 99 Here are some of these variables: for the full list of available variables, 100 type <kbd>M-x customize-group [RET] editorconfig [RET]</kbd>. 101 102 103 ### `editorconfig-trim-whitespaces-mode` 104 105 Buffer local minor-mode to use to trim trailing whitespaces. 106 107 If set, editorconfig will enable/disable this mode in accord with 108 `trim_trailing_whitespace` property in `.editorconfig`. 109 Otherwise, use Emacs built-in `delete-trailing-whitespace` function. 110 111 One possible value is 112 [`ws-butler-mode`](https://github.com/lewang/ws-butler), with which 113 only lines touched get trimmed. To use it, add following to your 114 init.el: 115 116 ``` emacs-lisp 117 (setq editorconfig-trim-whitespaces-mode 118 'ws-butler-mode) 119 ``` 120 121 122 ### `editorconfig-after-apply-functions` 123 124 (Formerly `editorconfig-custom-hooks`) 125 126 A list of functions which will be called after loading common EditorConfig settings, 127 when you can set some custom variables. 128 129 For example, `web-mode` has several variables for indentation offset size and 130 EditorConfig sets them at once by `indent_size`. You can stop indenting 131 only blocks of `web-mode` by adding following to your init.el: 132 133 ```emacs-lisp 134 (add-hook 'editorconfig-after-apply-functions 135 (lambda (props) (setq web-mode-block-padding 0))) 136 ``` 137 138 139 ### `editorconfig-hack-properties-functions` 140 141 A list of functions to alter property values before applying them. 142 143 These functions will be run after loading \".editorconfig\" files and before 144 applying them to current buffer, so that you can alter some properties from 145 \".editorconfig\" before they take effect. 146 147 For example, Makefile files always use tab characters for indentation: you can 148 overwrite \"indent_style\" property when current `major-mode` is 149 `makefile-mode`: 150 151 ``` emacs-lisp 152 (add-hook 'editorconfig-hack-properties-functions 153 '(lambda (props) 154 (when (derived-mode-p 'makefile-mode) 155 (puthash 'indent_style "tab" props)))) 156 157 ``` 158 159 160 ## Troubleshooting 161 162 Enabling `editorconfig-mode` should be enough for normal cases. 163 164 When EditorConfig properties are not effective for unknown reason, we recommend 165 first trying `M-x editorconfig-display-current-properties`. 166 167 This command will open a new buffer and display the EditorConfig properties 168 loaded for current buffer. 169 You can check if EditorConfig properties were not read for buffers at all, 170 or they were loaded but did not take effect for some other reasons. 171 172 173 174 ### Indentation for new major-modes 175 176 Because most Emacs major-modes have their own indentation settings, this plugin 177 requires explicit support for each major-mode for `indent_size` property. 178 179 By default this plugin ships with settings for many major-modes, but, 180 sorry to say, it cannot be perfect. Especially it is difficult to support 181 brand-new major-modes. 182 Please feel free to submit issue or pull-request for such major-mode! 183 184 Supported major-modes and their indentation configs are defined in the variable 185 `editorconfig-indentation-alist`. 186 187 188 ### Not work at all for FOO-mode! 189 190 Most cases properties are loaded just after visiting files when 191 `editorconfig-mode` is enabled. 192 But it is known that there are major-modes that this mechanism does not work 193 for and require explicit call of `editorconfig-apply`. 194 195 Typically it will occur when the major-mode is not defined using 196 `define-derived-mode` (`rpm-spec-mode` is an example for this). 197 Please feel free to submit issues if you find such modes! 198 199 200 201 202 ## Submitting Bugs and Feature Requests 203 204 Bugs, feature requests, and other issues should be submitted to the issue 205 tracker: https://github.com/editorconfig/editorconfig-emacs/issues 206 207 208 ### Development 209 210 Make and [CMake][] must be installed to run the tests 211 locally: 212 213 $ make check 214 215 To start a new Emacs process with current `*.el` and without loading user init 216 file, run: 217 218 $ make sandbox 219 220 221 222 223 ## License 224 225 EditorConfig Emacs Plugin is free software: you can redistribute it 226 and/or modify it under the terms of the GNU General Public License as 227 published by the Free Software Foundation, either version 3 of the 228 License, or (at your option) any later version. 229 230 This program is distributed in the hope that it will be useful, but 231 WITHOUT ANY WARRANTY; without even the implied warranty of 232 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 233 General Public License for more details. 234 235 You should have received a copy of the GNU General Public License along 236 with this program. If not, see <https://www.gnu.org/licenses/>. 237 238 239 240 [Emacs]: https://www.gnu.org/software/emacs/ 241 [MELPA]: https://melpa.org/#/editorconfig 242 [MELPA Stable]: https://stable.melpa.org/#/editorconfig 243 [NonGNU ELPA]: http://elpa.nongnu.org/nongnu/editorconfig.html 244 [use-package]: https://www.emacswiki.org/emacs/UsePackage 245 [EditorConfig]: https://editorconfig.org 246 [EditorConfig C Core]: https://github.com/editorconfig/editorconfig-core-c 247 [properties]: https://editorconfig.org/#supported-properties 248 [CMake]: https://cmake.org