.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "" "1" "2021-10-10" "21.4b2-2" "uncompromising Python code formatter"
.SH NAME
black-primer \- CI tool to check a number of projects in parallel using black
.SH DESCRIPTION
.sp
\fBblack\-primer\fP is a tool built for CI (and humans) to have \fBblack\fP
\fB\-\-check\fP a number of Git accessible projects in parallel. Projects
are configured in \fBprimer.json\fP
.SH RUN FLOW
.INDENT 0.0
.IP \(bu 2
Ensure we have \fBblack\fP + \fBgit\fP installed
.IP \(bu 2
Load projects from \fBprimer.json\fP
.IP \(bu 2
Run projects in parallel with \fB\-\-worker\fP workers (defaults to CPU  count / 2)
.INDENT 2.0
.IP \(bu 2
Checkout projects
.IP \(bu 2
Run black and record result
.IP \(bu 2
Clean up repository checkout _(can optionally be disabled via
\fB\-\-keep\fP)
.UNINDENT
.IP \(bu 2
Display results summary to screen
.IP \(bu 2
Default to cleaning up \fB\-\-work\-dir\fP (which defaults to tempfile  schematics)
.IP \(bu 2
Return
\- 0 for successful run
\- < 0 for environment / internal error
\- > 0 for each project with an error
.UNINDENT
.SH SPEED UP RUNS
.sp
If you\(aqre running locally yourself to test black on lots of code try:
.INDENT 0.0
.IP \(bu 2
Using \fB\-k\fP / \fB\-\-keep\fP + \fB\-w\fP / \fB\-\-work\-dir\fP so you don\(aqt have
to re\-checkout the repo each run
.UNINDENT
.SH CLI ARGUMENTS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Usage: black\-primer [OPTIONS]

 primer \- prime projects for blackening...

Options:
 \-c, \-\-config PATH      JSON config file path  [default: /Users/cooper/repos/
                        black/src/black_primer/primer.json]

 \-\-debug                Turn on debug logging  [default: False]
 \-k, \-\-keep             Keep workdir + repos post run  [default: False]
 \-L, \-\-long\-checkouts   Pull big projects to test  [default: False]
 \-R, \-\-rebase           Rebase project if already checked out  [default:
                        False]

 \-w, \-\-workdir PATH     Directory path for repo checkouts  [default: /var/fol
                        ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
                        517125229]

 \-W, \-\-workers INTEGER  Number of parallel worker coroutines  [default: 2]
 \-h, \-\-help             Show this message and exit.
.EE
.UNINDENT
.UNINDENT
.sp
## Primer config file
.sp
The config file is in JSON format. Its main element is the \fI\(dqprojects\(dq\fP dictionary and
each parameter is explained below:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{
 \(dqprojects\(dq: {
   \(dq00_Example\(dq: {
     \(dqcli_arguments\(dq: \(dqList of extra CLI arguments to pass Black for this project\(dq,
     \(dqexpect_formatting_changes\(dq: \(dqBoolean to indicate that the version of Black is expected to cause changes\(dq,
     \(dqgit_clone_url\(dq: \(dqURL you would pass \(gagit clone\(ga to check out this repo\(dq,
     \(dqlong_checkout\(dq: \(dqBoolean to have repo skipped by default unless \(ga\-\-long\-checkouts\(ga is specified\(dq,
     \(dqpy_versions\(dq: \(dqList of major Python versions to run this project with \- all will do as you\(aqd expect \- run on ALL versions\(dq
   },
   \(dqaioexabgp\(dq: {
     \(dqcli_arguments\(dq: [],
     \(dqexpect_formatting_changes\(dq: true,
     \(dqgit_clone_url\(dq: \(dqhttps://github.com/cooperlees/aioexabgp.git\(dq,
     \(dqlong_checkout\(dq: false,
     \(dqpy_versions\(dq: [\(dqall\(dq, \(dq3.8\(dq]
   }
 }
}
.EE
.UNINDENT
.UNINDENT
.sp
An example primer config file is used by Black
[here](\fI\%https://github.com/psf/black/blob/master/src/black_primer/primer.json\fP)
.SH EXAMPLE RUN
.INDENT 0.0
.INDENT 3.5
.sp
.EX
cooper\-mbp:black cooper$ ~/venvs/b/bin/black\-primer
[2020\-05\-17 13:06:40,830] INFO: 4 projects to run Black over (lib.py:270)
[2020\-05\-17 13:06:44,215] INFO: Analyzing results (lib.py:285)
\-\- primer results 📊 \-\-

3 / 4 succeeded (75.0%) ✅
1 / 4 FAILED (25.0%) 💩
 \- 0 projects disabled by config
 \- 0 projects skipped due to Python version
 \- 0 skipped due to long checkout

Failed projects:

## flake8\-bugbear:
 \- Returned 1
 \- stdout:
\-\-\- tests/b303_b304.py      2020\-05\-17 20:04:09.991227 +0000
+++ tests/b303_b304.py      2020\-05\-17 20:06:42.753851 +0000
@@ \-26,11 +26,11 @@
     maxint = 5  # this is okay
     # the following should not crash
     (a, b, c) = list(range(3))
     # it is different than this
     a, b, c = list(range(3))
\-    a, b, c, = list(range(3))
+    a, b, c = list(range(3))
     # and different than this
     (a, b), c = list(range(3))
     a, *b, c = [1, 2, 3, 4, 5]
     b[1:3] = [0, 0]

would reformat tests/b303_b304.py
Oh no! 💥 💔 💥
1 file would be reformatted, 22 files would be left unchanged.
.EE
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2018 Łukasz Langa
.\" Generated by docutils manpage writer.
.