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