skip git hook dummy files; update examples; clarify documentation

README.md

@@ -11,60 +11,33 @@ Believe it or not, shell scripts are notoriously difficult to write well, so it
 The stank system includes the stank Go library as well as several command line utilities for convenience. The `stank` application scans directories and files for POSIX-derived shell scripts and prints their paths, designed as a convenient standalone filter for linting large collections of source code. For example, use `stank` in combination with `xargs` to help per-file shell linters process large projects.
 
 ```console
-$ stank examples
-examples/.profile
-examples/.zshrc
-examples/badconfigs/.bash_profile
-examples/badconfigs/zprofile
-examples/blank.bash
-examples/derp.zsh
-examples/globs.bash
-examples/goodbye.sh
-examples/greetings.bash
-examples/hello
-examples/hello.sh
-examples/hooks/post-update
-examples/hooks/pre-applypatch
-examples/hooks/pre-commit
-examples/hooks/pre-push
-examples/hooks/pre-rebase
-examples/hooks/update
-examples/howdy
-examples/howdy.zsh
-examples/i-should-have-an-extension
-examples/just-eol.bash
-examples/just-shebang.bash
-examples/pipefail
-examples/salutations.bash
-examples/salutations.sh
-examples/salutations4.bash
-examples/sample.envrc
-examples/wednesday
-examples/welcome
-examples/welcome.sh
-
-$ stank examples/hooks | xargs shellcheck
-
-In examples/hooks/pre-applypatch line 11:
-. git-sh-setup
-  ^----------^ SC1091 (info): Not following: git-sh-setup was not specified as input (see shellcheck -x).
-
-
-In examples/hooks/pre-commit line 31:
-	test $(git diff --cached --name-only --diff-filter=A -z $against |
-             ^-- SC2046 (warning): Quote this to prevent word splitting.
-
-$ stank -help
-  -alt
-        Limit results to specifically alternative, non-POSIX lowlevel shell scripts
-  -help
-        Show usage information
-  -sh
-        Limit results to specifically bare POSIX sh scripts
-  -version
-        Show version information
+$ cd examples
+
+$ stank .
+.profile
+.shrc
+.zlogin
+...
 ```
 
+The `stank` command line utility searches file paths for shell scripts that may warrant linting.
+
+```console
+$ stank . | xargs -n 1 shellcheck
+In welcome.sh line 1:
+#!bash
+^----^ SC2239 (error): Ensure the shebang uses an absolute path to the interpreter.
+
+For more information:
+  https://www.shellcheck.net/wiki/SC2239 -- Ensure the shebang uses an absolu...
+```
+
+Take care when file paths may contain spaces, however.
+
+Machine-generated files, including git hook default `*.sample` files, are automatically skipped.
+
+See `stank -help` for additional options.
+
 # DOWNLOADS
 
 https://github.com/mcandre/stank/releases
@@ -259,6 +232,11 @@ BSD-2-Clause
 
 (None)
 
