eslint/docs/rules/linebreak-style.md

   1 # enforce consistent linebreak style (linebreak-style)
   2
   3 When developing with a lot of people all having different editors, VCS applications and operating systems it may occur that
   4 different line endings are written by either of the mentioned (might especially happen when using the windows and mac versions of SourceTree together).
   5
   6 The linebreaks (new lines) used in windows operating system are usually _carriage returns_ (CR) followed by a _line feed_ (LF) making it a _carriage return line feed_ (CRLF)
   7 whereas Linux and Unix use a simple _line feed_ (LF). The corresponding _control sequences_ are `"\n"` (for LF) and `"\r\n"` for (CRLF).
   8
   9 Many versioning systems (like git and subversion) can automatically ensure the correct ending. However to cover all contingencies, you can activate this rule.
  10
  11 ## Rule Details
  12
  13 This rule enforces consistent line endings independent of operating system, VCS, or editor used across your codebase.
  14
  15 ### Options
  16
  17 This rule has a string option:
  18
  19 * `"unix"` (default) enforces the usage of Unix line endings: `\n` for LF.
  20 * `"windows"` enforces the usage of Windows line endings: `\r\n` for CRLF.
  21
  22
  23 ### unix
  24
  25 Examples of **incorrect** code for this rule with the default `"unix"` option:
  26
  27 ```js
  28 /*eslint linebreak-style: ["error", "unix"]*/
  29
  30 var a = 'a'; // \r\n
  31
  32 ```
  33
  34 Examples of **correct** code for this rule with the default `"unix"` option:
  35
  36 ```js
  37 /*eslint linebreak-style: ["error", "unix"]*/
  38
  39 var a = 'a', // \n
  40     b = 'b'; // \n
  41 // \n
  42 function foo(params) { // \n
  43     // do stuff \n
  44 }// \n
  45 ```
  46
  47 ### windows
  48
  49 Examples of **incorrect** code for this rule with the `"windows"` option:
  50
  51 ```js
  52 /*eslint linebreak-style: ["error", "windows"]*/
  53
  54 var a = 'a'; // \n
  55 ```
  56
  57 Examples of **correct** code for this rule with the `"windows"` option:
  58
  59 ```js
  60 /*eslint linebreak-style: ["error", "windows"]*/
  61
  62 var a = 'a', // \r\n
  63     b = 'b'; // \r\n
  64 // \r\n
  65 function foo(params) { // \r\n
  66     // do stuff \r\n
  67 } // \r\n
  68 ```
  69
  70 ## Using this rule with version control systems
  71
  72 Version control systems sometimes have special behavior for linebreaks. To make it easy for developers to contribute to your codebase from different platforms, you may want to configure your VCS to handle linebreaks appropriately.
  73
  74 For example, the default behavior of [git](https://git-scm.com/) on Windows systems is to convert LF linebreaks to CRLF when checking out files, but to store the linebreaks as LF when committing a change. This will cause the `linebreak-style` rule to report errors if configured with the `"unix"` setting, because the files that ESLint sees will have CRLF linebreaks. If you use git, you may want to add a line to your [`.gitattributes` file](https://git-scm.com/docs/gitattributes) to prevent git from converting linebreaks in `.js` files:
  75
  76 ```
  77 *.js text eol=lf
  78 ```
  79
  80 ## When Not To Use It
  81
  82 If you aren't concerned about having different line endings within your code, then you can safely turn this rule off.
  83
  84 ## Compatibility
  85
  86 * **JSCS**: [validateLineBreaks](https://jscs-dev.github.io/rule/validateLineBreaks)