2018 is not the year of Unicode on your desktop

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index 0633b799aa4f5e3e1bd25ab2a60e1e54322238a2..411c9bf6cf3bed57296aa51a7af1edb2379bdcd1 100644 (file)
--- a/README.md
+++ b/README.md
@@ -29,13 +29,13 @@ possible.
 ---
 
 *Contents:* **[Installation and usage](#installation-and-usage)** |
 ---
 
 *Contents:* **[Installation and usage](#installation-and-usage)** |

-**[The *Black* code style](#the-black-code-style)** |
+**[Code style](#the-black-code-style)** |
+**[pyproject.toml](#pyprojecttoml)** |

 **[Editor integration](#editor-integration)** |
 **[Version control integration](#version-control-integration)** |
 **[Ignoring unmodified files](#ignoring-unmodified-files)** |
 **[Testimonials](#testimonials)** |
 **[Show your style](#show-your-style)** |
 **[Editor integration](#editor-integration)** |
 **[Version control integration](#version-control-integration)** |
 **[Ignoring unmodified files](#ignoring-unmodified-files)** |
 **[Testimonials](#testimonials)** |
 **[Show your style](#show-your-style)** |

-**[License](#license)** |

 **[Contributing](#contributing-to-black)** |
 **[Change Log](#change-log)** |
 **[Authors](#authors)**
 **[Contributing](#contributing-to-black)** |
 **[Change Log](#change-log)** |
 **[Authors](#authors)**


@@ -103,6 +103,7 @@ Options:
                               that were not changed or were ignored due to
                               --exclude=.
   --version                   Show the version and exit.
                               that were not changed or were ignored due to
                               --exclude=.
   --version                   Show the version and exit.

+  --config PATH               Read configuration from PATH.

   --help                      Show this message and exit.
 ```
 
   --help                      Show this message and exit.
 ```
 


@@ -487,6 +488,98 @@ a future version of the formatter:
 * use `float` instead of `Union[int, float]`.
 
 
 * use `float` instead of `Union[int, float]`.
 
 

+## pyproject.toml
+
+*Black* is able to read project-specific default values for its
+command line options from a `pyproject.toml` file.  This is
+especially useful for specifying custom `--include` and `--exclude`
+patterns for your project.
+
+**Pro-tip**: If you're asking yourself "Do I need to configure anything?"
+the answer is "No".  *Black* is all about sensible defaults.
+
+
+### What on Earth is a `pyproject.toml` file?
+
+[PEP 518](https://www.python.org/dev/peps/pep-0518/) defines
+`pyproject.toml` as a configuration file to store build system
+requirements for Python projects.  With the help of tools
+like [Poetry](https://poetry.eustace.io/) or
+[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the
+need for `setup.py` and `setup.cfg` files.
+
+
+### Where *Black* looks for the file
+
+By default *Black* looks for `pyproject.toml` starting from the common
+base directory of all files and directories passed on the command line.
+If it's not there, it looks in parent directories.  It stops looking
+when it finds the file, or a `.git` directory, or a `.hg` directory,
+or the root of the file system, whichever comes first.
+
+If you're formatting standard input, *Black* will look for configuration
+starting from the current working directory.
+
+You can also explicitly specify the path to a particular file that you
+want with `--config`.  In this situation *Black* will not look for any
+other file.
+
+If you're running with `--verbose`, you will see a blue message if
+a file was found and used.
+
+
+### Configuration format
+
+As the file extension suggests, `pyproject.toml` is a [TOML](https://github.com/toml-lang/toml) file.  It contains separate
+sections for different tools.  *Black* is using the `[tool.black]`
+section.  The option keys are the same as long names of options on
+the command line.
+
+Note that you have to use single-quoted strings in TOML for regular
+expressions. It's the equivalent of r-strings in Python.  Multiline
+strings are treated as verbose regular expressions by Black.  Use `[ ]`
+to denote a significant space character.
+
+<details>
+<summary>Example `pyproject.toml`</summary>
+
+```toml
+[tool.black]
+line-length = 88
+py36 = true
+include = '\.pyi?$'
+exclude = '''
+/(
+    \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | _build
+  | buck-out
+  | build
+  | dist
+
+  # The following are specific to Black, you probably don't want those.
+  | blib2to3
+  | tests/data
+)/
+'''
+```
+
+</details>
+
+### Lookup hierarchy
+
+Command-line options have defaults that you can see in `--help`.
+A `pyproject.toml` can override those defaults.  Finally, options
+provided by the user on the command line override both.
+
+*Black* will only ever use one `pyproject.toml` file during an entire
+run. It doesn't look for multiple files, and doesn't compose
+configuration from different levels of the file hierarchy.
+
+

 ## Editor integration
 
 ### Emacs
 ## Editor integration
 
 ### Emacs


@@ -542,6 +635,7 @@ Commands and shortcuts:
 Configuration:
 * `g:black_fast` (defaults to `0`)
 * `g:black_linelength` (defaults to `88`)
 Configuration:
 * `g:black_fast` (defaults to `0`)
 * `g:black_linelength` (defaults to `88`)

+* `g:black_skip_string_normalization` (defaults to `0`)

 * `g:black_virtualenv` (defaults to `~/.vim/black`)
 
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 * `g:black_virtualenv` (defaults to `~/.vim/black`)
 
 To install with [vim-plug](https://github.com/junegunn/vim-plug):


@@ -589,7 +683,9 @@ to do this.
 
 ### Visual Studio Code
 
 
 ### Visual Studio Code
 

-Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
+Use the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+([instructions](https://code.visualstudio.com/docs/python/editing#_formatting))
+or [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).

 
 
 ### SublimeText 3
 
 
 ### SublimeText 3


@@ -629,16 +725,18 @@ repos:
     rev: stable
     hooks:
     - id: black
     rev: stable
     hooks:
     - id: black

-      args: [--line-length=88, --safe]

       language_version: python3.6
 ```
 Then run `pre-commit install` and you're ready to go.
 
       language_version: python3.6
 ```
 Then run `pre-commit install` and you're ready to go.
 

-`args` in the above config is optional but shows you how you can change
-the line length if you really need to.  If you're already using Python
-3.7, switch the `language_version` accordingly. Finally, `stable` is a tag
-that is pinned to the latest release on PyPI.  If you'd rather run on
-master, this is also an option.
+Avoid using `args` in the hook.  Instead, store necessary configuration
+in `pyproject.toml` so that editors and command-line usage of Black all
+behave consistently for your project.  See *Black*'s own `pyproject.toml`
+for an example.
+
+If you're already using Python 3.7, switch the `language_version`
+accordingly. Finally, `stable` is a tag that is pinned to the latest
+release on PyPI.  If you'd rather run on master, this is also an option.

 
 
 ## Ignoring unmodified files
 
 
 ## Ignoring unmodified files


@@ -709,6 +807,13 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
 
 ## Change Log
 

+### 18.6b2
+
+* added `--config` (#65)
+
+* fixed improper unmodified file caching when `-S` was used
+
+

 ### 18.6b1
 
 * hotfix: don't output human-facing information on stdout (#299)
 ### 18.6b1
 
 * hotfix: don't output human-facing information on stdout (#299)


@@ -1031,18 +1136,3 @@ Multiple contributions by:
 * [Stavros Korokithakis](mailto:hi@stavros.io)
 * [Sunil Kapil](mailto:snlkapil@gmail.com)
 * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
 * [Stavros Korokithakis](mailto:hi@stavros.io)
 * [Sunil Kapil](mailto:snlkapil@gmail.com)
 * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)

-
----
-
-*Contents:*
-**[Installation and Usage](#installation-and-usage)** |
-**[The *Black* code style](#the-black-code-style)** |
-**[Editor integration](#editor-integration)** |
-**[Version control integration](#version-control-integration)** |
-**[Ignoring unmodified files](#ignoring-unmodified-files)** |
-**[Testimonials](#testimonials)** |
-**[Show your style](#show-your-style)** |
-**[License](#license)** |
-**[Contributing](#contributing-to-black)** |
-**[Change Log](#change-log)** |
-**[Authors](#authors)**