@@ -32,6 +32,7 @@ information.
3232- [ System configuration] ( #system-configuration )
3333- [ Character encoding] ( #character-encoding )
3434- [ Newlines] ( #newlines )
35+ - [ EOF and BOM] ( #eof-and-bom )
3536- [ File paths] ( #file-paths )
3637- [ Filenames] ( #filenames )
3738- [ Shell] ( #shell )
@@ -247,6 +248,36 @@ don't, which is why when reading from or writing to a file the OS-specific
247248newline [ ` os.EOL ` ] ( https://nodejs.org/api/os.html#os_os_eol ) should be used
248249instead of ` \n ` .
249250
251+ # EOF and BOM
252+
253+ The [ substitute character] ( https://en.wikipedia.org/wiki/Substitute_character )
254+ (` CTRL-Z ` )
255+ [ stops file streams] ( https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/read?view=vs-2017#remarks )
256+ on some Windows commands when in text mode. This includes the
257+ [ ` type ` command] ( https://ss64.com/nt/type.html ) in ` cmd.exe ` . As a consequence
258+ that character should be avoided in non-binary files.
259+
260+ As opposed to Windows, Unix does not implicitely add a newline at the end of
261+ files. Thus it is recommended to end files with a
262+ [ newline character] ( #newlines ) . However please remember that Windows will print
263+ these as if two newlines were present instead.
264+
265+ The [ BOM] ( https://en.wikipedia.org/wiki/Byte_order_mark ) is a special character
266+ at the beginning of a file indicating its
267+ [ endianness] ( https://en.wikipedia.org/wiki/Endianness ) and
268+ [ character encoding] ( https://en.wikipedia.org/wiki/Character_encoding ) . Since
269+ it creates issues with
270+ [ shebangs] ( < https://en.wikipedia.org/wiki/Shebang_(Unix) > ) and adds little
271+ value to [ UTF-8] ( https://en.wikipedia.org/wiki/UTF-8 ) , it is better not to add
272+ it to new files. However if a BOM is present in input, it should be properly
273+ handled. Fortunately this is the default behavior of Node.js core methods, so
274+ this should usually not create any issues.
275+
276+ Character encoding, newlines and EOF behavior should be specified with
277+ [ editorconfig] ( https://editorconfig.org/ ) . They can also be enforced with tools
278+ like [ ESLint] ( https://eslint.org/docs/rules/eol-last ) and
279+ [ Prettier] ( https://github.com/prettier/prettier ) .
280+
250281# File paths
251282
252283While ` / ` is used as a file path delimiter on Unix (` /file/to/path ` ), ` \ ` is
@@ -805,6 +836,11 @@ retrying few milliseconds later.
805836 [ log-symbols] ( https://github.com/sindresorhus/log-symbols ) .
806837- use [ ` os.EOL ` ] ( https://nodejs.org/api/os.html#os_os_eol ) when reading from or
807838 writing to a file, ` \n ` otherwise.
839+ - end files with a newline.
840+ - use [ editorconfig] ( https://editorconfig.org/ ) .
841+ - avoid the
842+ [ substitute character] ( https://en.wikipedia.org/wiki/Substitute_character )
843+ (` CTRL-Z ` ) in non-binary files.
808844- use
809845 [ ` path.normalize() ` ] ( https://nodejs.org/api/path.html#path_path_normalize_path )
810846 when writing a file path to a terminal or file. Otherwise use Unix paths
0 commit comments