BLACK(1)

💅 black — the manual page, but make it a group chat

okay bestie, so this is the manual for black, and the page itself is stamped 21.4b2 🎀 — that's the version, icon behavior. In the actual printed manual the top line reads black() on the left and 21.4b2 on the right, and honestly? iconic formatting. We love a symmetrical header. ✨

---

🌸 Name

black — the uncompromising Python code formatter. no cap, it says what it says. 🫶

---

💖 Summary

okay so here's the whole vibe: black is the uncompromising Python code formatter. And when you run it, you are literally, genuinely agreeing to cede control over minutiae of hand-formatting. like, you're handing over the aux cord. 🎧

In return, Black gives you:

• speed ⚡
• determinism 🎯
• freedom from pycodestyle nagging about formatting 😤

and the payoff is real: you will save time and mental energy for more important matters. main character energy only. 👑

---

🌈 Usage

black [OPTIONS] [SRC]...

---

✨ Common Options

girl there are SO many and I love all of them. here we go, one by one, no skips, periodt.

• -c, --code TEXT — format the code passed in as a string. just yeet the code straight in there as text. 💌
• -l, --line-length INTEGER — how many characters per line to allow. [default: 88] — yes bb, 88, the sacred number. 🧚
• -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39] — the Python versions that should be supported by Black's output. [default: per-file auto-detection] — it literally reads the room and figures it out per file. 🔍
• --pyi — format all input files like typing stubs regardless of file extension. super useful when piping source on standard input. 📥
• -S, --skip-string-normalization — don't normalize string quotes or prefixes. leave my quotes ALONE. 🙈
• -C, --skip-magic-trailing-comma — don't use trailing commas as a reason to split lines. the comma loses its power, rip. 💀
• --check — don't write the files back, just return the status. and the status codes are a whole language:
  • return code 0 means nothing would change 🟢
  • return code 1 means some files would be reformatted 🟡
  • return code 123 means there was an internal error 🔴
• --diff — don't write the files back, just output a diff for each file on stdout. show me the receipts. 🧾
• --color / --no-color — show colored diff. only applies when --diff is given. so it's giving ✨aesthetic✨ diff, but only in diff mode. no solo performances.
• --fast / --safe — if --fast is given, skip temporary sanity checks. [default: --safe] — we stay safety-on by default, bestie. 🛡️
• --include TEXT — a regular expression that matches files and directories that should be included on recursive searches. an empty value means all files are included regardless of the name. use forward slashes for directories on all platforms (Windows, too). exclusions are calculated first, inclusions later. [default: .pyi?$] — slash /.pyi?$/ energy, forward slashes everywhere, even Windows, I don't make the rules. 📁
• --exclude TEXT — a regular expression that matches files and directories that should be excluded on recursive searches. an empty value means no paths are excluded. use forward slashes for directories on all platforms (Windows, too). exclusions are calculated first, inclusions later. [default: /(.git|.hg|.mypy_cache|.tox|.venv|_build|buck-out|build|dist)/] — that whole little list of cursed folders gets left out, and honestly? correct. 🚫
• --extend-exclude TEXT — like --exclude, but adds additional files and directories on top of the excluded ones. (useful if you simply want to add to the default) — it's additive, not replacement, iykyk. ➕
• --force-exclude TEXT — like --exclude, but files and directories matching this regex will be excluded even when they are passed explicitly as arguments. like, even if you literally type the path. it will still say no. 💅
• --stdin-filename TEXT — the name of the file when passing it through stdin. useful to make sure Black will respect --force-exclude option on some editors that rely on using stdin. gotta give it a name so it knows whether to ghost it. 👻
• -q, --quiet — don't emit non-error messages to stderr. errors are still emitted — silence those with 2>/dev/null. so if you want TRUE silence you gotta do the redirect yourself, bestie. 🤫
• -v, --verbose — also emit messages to stderr about files that were not changed or were ignored due to --exclude=. spill the tea about every single file. ☕
• --version — show the version and exit. quick peek and bounce. 👀
• --config FILE — read configuration from PATH. 📜
• -h, --help — show this message and exit. the classic. if you're reading this, congrats, you already found it. 🎉

---

👑 Copyright

2018 Łukasz Langa

real ones credit the author. this is the copyright line, verbatim, don't touch it. 🫶

---

aaaand that's the whole page, bestie. the printed manual's bottom line is dated 2021-10-10, it's page 1, and it signs off as black(), version 21.4b2 — so consider this your cute little sign-off: written by the black crew, dated 2021-10-10, page 1, running on 21.4b2. now go format something gorgeous. 🌸💖✨