+## Recommended
+
+* GNU or BSD [findutils](https://en.wikipedia.org/wiki/Find_(Unix))
+* [jq](https://jqlang.github.io/jq/)
+
 # CONTRIBUTING
 
 For more details on developing stank itself, see [DEVELOPMENT.md](DEVELOPMENT.md).

cmd/funk/main.go

@@ -513,6 +513,10 @@ func (o *Funk) Walk(pth string, info os.FileInfo, err error) error {
 		fmt.Printf("%v\n", err)
 	}
 
+	if smell.MachineGenerated {
+		return nil
+	}
+
 	if (smell.POSIXy || smell.AltShellScript) && o.FunkyCheck(smell) {
 		o.FoundOdor = true
 	}

cmd/rosy/main.go

@@ -121,6 +121,10 @@ func (o *Rose) Walk(pth string, info os.FileInfo, err error) error {
 		log.Print(err)
 	}
 
+	if smell.MachineGenerated {
+		return nil
+	}
+
 	if (smell.POSIXy || smell.AltShellScript) &&
 		!(stank.LOWEREXTENSIONS2CONFIG[strings.ToLower(smell.Extension)] || stank.LOWERFILENAMES2CONFIG[strings.ToLower(smell.Filename)]) &&
 		!CheckShebang(smell) {

cmd/stank/main.go

@@ -51,6 +51,10 @@ func (o Stanker) Walk(pth string, info os.FileInfo, err error) error {
 		log.Print(err)
 	}
 
+	if smell.MachineGenerated {
+		return nil
+	}
+
 	for _, interpreterExclusion := range o.InterpreterExclusions {
 		if smell.Interpreter == interpreterExclusion {
 			return nil

examples/hooks/applypatch-msg.sample

@@ -0,0 +1,15 @@
+#!/bin/sh
+#
+# An example hook script to check the commit log message taken by
+# applypatch from an e-mail message.
+#
+# The hook should exit with non-zero status after issuing an
+# appropriate message if it wants to stop the commit.  The hook is
+# allowed to edit the commit message file.
+#
+# To enable this hook, rename this file to "applypatch-msg".
+
+. git-sh-setup
+commitmsg="$(git rev-parse --git-path hooks/commit-msg)"
+test -x "$commitmsg" && exec "$commitmsg" ${1+"$@"}
+:

examples/hooks/commit-msg.sample

@@ -0,0 +1,24 @@
+#!/bin/sh
+#
+# An example hook script to check the commit log message.
+# Called by "git commit" with one argument, the name of the file
+# that has the commit message.  The hook should exit with non-zero
+# status after issuing an appropriate message if it wants to stop the
+# commit.  The hook is allowed to edit the commit message file.
+#
+# To enable this hook, rename this file to "commit-msg".
+
+# Uncomment the below to add a Signed-off-by line to the message.
+# Doing this in a hook is a bad idea in general, but the prepare-commit-msg
+# hook is more suited to it.
+#
+# SOB=$(git var GIT_AUTHOR_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
+# grep -qs "^$SOB" "$1" || echo "$SOB" >> "$1"
+
+# This example catches duplicate Signed-off-by lines.
+
+test "" = "$(grep '^Signed-off-by: ' "$1" |
+	 sort | uniq -c | sed -e '/^[ 	]*1[ 	]/d')" || {
+	echo >&2 Duplicate Signed-off-by lines.
+	exit 1
+}

examples/hooks/fsmonitor-watchman.sample

@@ -0,0 +1,174 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+use IPC::Open2;
+
+# An example hook script to integrate Watchman
+# (https://facebook.github.io/watchman/) with git to speed up detecting
+# new and modified files.
+#
+# The hook is passed a version (currently 2) and last update token
+# formatted as a string and outputs to stdout a new update token and
+# all files that have been modified since the update token. Paths must
+# be relative to the root of the working tree and separated by a single NUL.
+#
+# To enable this hook, rename this file to "query-watchman" and set
+# 'git config core.fsmonitor .git/hooks/query-watchman'
+#
+my ($version, $last_update_token) = @ARGV;
+
+# Uncomment for debugging
+# print STDERR "$0 $version $last_update_token\n";
+
+# Check the hook interface version
+if ($version ne 2) {
+	die "Unsupported query-fsmonitor hook version '$version'.\n" .
+	    "Falling back to scanning...\n";
+}
+
+my $git_work_tree = get_working_dir();
+
+my $retry = 1;
+
+my $json_pkg;
+eval {
+	require JSON::XS;
+	$json_pkg = "JSON::XS";
+	1;
+} or do {
+	require JSON::PP;
+	$json_pkg = "JSON::PP";
+};
+
+launch_watchman();
+
+sub launch_watchman {
+	my $o = watchman_query();
+	if (is_work_tree_watched($o)) {
+		output_result($o->{clock}, @{$o->{files}});
+	}
+}
+
+sub output_result {
+	my ($clockid, @files) = @_;
+
+	# Uncomment for debugging watchman output
+	# open (my $fh, ">", ".git/watchman-output.out");
+	# binmode $fh, ":utf8";
+	# print $fh "$clockid\n@files\n";
+	# close $fh;
+
+	binmode STDOUT, ":utf8";
+	print $clockid;
+	print "\0";
+	local $, = "\0";
+	print @files;
+}
+
+sub watchman_clock {
+	my $response = qx/watchman clock "$git_work_tree"/;
+	die "Failed to get clock id on '$git_work_tree'.\n" .
+		"Falling back to scanning...\n" if $? != 0;
+
+	return $json_pkg->new->utf8->decode($response);
+}
+
+sub watchman_query {
+	my $pid = open2(\*CHLD_OUT, \*CHLD_IN, 'watchman -j --no-pretty')
+	or die "open2() failed: $!\n" .
+	"Falling back to scanning...\n";
+
+	# In the query expression below we're asking for names of files that
+	# changed since $last_update_token but not from the .git folder.
+	#
+	# To accomplish this, we're using the "since" generator to use the
+	# recency index to select candidate nodes and "fields" to limit the
+	# output to file names only. Then we're using the "expression" term to
+	# further constrain the results.
+	my $last_update_line = "";
+	if (substr($last_update_token, 0, 1) eq "c") {
+		$last_update_token = "\"$last_update_token\"";
+		$last_update_line = qq[\n"since": $last_update_token,];
+	}
+	my $query = <<"	END";
+		["query", "$git_work_tree", {$last_update_line
+			"fields": ["name"],
+			"expression": ["not", ["dirname", ".git"]]
+		}]
+	END
+
+	# Uncomment for debugging the watchman query
+	# open (my $fh, ">", ".git/watchman-query.json");
+	# print $fh $query;
+	# close $fh;
+
+	print CHLD_IN $query;
+	close CHLD_IN;
+	my $response = do {local $/; <CHLD_OUT>};
+
+	# Uncomment for debugging the watch response
+	# open ($fh, ">", ".git/watchman-response.json");
+	# print $fh $response;
+	# close $fh;
+
+	die "Watchman: command returned no output.\n" .
+	"Falling back to scanning...\n" if $response eq "";
+	die "Watchman: command returned invalid output: $response\n" .
+	"Falling back to scanning...\n" unless $response =~ /^\{/;
+
+	return $json_pkg->new->utf8->decode($response);
+}
+
+sub is_work_tree_watched {
+	my ($output) = @_;
+	my $error = $output->{error};
+	if ($retry > 0 and $error and $error =~ m/unable to resolve root .* directory (.*) is not watched/) {
+		$retry--;
+		my $response = qx/watchman watch "$git_work_tree"/;
+		die "Failed to make watchman watch '$git_work_tree'.\n" .
+		    "Falling back to scanning...\n" if $? != 0;
+		$output = $json_pkg->new->utf8->decode($response);
+		$error = $output->{error};
+		die "Watchman: $error.\n" .
+		"Falling back to scanning...\n" if $error;
+
+		# Uncomment for debugging watchman output
+		# open (my $fh, ">", ".git/watchman-output.out");
+		# close $fh;
+
+		# Watchman will always return all files on the first query so
+		# return the fast "everything is dirty" flag to git and do the
+		# Watchman query just to get it over with now so we won't pay
+		# the cost in git to look up each individual file.
+		my $o = watchman_clock();
+		$error = $output->{error};
+
+		die "Watchman: $error.\n" .
+		"Falling back to scanning...\n" if $error;
+
+		output_result($o->{clock}, ("/"));
+		$last_update_token = $o->{clock};
+
+		eval { launch_watchman() };
+		return 0;
+	}
+
+	die "Watchman: $error.\n" .
+	"Falling back to scanning...\n" if $error;
+
+	return 1;
+}
+
+sub get_working_dir {
+	my $working_dir;
+	if ($^O =~ 'msys' || $^O =~ 'cygwin') {
+		$working_dir = Win32::GetCwd();
+		$working_dir =~ tr/\\/\//;
+	} else {
+		require Cwd;
+		$working_dir = Cwd::cwd();
+	}
+
+	return $working_dir;
+}