This is a small utility built on top of the black and isort Python code formatters to enable formatting of only regions which have changed in the Git working tree since the last commit.

You want to start unifying code style in your project using black. But instead of formatting the whole code base in one giant commit, you'd like to only change formatting when you're touching the code for other reasons.

This can also be useful when contributing to upstream codebases that are not under your complete control.

However, partial formatting is not supported by black itself, for various good reasons, and it won't be implemented either (134, 142, 245, 370, 511, 830).

This is where darker enters the stage. This tool is for those who want to do partial formatting anyway.

Note that this tool is meant for special situations when dealing with existing code bases. You should just use black as is when starting a project from scratch.

To install, use:

pip install darker

The darker <myfile.py> command reads the original file, formats it using black, combines original and formatted regions based on edits, and writes back over the original file.

Alternatively, you can invoke the module directly through the python executable, which may be preferable depending on your setup. Use python -m darker instead of darker in that case.

Example:

$ mkdir test && cd test && git init
Initialized empty Git repository in /tmp/test/.git/
$ echo "if True: print('hi')\n\nif False: print('there')" | tee test.py
if True: print('hi')

if False: print('there')
$ git add test.py && git commit -m "Initial commit"
[master (root-commit) a0c7c32] Initial commit
 1 file changed, 3 insertions(+)
 create mode 100644 test.py
$ echo "if True: print('changed')\n\nif False: print('there')" | tee test.py
if True: print('changed')

if False: print('there')
$ darker test.py && cat test.py
if True:
    print("changed")

if False: print('there')

Many editors have plugins or recipes for integrating black. You may be able to adapt them to be used with darker. See editor integration in the black documentation.

1. Install darker:

   $ pip install darker
   

2. Locate your darker installation folder.

   On macOS / Linux / BSD:

   $ which darker
   /usr/local/bin/darker  # possible location
   

   On Windows:

   $ where darker
   %LocalAppData%\Programs\Python\Python36-32\Scripts\darker.exe  # possible location
   

3. Open External tools in PyCharm/IntelliJ IDEA

   On macOS:

   PyCharm -> Preferences -> Tools -> External Tools

   On Windows / Linux / BSD:

   File -> Settings -> Tools -> External Tools

4. Click the + icon to add a new external tool with the following values:

   • Name: Darker
   • Description: Use Black to auto-format regions changed since the last git commit.
   • Program: <install_location_from_step_2>
   • Arguments: "$FilePath$"

5. Format the currently opened file by selecting Tools -> External Tools -> Darker.

   • Alternatively, you can set a keyboard shortcut by navigating to Preferences or Settings -> Keymap -> External Tools -> External Tools - Darker

6. Optionally, run darker on every file save:

   1. Make sure you have the File Watcher plugin installed.
   2. Go to Preferences or Settings -> Tools -> File Watchers and click + to add a new watcher:
      • Name: Darker
      • File type: Python
      • Scope: Project Files
      • Program: <install_location_from_step_2>
      • Arguments: $FilePath$
      • Output paths to refresh: $FilePath$
      • Working directory: $ProjectFileDir$
   3. Uncheck "Auto-save edited files to trigger the watcher"

Darker takes a git diff of your Python files, records which lines of current files have been edited or added since the last commit. It then runs black and notes which chunks of lines were reformatted. Finally, only those reformatted chunks on which edited lines fall (even partially) are applied to the edited file.

Also, in case the --isort option was specified, isort is run on each edited file before applying black.

BSD. See LICENSE.rst.

• black-macchiato
• darken