docs/installation_and_usage.md

   1 [//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM README.md"
   2
   3 # Installation and usage
   4
   5 ## Installation
   6
   7 _Black_ can be installed by running `pip install black`. It requires Python 3.6.0+ to
   8 run but you can reformat Python 2 code with it, too.
   9
  10 ### Install from GitHub
  11
  12 If you can't wait for the latest _hotness_ and want to install from GitHub, use:
  13
  14 `pip install git+git://github.com/psf/black`
  15
  16 ## Usage
  17
  18 To get started right away with sensible defaults:
  19
  20 ```sh
  21 black {source_file_or_directory}
  22 ```
  23
  24 You can run _Black_ as a package if running it as a script doesn't work:
  25
  26 ```sh
  27 python -m black {source_file_or_directory}
  28 ```
  29
  30 ## Command line options
  31
  32 _Black_ doesn't provide many options. You can list them by running `black --help`:
  33
  34 ```text
  35 Usage: black [OPTIONS] [SRC]...
  36
  37   The uncompromising code formatter.
  38
  39 Options:
  40   -c, --code TEXT                 Format the code passed in as a string.
  41   -l, --line-length INTEGER       How many characters per line to allow.
  42                                   [default: 88]
  43
  44   -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39]
  45                                   Python versions that should be supported by
  46                                   Black's output. [default: per-file auto-
  47                                   detection]
  48
  49   --pyi                           Format all input files like typing stubs
  50                                   regardless of file extension (useful when
  51                                   piping source on standard input).
  52
  53   -S, --skip-string-normalization
  54                                   Don't normalize string quotes or prefixes.
  55   --check                         Don't write the files back, just return the
  56                                   status.  Return code 0 means nothing would
  57                                   change.  Return code 1 means some files
  58                                   would be reformatted. Return code 123 means
  59                                   there was an internal error.
  60
  61   --diff                          Don't write the files back, just output a
  62                                   diff for each file on stdout.
  63
  64   --color / --no-color            Show colored diff. Only applies when
  65                                   `--diff` is given.
  66
  67   --fast / --safe                 If --fast given, skip temporary sanity
  68                                   checks. [default: --safe]
  69
  70   --include TEXT                  A regular expression that matches files and
  71                                   directories that should be included on
  72                                   recursive searches.  An empty value means
  73                                   all files are included regardless of the
  74                                   name.  Use forward slashes for directories
  75                                   on all platforms (Windows, too).  Exclusions
  76                                   are calculated first, inclusions later.
  77                                   [default: \.pyi?$]
  78
  79   --exclude TEXT                  A regular expression that matches files and
  80                                   directories that should be excluded on
  81                                   recursive searches.  An empty value means no
  82                                   paths are excluded. Use forward slashes for
  83                                   directories on all platforms (Windows, too).
  84                                   Exclusions are calculated first, inclusions
  85                                   later.  [default: /(\.eggs|\.git|\.hg|\.mypy
  86                                   _cache|\.nox|\.tox|\.venv|\.svn|_build|buck-
  87                                   out|build|dist)/]
  88
  89   --force-exclude TEXT            Like --exclude, but files and directories
  90                                   matching this regex will be excluded even
  91                                   when they are passed explicitly as arguments.
  92
  93   --stdin-filename TEXT           The name of the file when passing it through
  94                                   stdin. Useful to make sure Black will respect
  95                                   --force-exclude option on some editors that
  96                                   rely on using stdin.
  97
  98   -q, --quiet                     Don't emit non-error messages to stderr.
  99                                   Errors are still emitted; silence those with
 100                                   2>/dev/null.
 101
 102   -v, --verbose                   Also emit messages to stderr about files
 103                                   that were not changed or were ignored due to
 104                                   --exclude=.
 105
 106   --version                       Show the version and exit.
 107   --config FILE                   Read configuration from FILE path.
 108   -h, --help                      Show this message and exit.
 109 ```
 110
 111 _Black_ is a well-behaved Unix-style command-line tool:
 112
 113 - it does nothing if no sources are passed to it;
 114 - it will read from standard input and write to standard output if `-` is used as the
 115   filename;
 116 - it only outputs messages to users on standard error;
 117 - exits with code 0 unless an internal error occurred (or `--check` was used).
 118
 119 ## Using _Black_ with other tools
 120
 121 While _Black_ enforces formatting that conforms to PEP 8, other tools may raise warnings
 122 about _Black_'s changes or will overwrite _Black_'s changes. A good example of this is
 123 [isort](https://pypi.org/p/isort). Since _Black_ is barely configurable, these tools
 124 should be configured to neither warn about nor overwrite _Black_'s changes.
 125
 126 Actual details on _Black_ compatible configurations for various tools can be found in
 127 [compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md#black-compatible-configurations).
 128
 129 ## Migrating your code style without ruining git blame
 130
 131 A long-standing argument against moving to automated code formatters like _Black_ is
 132 that the migration will clutter up the output of `git blame`. This was a valid argument,
 133 but since Git version 2.23, Git natively supports
 134 [ignoring revisions in blame](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revltrevgt)
 135 with the `--ignore-rev` option. You can also pass a file listing the revisions to ignore
 136 using the `--ignore-revs-file` option. The changes made by the revision will be ignored
 137 when assigning blame. Lines modified by an ignored revision will be blamed on the
 138 previous revision that modified those lines.
 139
 140 So when migrating your project's code style to _Black_, reformat everything and commit
 141 the changes (preferably in one massive commit). Then put the full 40 characters commit
 142 identifier(s) into a file.
 143
 144 ```
 145 # Migrate code style to Black
 146 5b4ab991dede475d393e9d69ec388fd6bd949699
 147 ```
 148
 149 Afterwards, you can pass that file to `git blame` and see clean and meaningful blame
 150 information.
 151
 152 ```console
 153 $ git blame important.py --ignore-revs-file .git-blame-ignore-revs
 154 7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 1) def very_important_function(text, file):
 155 abdfd8b0 (Alice Doe  2019-09-23 11:39:32 -0400 2)     text = text.lstrip()
 156 7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 3)     with open(file, "r+") as f:
 157 7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 4)         f.write(formatted)
 158 ```
 159
 160 You can even configure `git` to automatically ignore revisions listed in a file on every
 161 call to `git blame`.
 162
 163 ```console
 164 $ git config blame.ignoreRevsFile .git-blame-ignore-revs
 165 ```
 166
 167 **The one caveat is that GitHub and GitLab do not yet support ignoring revisions using
 168 their native UI of blame.** So blame information will be cluttered with a reformatting
 169 commit on those platforms. (If you'd like this feature, there's an open issue for
 170 [GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/31423) and please let GitHub
 171 know!)
 172
 173 ## NOTE: This is a beta product
 174
 175 _Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
 176 projects, small and big. It also sports a decent test suite. However, it is still very
 177 new. Things will probably be wonky for a while. This is made explicit by the "Beta"
 178 trove classifier, as well as by the "b" in the version number. What this means for you
 179 is that **until the formatter becomes stable, you should expect some formatting to
 180 change in the future**. That being said, no drastic stylistic changes are planned,
 181 mostly responses to bug reports.
 182
 183 Also, as a temporary safety measure, _Black_ will check that the reformatted code still
 184 produces a valid AST that is equivalent to the original. This slows it down. If you're
 185 feeling confident, use `--fast`.