git_stage_formatter 2.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e24f5f48a24491053f2e2220ce055df6f61c6207a750f5a8ff6098afbde4120a
+  data.tar.gz: 54553233ebdb102c78ab79d8a660c12f8df10647f3cfb65c22397516d8f0b965
+SHA512:
+  metadata.gz: 20911e08c4169554122387169899c2d93f9b0be2ef7d305370c059dba9be6ab88a8553efdbf0fbb74598a31ea62cc7945a04dcb416379fb7abef8f1d677700f4
+  data.tar.gz: d86c46ed60800b49fd8ee4132226e97483a1fb15060d08642984d55fc23096f2d8147ea04a835763d48ef8c25ff1e05d7afd87472f6a8a745039b41872bc0b9c

data/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+npm-debug.log
+yarn-error.log
+
+# Ruby
+.bundle
+Gemfile.lock
+
+# Misc
+.DS_Store

data/.travis.yml

@@ -0,0 +1,28 @@
+language: python
+python:
+  - 3.8
+  - 3.6
+  - 2.7
+
+cache:
+  directories:
+    - ~/.npm
+
+before_install:
+  - nvm install v14
+
+install:
+  - npm install
+
+script:
+  - npm test
+
+jobs:
+  include:
+    - stage: release
+      deploy:
+        provider: script
+        skip_cleanup: true
+        script: "npm run semantic-release"
+        on:
+          all_branches: true

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Gem dependencies specified in git_stage_formatter.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2018 Jesse Hallett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,194 @@
+# git-format-staged
+
+[![Build Status](https://travis-ci.org/hallettj/git-format-staged.svg?branch=master)](https://travis-ci.org/hallettj/git-format-staged)
+
+Consider a project where you want all code formatted consistently. So you use
+a formatting command. (For example I use [prettier-standard][] in my
+Javascript projects.) You want to make sure that everyone working on the
+project runs the formatter, so you use a tool like [husky][] to install a git
+pre-commit hook. The naive way to write that hook would be to:
+
+- get a list of staged files
+- run the formatter on those files
+- run `git add` to stage the results of formatting
+
+The problem with that solution is it forces you to commit entire files. At
+worst this will lead to contributors to unwittingly committing changes. At
+best it disrupts workflow for contributors who use `git add -p`.
+
+git-format-staged tackles this problem by running the formatter on the staged
+version of the file. Staging changes to a file actually produces a new file
+that exists in the git object database. git-format-staged uses some git
+plumbing commands to send content from that file to your formatter. The command
+replaces file content in the git index. The process bypasses the working tree,
+so any unstaged changes are ignored by the formatter, and remain unstaged.
+
+After formatting a staged file git-format-staged computes a patch which it
+attempts to apply to the working tree file to keep the working tree in sync
+with staged changes. If patching fails you will see a warning message. The
+version of the file that is committed will be formatted properly - the warning
+just means that working tree copy of the file has been left unformatted. The
+patch step can be disabled with the `--no-update-working-tree` option.
+
+[prettier-standard]: https://www.npmjs.com/package/prettier-standard
+[husky]: https://www.npmjs.com/package/husky
+
+
+## How to install
+
+Requires Python version 3 or 2.7.
+
+Install as a development dependency in a project that uses npm packages:
+
+    $ npm install --save-dev git-format-staged
+
+Or install globally:
+
+    $ npm install --global git-format-staged
+
+If you do not use npm you can copy the
+[`git-format-staged`](./git-format-staged) script from this repository and
+place it in your executable path. The script is MIT-licensed - so you can check
+the script into version control in your own open source project if you wish.
+
+
+## How to use
+
+For detailed information run:
+
+    $ git-format-staged --help
+
+The command expects a shell command to run a formatter, and one or more file
+patterns to identify which files should be formatted. For example:
+
+    $ git-format-staged --formatter 'prettier --stdin --stdin-filepath "{}"' 'src/*.js'
+
+That will format all files under `src/` and its subdirectories using
+`prettier`. The file pattern is tested against staged files using Python's
+[`fnmatch`][] function: each `*` will match nested directories in addition to
+file names.
+
+[`fnmatch`]: https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch
+
+The formatter command must read file content from `stdin`, and output formatted
+content to `stdout`.
+
+Files can be excluded by prefixing a pattern with `!`. For example:
+
+    $ git-format-staged --formatter 'prettier --stdin' '*.js' '!flow-typed/*'
+
+Patterns are evaluated from left-to-right: if a file matches multiple patterns
+the right-most pattern determines whether the file is included or excluded.
+
+git-format-staged never operates on files that are excluded from version
+control. So it is not necessary to explicitly exclude stuff like
+`node_modules/`.
+
+The formatter command may include a placeholder, `{}`, which will be replaced
+with the path of the file that is being formatted. This is useful if your
+formatter needs to know the file extension to determine how to format or to
+lint each file. For example:
+
+    $ git-format-staged -f 'prettier --stdin --stdin-filepath "{}"' '*.js' '*.css'
+
+Do not attempt to read or write to `{}` in your formatter command! The
+placeholder exists only for referencing the file name and path.
+
+### Check staged changes with a linter without formatting
+
+Perhaps you do not want to reformat files automatically; but you do want to
+prevent files from being committed if they do not conform to style rules. You
+can use git-format-staged with the `--no-write` option, and supply a lint
+command instead of a format command. Here is an example using ESLint:
+
+    $ git-format-staged --no-write -f 'eslint --stdin --stdin-filename "{}" >&2' 'src/*.js'
+
+If this command is run in a pre-commit hook, and the lint command fails the
+commit will be aborted and error messages will be displayed. The lint command
+must read file content via `stdin`. Anything that the lint command outputs to
+`stdout` will be ignored. In the example above `eslint` is given the `--stdin`
+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
+
+Follow these steps to automatically format all Javascript files on commit in
+a project that uses npm.
+
+Install git-format-staged, husky, and a formatter (I use prettier-standard):
+
+    $ npm install --save-dev git-format-staged husky prettier-standard
+
+Add a `"precommit"` script in `package.json`:
+
+    "scripts": {
+      "precommit": "git-format-staged -f prettier-standard '*.js'"
+    }
+
+Once again note that the `'*.js'` pattern is quoted! If the formatter command
+included arguments it would also need to be quoted.
+
+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`.
+
+
+## Comparisons to similar utilities
+
+There are other tools that will format or lint staged files. What distinguishes
+git-format-staged is that when a file has both staged and unstaged changes
+git-format-staged ignores the unstaged changes; and it leaves unstaged changes
+unstaged when applying formatting.
+
+Some linters (such as [precise-commits][]) have an option to restrict linting
+to certain lines or character ranges in files, which is one way to ignore
+unstaged changes while linting. The author is not aware of a utility other than
+git-format-staged that can apply any arbitrary linter so that it ignores
+unstaged changes.
+
+Some other formatting utilities (such as [pre-commit][])
+use a different strategy to keep unstaged changes unstaged:
+
+1. stash unstaged changes
+2. apply the formatter to working tree files
+3. stage any resulting changes
+4. reapply stashed changes to the working tree.
+
+The problem is that you may get a conflict where stashed changes cannot be
+automatically merged after formatting has been applied. In those cases the user
+has to do some manual fixing to retrieve unstaged changes. As far as the author
+is aware git-format-staged is the only utility that applies a formatter without
+touching working tree files, and then merges formatting changes to the working
+tree. The advantage of merging formatting changes into unstaged changes (as
+opposed to merging unstaged changes into formatting changes) is that
+git-format-staged is non-lossy: if there are conflicts between unstaged changes
+and formatting the unstaged changes win, and are kept in the working tree,
+while staged/committed files are formatted properly.
+
+Another advantage of git-format-staged is that it has no dependencies beyond
+Python and git, and can be dropped into any programming language ecosystem.
+
+Some more comparisons:
+
+- [lint-staged][] lints and formats staged files. At the time of this writing
+  it does not have an official strategy for ignoring unstaged changes when
+  linting, or for keeping unstaged changes unstaged when formatting. But
+  lint-staged does provide powerful configuration options around which files
+  should be linted or formatted, what should happen before and after linting,
+  and so on.
+- [pretty-quick][] formats staged files with prettier. By default pretty-quick
+  will abort the commit if files are partially staged to allow the user to
+  decide how to re-stage changes from formatting. The result is more manual
+  effort compared to git-format-staged.
+- the one-liner
+  `git diff --diff-filter=d --cached | grep '^[+-]' | grep -Ev '^(--- a/|\+\+\+ b/)' | LINT_COMMAND`
+  (described [here][lint changed hunks]) extracts changed hunks and feeds them
+  to a linter. But linting will fail if the linter requires the entire file for
+  context. For example a linter might report errors if it cannot see import
+  lines.
+
+[precise-commits]: https://github.com/nrwl/precise-commits
+[pre-commit]: https://pre-commit.com/#pre-commit-during-commits
+[pretty-quick]: https://www.npmjs.com/package/pretty-quick
+[lint-staged]: https://github.com/okonet/lint-staged
+[lint changed hunks]: https://github.com/okonet/lint-staged/issues/62#issuecomment-383217916

data/bin/git_stage_formatter

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "git_stage_formatter"
+
+GitStageFormatter.run(ARGV)

data/commitlint.config.js

@@ -0,0 +1,5 @@
+'use strict'
+
+module.exports = {
+  extends: ['@commitlint/config-conventional']
+}

data/git-format-staged

@@ -0,0 +1,267 @@
+#!/usr/bin/env python
+#
+# Git command to transform staged files according to a command that accepts file
+# content on stdin and produces output on stdout. This command is useful in
+# combination with `git add -p` which allows you to stage specific changes in
+# a file. This command runs a formatter on the file with staged changes while
+# ignoring unstaged changes.
+#
+# Usage: git-format-staged [OPTION]... [FILE]...
+# Example: git-format-staged --formatter 'prettier --stdin' '*.js'
+#
+# Tested with Python 3.6 and Python 2.7.
+#
+# Original author: Jesse Hallett <jesse@sitr.us>
+
+from __future__ import print_function
+import argparse
+from fnmatch import fnmatch
+from gettext import gettext as _
+import os
+import re
+import subprocess
+import sys
+
+# The string $VERSION is replaced during the publish process.
+VERSION = '$VERSION'
+PROG = sys.argv[0]
+
+def info(msg):
+    print(msg, file=sys.stderr)
+
+def warn(msg):
+    print('{}: warning: {}'.format(PROG, msg), file=sys.stderr)
+
+def fatal(msg):
+    print('{}: error: {}'.format(PROG, msg), file=sys.stderr)
+    exit(1)
+
+def format_staged_files(file_patterns, formatter, git_root, update_working_tree=True, write=True):
+    try:
+        output = subprocess.check_output([
+            'git', 'diff-index',
+            '--cached',
+            '--diff-filter=AM', # select only file additions and modifications
+            '--no-renames',
+            'HEAD'
+            ])
+        for line in output.splitlines():
+            entry = parse_diff(line.decode('utf-8'))
+            entry_path = normalize_path(entry['src_path'], relative_to=git_root)
+            if not (matches_some_path(file_patterns, entry_path)):
+                continue
+            if format_file_in_index(formatter, entry, update_working_tree=update_working_tree, write=write):
+                info('Reformatted {} with {}'.format(entry['src_path'], formatter))
+    except Exception as err:
+        fatal(str(err))
+
+# Run formatter on file in the git index. Creates a new git object with the
+# result, and replaces the content of the file in the index with that object.
+# Returns hash of the new object if formatting produced any changes.
+def format_file_in_index(formatter, diff_entry, update_working_tree=True, write=True):
+    orig_hash = diff_entry['dst_hash']
+    new_hash = format_object(formatter, orig_hash, diff_entry['src_path'])
+
+    # If the new hash is the same then the formatter did not make any changes.
+    if not write or new_hash == orig_hash:
+        return None
+
+    # If the content of the new object is empty then the formatter did not
+    # produce any output. We want to abort instead of replacing the file with an
+    # empty one.
+    if object_is_empty(new_hash):
+        return None
+
+    replace_file_in_index(diff_entry, new_hash)
+
+    if update_working_tree:
+        try:
+            patch_working_file(diff_entry['src_path'], orig_hash, new_hash)
+        except Exception as err:
+            # Errors patching working tree files are not fatal
+            warn(str(err))
+
+    return new_hash
+
+file_path_placeholder = re.compile('\{\}')
+
+# Run formatter on a git blob identified by its hash. Writes output to a new git
+# blob, and returns the hash of the new blob.
+def format_object(formatter, object_hash, file_path):
+    get_content = subprocess.Popen(
+            ['git', 'cat-file', '-p', object_hash],
+            stdout=subprocess.PIPE
+            )
+    format_content = subprocess.Popen(
+            re.sub(file_path_placeholder, file_path, formatter),
+            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
+            )
+
+    get_content.stdout.close()
+    format_content.stdout.close()
+
+    if get_content.wait() != 0:
+        raise ValueError('unable to read file content from object database: ' + object_hash)
+
+    if format_content.wait() != 0:
+        raise Exception('formatter exited with non-zero status') # TODO: capture stderr from format command
+
+    new_hash, err = write_object.communicate()
+
+    if write_object.returncode != 0:
+        raise Exception('unable to write formatted content to object database')
+
+    return new_hash.decode('utf-8').rstrip()
+
+def object_is_empty(object_hash):
+    get_content = subprocess.Popen(
+            ['git', 'cat-file', '-p', object_hash],
+            stdout=subprocess.PIPE
+        )
+    content, err = get_content.communicate()
+
+    if get_content.returncode != 0:
+        raise Exception('unable to verify content of formatted object')
+
+    return not content
+
+def replace_file_in_index(diff_entry, new_object_hash):
+    subprocess.check_call(['git', 'update-index',
+        '--cacheinfo', '{},{},{}'.format(
+            diff_entry['dst_mode'],
+            new_object_hash,
+            diff_entry['src_path']
+            )])
+
+def patch_working_file(path, orig_object_hash, new_object_hash):
+    patch = subprocess.check_output(
+            ['git', 'diff', orig_object_hash, new_object_hash]
+            )
+
+    # Substitute object hashes in patch header with path to working tree file
+    patch_b = patch.replace(orig_object_hash.encode(), path.encode()).replace(new_object_hash.encode(), path.encode())
+
+    apply_patch = subprocess.Popen(
+            ['git', 'apply', '-'],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE
+            )
+
+    output, err = apply_patch.communicate(input=patch_b)
+
+    if apply_patch.returncode != 0:
+        raise Exception('could not apply formatting changes to working tree file {}'.format(path))
+
+# Format: src_mode dst_mode src_hash dst_hash status/score? src_path dst_path?
+diff_pat = re.compile('^:(\d+) (\d+) ([a-f0-9]+) ([a-f0-9]+) ([A-Z])(\d+)?\t([^\t]+)(?:\t([^\t]+))?$')
+
+# Parse output from `git diff-index`
+def parse_diff(diff):
+    m = diff_pat.match(diff)
+    if not m:
+        raise ValueError('Failed to parse diff-index line: ' + diff)
+    return {
+            'src_mode': unless_zeroed(m.group(1)),
+            'dst_mode': unless_zeroed(m.group(2)),
+            'src_hash': unless_zeroed(m.group(3)),
+            'dst_hash': unless_zeroed(m.group(4)),
+            'status': m.group(5),
+            'score': int(m.group(6)) if m.group(6) else None,
+            'src_path': m.group(7),
+            'dst_path': m.group(8)
+            }
+
+zeroed_pat = re.compile('^0+$')
+
+# Returns the argument unless the argument is a string of zeroes, in which case
+# returns `None`
+def unless_zeroed(s):
+    return s if not zeroed_pat.match(s) else None
+
+def get_git_root():
+    return subprocess.check_output(
+            ['git', 'rev-parse', '--show-toplevel']
+            ).decode('utf-8').rstrip()
+
+def normalize_path(p, relative_to=None):
+    return os.path.abspath(
+            os.path.join(relative_to, p) if relative_to else p
+            )
+
+def matches_some_path(patterns, target):
+    is_match = False
+    for signed_pattern in patterns:
+        (is_pattern_positive, pattern) = from_signed_pattern(signed_pattern)
+        if fnmatch(target, normalize_path(pattern)):
+            is_match = is_pattern_positive
+    return is_match
+
+# Checks for a '!' as the first character of a pattern, returns the rest of the
+# pattern in a tuple. The tuple takes the form (is_pattern_positive, pattern).
+# For example:
+#     from_signed_pattern('!pat') == (False, 'pat')
+#     from_signed_pattern('pat') == (True, 'pat')
+def from_signed_pattern(pattern):
+    if pattern[0] == '!':
+        return (False, pattern[1:])
+    else:
+        return (True, pattern)
+
+class CustomArgumentParser(argparse.ArgumentParser):
+    def parse_args(self, args=None, namespace=None):
+        args, argv = self.parse_known_args(args, namespace)
+        if argv:
+            msg = argparse._(
+                    'unrecognized arguments: %s. Do you need to quote your formatter command?'
+                    )
+            self.error(msg % ' '.join(argv))
+        return args
+
+if __name__ == '__main__':
+    parser = CustomArgumentParser(
+            description='Transform staged files using a formatting command that accepts content via stdin and produces a result via stdout.',
+            epilog='Example: %(prog)s --formatter "prettier --stdin" "src/*.js" "test/*.js"'
+            )
+    parser.add_argument(
+            '--formatter', '-f',
+            required=True,
+            help='Shell command to format files, will run once per file. Occurrences of the placeholder `{}` will be replaced with a path to the file being formatted. (Example: "prettier --stdin --stdin-filepath \'{}\'")'
+            )
+    parser.add_argument(
+            '--no-update-working-tree',
+            action='store_true',
+            help='By default formatting changes made to staged file content will also be applied to working tree files via a patch. This option disables that behavior, leaving working tree files untouched.'
+            )
+    parser.add_argument(
+            '--no-write',
+            action='store_true',
+            help='Prevents %(prog)s from modifying staged or working tree files. You can use this option to check staged changes with a linter instead of formatting. With this option stdout from the formatter command is ignored. Example: %(prog)s --no-write -f "eslint --stdin --stdin-filename \'{}\' >&2" "*.js"'
+            )
+    parser.add_argument(
+            '--version',
+            action='version',
+            version='%(prog)s version {}'.format(VERSION),
+            help='Display version of %(prog)s'
+            )
+    parser.add_argument(
+            'files',
+            nargs='+',
+            help='Patterns that specify files to format. The formatter will only transform staged files that are given here. Patterns may be literal file paths, or globs which will be tested against staged file paths using Python\'s fnmatch function. For example "src/*.js" will match all files with a .js extension in src/ and its subdirectories. Patterns may be negated to exclude files using a "!" character. Patterns are evaluated left-to-right. (Example: "main.js" "src/*.js" "test/*.js" "!test/todo/*")'
+            )
+    args = parser.parse_args()
+    files = vars(args)['files']
+    format_staged_files(
+            file_patterns=files,
+            formatter=vars(args)['formatter'],
+            git_root=get_git_root(),
+            update_working_tree=not vars(args)['no_update_working_tree'],
+            write=not vars(args)['no_write']
+            )