git-format-staged 4.0.0 → 4.0.1

package/README.md

@@ -128,30 +128,55 @@ option to tell it to read content from `stdin` instead of reading files from
 disk, and messages from `eslint` are redirected to `stderr` (using the `>&2`
 notation) so that you can see them.
 
-### Set up a pre-commit hook with Husky
+### Set up a pre-commit hook
 
-Follow these steps to automatically format all Javascript files on commit in
-a project that uses npm.
+A git pre-commit hook runs automatically whenever you make a commit, before your
+editor opens to write a commit message. If formatting fails with a non-zero exit
+status it will cancel the commit, requiring you to fix the problem before trying
+again. (You can always skip a pre-commit hook by running `git commit
+--no-verify`.) But in most cases you will have correctly formatted files at all
+times, without having to think about it again after setup. Whenever a file is
+changed as a result of formatting on commit you will see a message in the output
+from `git commit`.
 
-Install git-format-staged, husky, and a formatter (I use `prettier`):
+There are a number of options for setting up a git pre-commit hook depending on
+the software ecosystem you are working with.
 
-    $ npm install --save-dev git-format-staged husky prettier
+#### Write a pre-commit hook manually
 
-Add a `prepare` script to install husky when running `npm install`:
+You can write a hook manually by creating the file `.git/hooks/pre-commit`, and
+making it executable. A hook set up this way will _not_ automatically propagate
+to other clones, so every collaborator will have to do this themselves.
 
-    $ npm set-script prepare "husky install"
-    $ npm run prepare
+#### Nix devShell
 
-Add the pre-commit hook:
+If you use a Nix devShell you can use [nix-git-hooks][] to help set up
+a pre-commit hook automatically. You can either automatically install hooks for
+everyone who uses the devShell, or provide a command that collaborators can run
+to easily opt in to hooks. Take a look at how this repo uses nix-git-hooks in
+[flake.nix](./flake.nix).
 
-    $ npx husky add .husky/pre-commit "git-format-staged --formatter 'prettier --stdin-filepath {}' '*.js' '*.ts'"
-    $ git add .husky/pre-commit
+[nix-git-hooks]: https://github.com/ysndr/nix-git-hooks
 
-Once again note that the formatter command and the `'*.js'` and `'*.ts'`
-patterns are quoted!
+#### Npm, yarn, pnpm, or bun
 
-That's it! Whenever a file is changed as a result of formatting on commit you
-will see a message in the output from `git commit`.
+[Husky][] will automatically install git hooks for all project collaborators
+after running package manager commands.
+
+[Husky]: https://typicode.github.io/husky/get-started.html
+
+#### Rust with Cargo
+
+[cargo-husky][] is like Husky, but for Rust projects.
+
+[cargo-husky]: https://crates.io/crates/cargo-husky
+
+#### and more!
+
+See more hook management options in [awesome-git][] and [awesome-git-hooks][].
+
+[awesome-git]: https://github.com/dictcp/awesome-git?tab=readme-ov-file#hook-management.
+[awesome-git-hooks]: https://github.com/compscilauren/awesome-git-hooks?tab=readme-ov-file#tools
 
 ## Comparisons to similar utilities
 

package/git-format-staged

@@ -20,13 +20,14 @@ from fnmatch import fnmatch
 from gettext import gettext as _
 import re
 import shlex
+import signal
 import subprocess
 import sys
 from typing import NoReturn, Protocol, cast
 
 
-# The string 4.0.0 is replaced during the publish process.
-VERSION = "4.0.0"
+# The string 4.0.1 is replaced during the publish process.
+VERSION = "4.0.1"
 PROG = sys.argv[0]
 
 
@@ -34,6 +35,10 @@ def info(msg: str):
     print(msg, file=sys.stdout)
 
 
+def info_stderr(msg: str):
+    print(msg, file=sys.stderr)
+
+
 def warn(msg: str):
     print("{}: warning: {}".format(PROG, msg), file=sys.stderr)
 
