]> git.madduck.net Git - etc/vim.git/blobdiff - README.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:

Treat comments less magically
[etc/vim.git] / README.md
index c0870a8d748ccf49571f2c7ccfab3c4cda62b73a..b7c6229214fc55549aedd8c46d750d2795998a8a 100644 (file)
--- a/README.md
+++ b/README.md
@@ -43,6 +43,11 @@ black [OPTIONS] [SRC]...
 
 Options:
   -l, --line-length INTEGER   Where to wrap around.  [default: 88]
+  --check                     Don't write back the files, just return the
+                              status.  Return code 0 means nothing changed.
+                              Return code 1 means some files were reformatted.
+                              Return code 123 means there was an internal
+                              error.
   --fast / --safe             If --fast given, skip temporary sanity checks.
                               [default: --safe]
   --version                   Show the version and exit.
@@ -101,7 +106,7 @@ matching brackets.  If that doesn't work, it will put all of them in
 separate lines.
 ```py3
 # in:
-def very_important_function(template: str, *variables, *, file: os.PathLike, debug: bool = False):
+def very_important_function(template: str, *variables, file: os.PathLike, debug: bool = False):
     """Applies `variables` to the `template` and writes to `file`."""
     with open(file, 'w') as f:
         ...
@@ -110,7 +115,6 @@ def very_important_function(template: str, *variables, *, file: os.PathLike, deb
 def very_important_function(
     template: str,
     *variables,
-    *,
     file: os.PathLike,
     debug: bool = False,
 ):
@@ -179,6 +183,22 @@ explains it.  The tl;dr is "it's like highway speed limits, we won't
 bother you if you overdo it by a few km/h".
 
 
+### Empty lines
+
+*Black* will allow single empty lines left by the original editors,
+except when they're added within parenthesized expressions.  Since such
+expressions are always reformatted to fit minimal space, this whitespace
+is lost.
+
+It will also insert proper spacing before and after function definitions.
+It's one line before and after inner functions and two lines before and
+after module-level functions.  *Black* will put those empty lines also
+between the function definition and any standalone comments that
+immediately precede the given function.  If you want to comment on the
+entire function, use a docstring or put a leading comment in the function
+body.
+
+
 ### Editor integration
 
 There is currently no integration with any text editors. Vim and
@@ -226,7 +246,7 @@ statements.
 
 By making the code exclusively Python 3.6+, I'm able to focus on the
 quality of the formatting and re-use all the nice features of the new
-releases (check out [pathlib](docs.python.org/3/library/pathlib.html) or
+releases (check out [pathlib](https://docs.python.org/3/library/pathlib.html) or
 f-strings) instead of wasting cycles on Unicode compatibility, and so on.
 
 
@@ -248,13 +268,62 @@ answer is "because I don't like a particular formatting" then you're not
 ready to embrace *Black* yet. Such changes are unlikely to get accepted.
 You can still try but prepare to be disappointed.
 
+More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
+
 
 ## Change Log
 
+### 18.3a3
+
+* don't remove single empty lines outside of bracketed expressions
+  (#19)
+
+* added ability to pipe formatting from stdin to stdin (#25)
+
+* restored ability to format code with legacy usage of `async` as
+  a name (#20, #42)
+
+* even better handling of numpy-style array indexing (#33, again)
+
+
+### 18.3a2
+
+* changed positioning of binary operators to occur at beginning of lines
+  instead of at the end, following [a recent change to PEP8](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b)
+  (#21)
+
+* ignore empty bracket pairs while splitting. This avoids very weirdly
+  looking formattings (#34, #35)
+
+* remove a trailing comma if there is a single argument to a call
+
+* if top level functions were separated by a comment, don't put four
+  empty lines after the upper function
+
+* fixed unstable formatting of newlines with imports
+
+* fixed unintentional folding of post scriptum standalone comments
+  into last statement if it was a simple statement (#18, #28)
+
+* fixed missing space in numpy-style array indexing (#33)
+
+* fixed spurious space after star-based unary expressions (#31)
+
+
 ### 18.3a1
 
+* added `--check`
+
+* only put trailing commas in function signatures and calls if it's
+  safe to do so. If the file is Python 3.6+ it's always safe, otherwise
+  only safe if there are no `*args` or `**kwargs` used in the signature
+  or call. (#8)
+
 * fixed invalid spacing of dots in relative imports (#6, #13)
 
+* fixed invalid splitting after comma on unpacked variables in for-loops
+  (#23)
+
 * fixed spurious space in parenthesized set expressions (#7)
 
 * fixed spurious space after opening parentheses and in default