The style file for your project should be configured in the
[tool.nitpick] section of the configuration file.
Possible configuration files (in order of precedence):
The first file found will be used; the other files will be ignored.
nipick init CLI command to create a config file (init: Initialise a configuration file).
To configure your own style, you can either use
$ nitpick init /path/to/your-style-file.toml
or edit your configuration file and set the
[tool.nitpick] style = "/path/to/your-style-file.toml"
You can set
style with any local file or URL.
Use the URL of the remote file.
If it’s hosted on GitHub, use any of the following formats:
GitHub URL scheme (
gh://) pinned to a specific version:
[tool.nitpick] style = "github://email@example.com/nitpick-style.toml" # or style = "gh://firstname.lastname@example.org/nitpick-style.toml"
@ syntax is used to get a Git reference (commit, tag, branch).
It is similar to the syntax used by
If no Git reference is provided, the default GitHub branch will be used (for Nitpick, it’s
[tool.nitpick] style = "github://andreoliwa/nitpick/nitpick-style.toml" # or style = "gh://andreoliwa/nitpick/nitpick-style.toml" # It has the same effect as providing the default branch explicitly: style = "github://andreoliwa/nitpick@develop/nitpick-style.toml" # or style = "gh://andreoliwa/nitpick@develop/nitpick-style.toml"
A regular GitHub URL also works. The corresponding raw URL will be used.
[tool.nitpick] style = "https://github.com/andreoliwa/nitpick/blob/v0.32.0/nitpick-style.toml"
Or use the raw GitHub URL directly:
[tool.nitpick] style = "https://raw.githubusercontent.com/andreoliwa/nitpick/v0.32.0/nitpick-style.toml"
You can also use the raw URL of a GitHub Gist:
[tool.nitpick] style = "https://gist.githubusercontent.com/andreoliwa/f4fccf4e3e83a3228e8422c01a48be61/raw/ff3447bddfc5a8665538ddf9c250734e7a38eabb/remote-style.toml"
If your style is on a private GitHub repo, you can provide the token directly on the URL. Or you can use an environment variable to avoid keeping secrets in plain text.
[tool.nitpick] # A literal token style = "github://p5iCG5AJuDgY@some-user/a-private-repo@some-branch/nitpick-style.toml" # Or reading the secret value from the MY_AUTH_KEY env var style = "github://$MY_AUTH_KEY@some-user/a-private-repo@some-branch/nitpick-style.toml"
A literal token cannot start with a
All tokens must not contain any
Style inside Python package
The style file can be fetched from an installed Python package.
Example of a use case: you create a custom flake8 extension and you also want to distribute a (versioned) Nitpick style bundled as a resource inside the Python package (check out this issue: Get style file from python package · Issue #202).
Python package URL scheme is
[tool.nitpick] style = "pypackage://some_python_package.styles.nitpick-style.toml" # or style = "py://some_python_package.styles.nitpick-style.toml"
Thanks to @isac322 for this feature.
Remote styles can be cached to avoid unnecessary HTTP requests.
The cache can be configured with the
cache key; see the examples below.
By default, remote styles will be cached for one hour.
This default will also be used if the
cache key has an invalid value.
Expiring after a predefined time
The cache can be set to expire after a defined time unit.
Use the format
cache = "<integer> <time unit>".
Time unit can be one of these (plural or singular, it doesn’t matter):
To cache for 15 minutes:
[tool.nitpick] style = "https://example.com/remote-style.toml" cache = "15 minutes"
To cache for 1 day:
[tool.nitpick] style = "https://example.com/remote-style.toml" cache = "1 day"
With this option, once the style(s) are cached, they never expire.
[tool.nitpick] style = "https://example.com/remote-style.toml" cache = "forever"
With this option, the cache is never used. The remote style file(s) are always looked-up and a HTTP request is always executed.
[tool.nitpick] style = "https://example.com/remote-style.toml" cache = "never"
The cache files live in a subdirectory of your project:
To clear the cache, simply remove this directory.
Using a file in your home directory:
[tool.nitpick] style = "~/some/path/to/another-style.toml"
Using a relative path from another project in your hard drive:
[tool.nitpick] style = "../another-project/another-style.toml"
You can also use multiple styles and mix local files and URLs.
Example of usage: the
[tool.nitpick] table on Nitpick’s own pyproject.toml.
[tool.nitpick] style = [ "/path/to/first.toml", "/another/path/to/second.toml", "https://example.com/on/the/web/third.toml" ]
The order is important: each style will override any keys that might be set by the previous
If a key is defined in more than one file, the value from the last file will prevail.
Override a remote style
You can use a remote style as a starting point, and override settings on your local style file.
./ to indicate the local style:
[tool.nitpick] style = [ "https://example.com/on/the/web/remote-style.toml", "./my-local-style.toml", ]
For Windows users: even though the path separator is a backslash, use the example above as-is. The “dot-slash” is a convention for Nitpick to know this is a local style file.