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