]> git.madduck.net Git - etc/vim.git/blob - docs/installation_and_usage.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Include mode information for unstable formattings
[etc/vim.git] / 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]
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   -q, --quiet                     Don't emit non-error messages to stderr.
94                                   Errors are still emitted; silence those with
95                                   2>/dev/null.
96
97   -v, --verbose                   Also emit messages to stderr about files
98                                   that were not changed or were ignored due to
99                                   --exclude=.
100
101   --version                       Show the version and exit.
102   --config FILE                   Read configuration from FILE path.
103   -h, --help                      Show this message and exit.
104 ```
105
106 _Black_ is a well-behaved Unix-style command-line tool:
107
108 - it does nothing if no sources are passed to it;
109 - it will read from standard input and write to standard output if `-` is used as the
110   filename;
111 - it only outputs messages to users on standard error;
112 - exits with code 0 unless an internal error occurred (or `--check` was used).
113
114 ## Using _Black_ with other tools
115
116 While _Black_ enforces formatting that conforms to PEP 8, other tools may raise warnings
117 about _Black_'s changes or will overwrite _Black_'s changes. A good example of this is
118 [isort](https://pypi.org/p/isort). Since _Black_ is barely configurable, these tools
119 should be configured to neither warn about nor overwrite _Black_'s changes.
120
121 Actual details on _Black_ compatible configurations for various tools can be found in
122 [compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md).
123
124 ## Migrating your code style without ruining git blame
125
126 A long-standing argument against moving to automated code formatters like _Black_ is
127 that the migration will clutter up the output of `git blame`. This was a valid argument,
128 but since Git version 2.23, Git natively supports
129 [ignoring revisions in blame](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revltrevgt)
130 with the `--ignore-rev` option. You can also pass a file listing the revisions to ignore
131 using the `--ignore-revs-file` option. The changes made by the revision will be ignored
132 when assigning blame. Lines modified by an ignored revision will be blamed on the
133 previous revision that modified those lines.
134
135 So when migrating your project's code style to _Black_, reformat everything and commit
136 the changes (preferably in one massive commit). Then put the full 40 characters commit
137 identifier(s) into a file.
138
139 ```
140 # Migrate code style to Black
141 5b4ab991dede475d393e9d69ec388fd6bd949699
142 ```
143
144 Afterwards, you can pass that file to `git blame` and see clean and meaningful blame
145 information.
146
147 ```console
148 $ git blame important.py --ignore-revs-file .git-blame-ignore-revs
149 7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 1) def very_important_function(text, file):
150 abdfd8b0 (Alice Doe  2019-09-23 11:39:32 -0400 2)     text = text.lstrip()
151 7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 3)     with open(file, "r+") as f:
152 7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 4)         f.write(formatted)
153 ```
154
155 You can even configure `git` to automatically ignore revisions listed in a file on every
156 call to `git blame`.
157
158 ```console
159 $ git config blame.ignoreRevsFile .git-blame-ignore-revs
160 ```
161
162 **The one caveat is that GitHub and GitLab do not yet support ignoring revisions using
163 their native UI of blame.** So blame information will be cluttered with a reformatting
164 commit on those platforms. (If you'd like this feature, there's an open issue for
165 [GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/31423) and please let GitHub
166 know!)
167
168 ## NOTE: This is a beta product
169
170 _Black_ is already [successfully used](#used-by) by many projects, small and big. It
171 also sports a decent test suite. However, it is still very new. Things will probably be
172 wonky for a while. This is made explicit by the "Beta" trove classifier, as well as by
173 the "b" in the version number. What this means for you is that **until the formatter
174 becomes stable, you should expect some formatting to change in the future**. That being
175 said, no drastic stylistic changes are planned, mostly responses to bug reports.
176
177 Also, as a temporary safety measure, _Black_ will check that the reformatted code still
178 produces a valid AST that is equivalent to the original. This slows it down. If you're
179 feeling confident, use `--fast`.