@@ -144,31 +149,85 @@ def format_object(
     get_content = subprocess.Popen(
         ["git", "cat-file", "-p", object_hash], stdout=subprocess.PIPE
     )
+
     command = re.sub(file_path_placeholder, shlex.quote(file_path), formatter)
     if verbose:
-        info(command)
+        info_stderr(command)
     format_content = subprocess.Popen(
         command, shell=True, stdin=get_content.stdout, stdout=subprocess.PIPE
     )
+
     write_object = subprocess.Popen(
         ["git", "hash-object", "-w", "--stdin"],
         stdin=format_content.stdout,
         stdout=subprocess.PIPE,
     )
 
-    # Read output from the final process first to avoid deadlock if intermediate processes produce
-    # large outputs that would fill pipe buffers
+    # Close the parent process reference to stdout, leaving only references in the child processes.
+    # This way if the downstream process terminates while format_content is still running,
+    # format_content will be terminated with a SIGPIPE signal.
+    format_content.stdout.close()  # pyright: ignore[reportOptionalMemberAccess]
+
+    # On the other hand we don't close get_content.stdout() so that we can check if there is unread
+    # data left after the formatter has finished.
+
+    # Read output from the last process in the pipe, and block until that process has completed.
+    # It's important to block on the last process completing before waiting for the other sub
+    # processes to finish.
     new_hash, _err = write_object.communicate()
 
-    if get_content.wait() != 0:
-        raise ValueError(
-            "unable to read file content from object database: " + object_hash
+    # The first two pipe processes should have completed by now. Block to verify that we have exit
+    # statuses from them.
+    try:
+        # Use communicate() to check for any unread output from get_content.
+        get_content_unread_stdout, _ = get_content.communicate(timeout=5)
+        get_content.stdout.close()  # pyright: ignore[reportOptionalMemberAccess]
+        format_content_exit_status = format_content.wait(timeout=5)
+    except subprocess.TimeoutExpired as exception:
+        raise Exception(
+            "the formatter command did not terminate as expected"
+        ) from exception
+
+    # An error from format_content is most relevant to the user, so prioritize displaying this error
+    # message in case multiple things went wrong.
+    if format_content_exit_status != 0:
+        raise Exception(
+            f"formatter exited with non-zero status ({format_content_exit_status}) while processing {file_path}"
+        )
+
+    # If the formatter exited before reading all input then get_content might have been terminated
+    # by a SIGPIPE signal. This is probably incorrect behavior from the formatter command, but is
+    # allowed by design (for now). So we emit a warning, but will not fail.
+
+    # If there was unread output from get_content that's an indication that the formatter command is
+    # probably not configured correctly. But program design allows the formatter command do do what
+    # it wants. So this is a warning, not a hard error.
+    #
+    # A SIGPIPE termination to get_content would also indicate unread output. This should not
+    # happen, but it doesn't hurt to check.
+    if len(get_content_unread_stdout) > 0 or get_content.returncode == -signal.SIGPIPE:
+        warn(
+            f"the formatter command exited before reading all content from {file_path}"
         )
 
-    if format_content.wait() != 0:
-        raise Exception("formatter exited with non-zero status")
+    if get_content.returncode != 0 and get_content.returncode != -signal.SIGPIPE:
+        if verbose:
+            info_stderr(
+                f"non-zero exit status from `git cat-file -p {object_hash}`\n"
+                + f"exit status: {get_content.returncode}\n"
+                + f"file path: {file_path}\n"
+            )
+        raise ValueError(
+            f"unable to read file content for {file_path} from object database."
+        )
 
     if write_object.returncode != 0:
+        if verbose:
+            info_stderr(
+                f"non-zero exit status from `git hash-object -w --stdin`\n"
+                + f"exit status: {write_object.returncode}\n"
+                + f"file path: {file_path}\n"
+            )
         raise Exception("unable to write formatted content to object database")
 
     return new_hash.decode("utf-8").rstrip()

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "git-format-staged",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Git command to transform staged files according to a command that accepts file content on stdin and produces output on stdout.",
   "scripts": {
     "test": "ava",
+    "prepare": "update-npm-deps-hash || true",
     "prepublishOnly": "sed -i \"s/\\$VERSION/$npm_package_version/\" git-format-staged",
     "semantic-release": "semantic-release"
   },