docs/usage.md

   1 # Installation and Usage
   2
   3 ## Installation
   4
   5 *Black* can be installed by running `pip install black`.
   6
   7 ## Usage
   8
   9 To get started right away with sensible defaults:
  10
  11 ```
  12 black {source_file}
  13 ```
  14
  15 ### Command line options
  16
  17 Some basics about the command line help, `black --help`:
  18
  19 ```
  20 Usage: black [OPTIONS] [SRC]...
  21
  22   The uncompromising code formatter.
  23
  24 Options:
  25   -l, --line-length INTEGER  How many character per line to allow.  [default:
  26                              88]
  27   --check                    Don't write back the files, just return the
  28                              status.  Return code 0 means nothing would
  29                              change.  Return code 1 means some files would be
  30                              reformatted.  Return code 123 means there was an
  31                              internal error.
  32   --fast / --safe            If --fast given, skip temporary sanity checks.
  33                              [default: --safe]
  34   --version                  Show the version and exit.
  35   --help                     Show this message and exit.
  36 ```
  37
  38 `Black` is a well-behaved Unix-style command-line tool:
  39
  40 * it does nothing if no sources are passed to it;
  41 * it will read from standard input and write to standard output if `-`
  42   is used as the filename;
  43 * it only outputs messages to users on standard error;
  44 * exits with code 0 unless an internal error occured (or `--check` was
  45   used).
  46
  47 ## Important note about the pre-release of Black
  48
  49 *Black* can already successfully format itself and the standard library.
  50 It also sports a decent test suite.  However, it is still very new.
  51 Things will probably be wonky for a while. This is made explicit by the
  52 "Alpha" trove classifier, as well as by the "a" in the version number.
  53 What this means for you is that **until the formatter becomes stable,
  54 you should expect some formatting to change in the future**.
  55
  56 Also, as a temporary safety measure, *Black* will check that the
  57 reformatted code still produces a valid AST that is equivalent to the
  58 original.  This slows it down.  If you're feeling confident, use
  59 ``--fast``.