Skip to content

Commit 37a93db

Browse files
committed
Add EOF and BOM sections
1 parent 8f20e8f commit 37a93db

File tree

1 file changed

+36
-0
lines changed

1 file changed

+36
-0
lines changed

README.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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
247248
newline [`os.EOL`](https://nodejs.org/api/os.html#os_os_eol) should be used
248249
instead 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

252283
While `/` 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

Comments
 (0)