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