docs/usage.md

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