From ec0cf0eb69a8a7ef01260ff3600186061f8e5b57 Mon Sep 17 00:00:00 2001 From: Qix Date: Wed, 7 Jul 2021 00:40:54 +0200 Subject: [PATCH] Initial Home page --- Where-did-my-colored-output-go?.md | 34 ++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 Where-did-my-colored-output-go?.md diff --git a/Where-did-my-colored-output-go?.md b/Where-did-my-colored-output-go?.md new file mode 100644 index 0000000..c272c67 --- /dev/null +++ b/Where-did-my-colored-output-go?.md @@ -0,0 +1,34 @@ +> If you've wound up here, you're probably wondering why your application with Chalk output is missing color or other formatting. If you've been linked here, please understand that we get this question _a lot_ - there is no bug, nor is there anything we can do, and explaining this time and time again takes a lot of our time. + +Chalk uses what are called ["escape sequences" or "escape codes"](https://en.wikipedia.org/wiki/ANSI_escape_code) to tell supporting terminals how to style/format program output. Generally speaking, any program can output a stream of text to be shown, but with escape codes this text can be displayed in a variety of colors, formatting styles (bold, italic, underline, etc.), and even at different positions on the screen. + +**Chalk uses "standard" escape sequences and API calls to do what it does. There is nothing magical or unique about how Chalk outputs color. In _MOST_ cases, "bugs" reported to us are cases of user-error.** + +Not all terminals support these codes, and - perhaps worse - many [terminal emulators](https://en.wikipedia.org/wiki/Terminal_emulator) that _do_ support them often omit certain codes or have them behave much differently than other terminal emulators might. + +Further, these escape sequences are not magic. They are interleaved with normal program output (intended to be read by a human) and are simply characters that hold special meaning, just like any other text. This causes problems when programs are [piped](https://en.wikipedia.org/wiki/Pipeline_%28Unix%29) together, since those escape sequences are otherwise considered as input and can cause a variety of problems - the _best_ case being the program refusing the input altogether. + +Thus, most programs (in most languages, on most platforms, using most terminal frameworks, in most cases - **not** just Chalk) tend to check whether or not the target of the colorful output is a [TTY](https://en.wikipedia.org/wiki/Tty_(unix)) - in which case, it is a safe assumption that a user is interactively running the program. + +If it is _not_ a TTY, then we choose _not_ to output escape sequences, since it is a pretty safe assumption that the output of the program is being piped into another program as input. + +Some cases where your program's output _might_ be piped to another program: + +- It's running in a [Docker](https://www.docker.com/) container (including those created by Kubernetes) +- It's running in [PM2](https://pm2.keymetrics.io/) +- It's running within a [systemd](https://systemd.io/) unit (e.g. a service or timer) +- It's being monitored by some logging/error detection system +- It's running within [GNU Screen](https://en.wikipedia.org/wiki/GNU_Screen) (though this is unlikely as Screen tends to emulate a TTY) +- It's running within a [CI](https://en.wikipedia.org/wiki/Continuous_integration) system (though [we support](https://github.com/chalk/supports-color/issues?q=CI) many CI services) +- It's running inside of a [shell script](https://en.wikipedia.org/wiki/Shell_script) +- It's running on an old version of Windows +- Your terminal emulator doesn't support color codes +- About 1000 other potential causes. + +Chalk uses a library (called `supports-color`) to perform this check, which when most of the edge-case checks have been boiled away, uses Node's built-in [`isatty()`](https://nodejs.org/api/tty.html#tty_writestream_istty) to determine if the output of either [stdout or stderr](https://en.wikipedia.org/wiki/Standard_streams) are TTYs, depending on [which stream you're using Chalk with](https://github.com/chalk/chalk#chalkstderr-and-supportscolorstderr). + +--- + +So, where did your colors go? They probably aren't being displayed to begin with! + +If you're in a situation where you _know_ colors can be safely displayed, we provide a [variety](https://github.com/chalk/chalk#supportscolor) of [ways](https://github.com/chalk/chalk#chalklevel) to override `supports-color`'s result. All of this information, and more, is available in the [Chalk README](https://github.com/chalk/chalk#readme) :) \ No newline at end of file