swellaby/rusty-hook

git hook manager, geared toward Rust projects

rusty-hook

Git hook utility for Rust codebases that lets you run any script for any git hook.

Functional, but still in Beta!

Quick Start

Pre-requisites: Make sure you have Rust installed and that Cargo's bin directory is on your PATH. https://www.rust-lang.org/tools/install

1. Add rusty-hook as a dev dependency in your Cargo.toml file
2. Run cargo test (to build your dev dependencies, including rusty-hook)
3. Update the generated .rusty-hook.toml file with the commands you want to run
4. Run git commit (or equivalent to trigger your git hook)!
   • You may also want to have your hook script fail (for example add a failing test if your commit hook is cargo test) to see the hooks be enforced.
   • note the very first (and only) time you do this will take an extra ~30 seconds or so to finalize the setup

Setup

Just add rusty-hook as a dev dependency in your Cargo.toml file:

[dev-dependencies]
rusty-hook = "^0.11.2"

Initialize

When you add rusty-hook as a dev-dependency in your project, it will automatically configure the git hooks once it is built (for example the first time you run cargo test).

This will ensure that all of the client side git hooks are setup and available, and it will create a rusty-hook configuration file if one does not already exist.

The git hook script will ensure that the rusty-hook cli is available, so the very first time a git hook is triggered on your machine you will see a message indicating that the rusty-hook setup is being finalized which may take ~30 seconds or so:

Finalizing rusty-hook configuration...
This may take a few seconds...

(Optional) Install

You can also install the rusty-hook cli with cargo:

cargo install rusty-hook

You can optionally manually initialize any git directory by running the init command in any git directory to set it up:

rusty-hook init

Configure

You define your desired git hook configuration in the rusty-hook configuration file (a TOML file named .rusty-hook.toml or rusty-hook.toml).

Here's an example rusty-hook configuration that leverages multiple git hooks, including the pre-commit and the pre-push hooks:

[hooks]
pre-commit = "cargo test"
pre-push = ["cargo check", "cargo fmt -- --check"]
post-commit = "echo yay"

[logging]
verbose = true

Hooks

Under the [hooks] table, you can add an entry for any and every git hook you want to run by adding a key using the name of the git hook, and then specify the command/script you want to run for that hook. Multiple commands in a form of a toml array or via command chaining using && are also allowed (Only for versions 0.12 and up). Whenever that git hook is triggered, rusty-hook will run your specified command!

Using git arguments

In git hook commands, any instance of %rh! will be replaced by the arguments that git passes to this hook.

[hooks]
pre-push = "echo %rh!"

Logging

Under the [logging] table, you can control whether to log the output of running your specified hook commands. By default rusty-hook will log the results of your hook script, but you can disable this behavior by setting the verbose key to false:

[logging]
verbose = false

Alternatives

There's a few other git hook utilities available on crates.io, but none of them quite suited our needs so we made rusty-hook!

• cargo-husky
• shiba
• git_hooks

Contributions

All contributions are welcome and appreciated! Check out our Contributing Guidelines for more information about opening issues, developing, and more.

Changelog

See CHANGELOG.md

Removing rusty-hook

We'll be sad to see you go, but here's what to do if you'd like to remove rusty-hook from your project.

1. Remove the rusty-hook dev dependency from the Cargo.toml file in your project.
2. Remove the .rusty-hook.toml configuration file from your project.
3. Remove the git hook scripts that were placed in the git hooks directory in your local project workspace (this is typically in the .git/hooks/ directory). Note that if you were using rusty-hook version 0.9.1 or newer and you skip this step, then the git hooks will still be invoked as part of your git workflow and you will see the following warning message on git commit:

rusty-hook git hooks are configured, but no config file was found
In order to use rusty-hook, your project must have a config file
See https://github.com/swellaby/rusty-hook#configure for more information about configuring rusty-hook

If you were trying to remove rusty-hook, then you should also delete the git hook files to remove this warning
See https://github.com/swellaby/rusty-hook#removing-rusty-hook for more information about removing rusty-hook from your project

Please also consider opening an issue to report any bugs/problems you experienced, missing features, etc. so that we can work on improving rusty-hook!

rusty-hook's Issues

Add PR builds for rustfmt and clippy

Update tarpaulin usage

A new --output-dir option has been added to tarpaulin, so let's incorporate that into the pipeline that is generating code coverage

Print hook and cli version

Description

Would be nice to print both the hook file version and perhaps the rusty-hook cli version on hook execution, in a follow up we can add an option to allow this to be disabled via the verbose config setting

Value

A user can see their current rusty-hook version via cli command (i.e. rusty-hook -v) but there's no way to see the version of the hook files outside of manually looking inside the underlying file within the .hooks directory

Automatic hook set up

Description

Provide the ability for rusty-hook to automatically configure git hooks, perhaps via a build script

Value

Provides an easy option to have hooks automatically added on the first cargo fetch or test command

Add removal and hook file info to docs

We need to update the documentation to cover a few points:

1. Clearly convey that rusty-hook creates hook scripts in the .git/hooks directory
2. Enumerate the required steps to remove rusty-hook

Currently it can be confusing/painful for folks that want to remove rusty-hook from a project, especially if they were using the auto-install mode which makes rusty-hook a bit stickier than folks would expect. This can lead to a rather annoying and frustrating experience.

Prep and publish v0.10.3 release

Switch to tarpaulin for coverage

Up to this point cargo kcov has served us fairly well, but it's been causing some problems of late that aren't terribly surprising considerking that kcov's primarily focused on C/C++ code. We've notably had incorrect coverage reports on things like functions w/implicit expression returns and it's convinced me it is time to switch.

I've already done some local and CI testing with tarpaulin and confirmed it's working well (including the cases kcov was having challenges with) and believe that's the way to go.

Add dev setup scripts

Setup PR Validation Builds

Externalize hook script(s) in source with include_str! macro

The git hook script is currently defined inline in a Rust file, but it would be a bit easier to view/manage/etc. if we extract it into a separate .sh file and use include_str!(...) to pull the contents in at compile time. Plus this would also let us run tools like ShellCheck against the scripts

https://doc.rust-lang.org/std/macro.include_str.html

Expand setup documentation to cover both usage modes

This isn't obvious from the current docs, but users of rusty-hook have two ways of leveraging it in their projects.

1. more automatic/forced way - add it as a dev dependency, and then any dev/contributor on your repo will get the hooks set up automagically
2. more optional/opt-in way - instead of adding it as a dev dep, users could suggest/encourage devs/contributors to manually install (cargo install rusty-hook) and then run the rusty-hook init command if the dev/contributor wanted to set up local git hooks in his or her environment.

We certainly prefer to use option 1 in our personal repos, but given that rusty-hook gives flexibility/choice to the consumers, it's important for the docs to clearly convey those options so folks can choose the option that works best for them and their projects

Skip setup in CI

Description

Skip the on-build hook setup when a CI environment is detected.

Value

We're currently checking to see if we're in a CI environment on hook execution, as we typically don't want to enforce git hooks in that context. This same notion applies to setup too: there's no need to create hooks and do the cli install of rusty-hook during the build/test process for applications using rusty-hook as a dev dependency

Add docs for devs on setting up local code coverage

Description

Add setup scripts, doc updates, etc. for code coverage

Value

Code coverage is an important part of the inner dev-loop process, and the PR validation checks enforce code coverage thresholds.

Accordingly, a developer working on this project needs to be able to generate code coverage info in his/her local env, and we should provide the relevant artifacts for them to be able to do so.

Exec permission not set on hook files

Environment Details

• Operating System
  • Linux
  • Mac
  • Windows
• Rust Version: n/a
• Rust Release Channel
  • Stable
  • Nightly
  • Beta
• Cargo Version: n/a
• rusty-hook Version: n/a

Description

The executable permission is not being set on the files created in the .hooks directory on unix systems

Add executable permission on dev setup scripts

Description

Add executable permission to shell scripts in the repo

Value

Allows for the scripts to be run after cloning without having to manually chmod +x

Thanks for the suggestion @beverts312 😉

Setup Dependabot

I'm still a big fan of Renovate, and even though they support Rust/Cargo, we should set up Dependabot for rusty-hook.

The biggest reason is that in addition to the core dependency management, Dependabot will also create PRs for dependencies with known security issues flagged in RustSec

Publish v0.10.1

There's an updated version of the ci_info dependency we use

Feature Request - stream git hook output

Description

I run cargo make ci-flow as part of git pre push.
that script runs many tasks and takes a bit to finish.
it would be nice to see where it is in the execution, so if you would stream the githook script output in realtime instead of buffering it into memory and flushing only at the end, it would be really help and will improve the usability.

Value

Users for long running hooks won't think it is stuck and would get real time progress.

by the way, this crate is really great.

Support running pre-commit hook against staged files

prep v0.10.2 release

We've a new version of toml that's now being used so we should publish a new version with the updated dependencies

Update PR pipeline configs

There's been some changes in the AZP ecosystem (Rust will be pre-installed on the hosted VMs, version 1.x of the pipeline upload/download tasks released, etc.) that should be applied to the pipeline templates

Setup Release Pipeline

Self explanatory in the title 😄

Auto install rusty-hook

Description

Update the git hook script to auto install rusty-hook if it's not already available, allow this behavior to be disabled via an environment variable.

Value

#28 added support to automatically configure the git hooks on build. However, since cargo does not (yet) support installing dev deps as executables, there's still a need to run a one time cargo install rusty-hook manually. Adding this would truly make rusty-hook fully installable via simple dependency reference 👍

Add remove functionality

Add subcommand for removing hook files

Support user/local configs

Description

Allow for the hook configuration for a project to be augmented/overriden by a local/user configuration

Value

This would provide greater flexibility for individuals when working on a project. A project-level default could be set (using the existing .rusty-hook.toml configuration file), but then users could individually have their own configuration file (perhaps .rusty-hook.local.toml or something like that) if they wanted to run additional/different/etc. hooks in their local environment.

Add command/task runner

I'm leaning towards just for this but still considering cargo-make

Update Windows setup script

The Windows dev_setup script will currently do a force install of the VS vctools in order to support Rust's default MSVC target on Windows, if Rustc is not available.

The vctools install may not always be necessary, so if the script detects Rust has not been installed, it should check the minimum VS2013+ vctools install before attempting to install it.

The vs tools install almost always require a system restart, which means that in the event that the script does need to install the vctools, it cannot continue to the next steps prior to the user restarting.

This setup should be split out into a separate script/sequence to improve the dev experience

Windows PR job not failing on task failures

Seems that even if there's compilation and/or test failures that the Windows PR job will still show as green anyway 🤦‍♂️

Add init functionality

Fix clippy warning

Latest clippy version is (thankfully) flagging some Option usages where we'd be better off using if let Some(...)...

Investigate optimizing git hook scripts

Description

Currently, every single git hook runs the setup checks (does the cli exists, does it meet the minimum required version, etc.). We should investigate optimizing those checks to only run on the "initiating" hook that starts the respective git hook lifecycles

Value

Running those checks on every single hook is inherently duplicative and unnecessary. For example, if the pre-commit hook check validates those items, then there's really no need to re-run the valdiation checks on the post-commit hook; you can't hit the post-commit hook without first hitting the pre-commit hook.

Add GitHub Templates

Add cli version check

Description

Update the the git hook scripts to support upgrading the rusty-hook CLI conditionally, such as when the CLI version is less than X.

High level flow would be something like:

if cliVersion < minimumCliVersion; then 
  cargo install --force rusty-hook
fi

Value

The hook script files will be automatically upgraded, but the CLI is only installed if it doesn't already exist on the system. This could eventually lead to a lot of version drift between the script files and the CLI, and having the ability the conditionally upgrade the CLI version from the scripts would better enable keeping them more closely synchronized and simplifying the development/deployment process.

Add run functionality

Add PR job for shell scripts

Description

Add shellcheck scan to our PR validation process (at least on either the Linux or Mac builds)

Value

We've got some shell scripts used as part of rusty-hook, both for the app and for dev support scripts. it'd be good to run some valdiation on those

Publish v0.9.4

getops dependency was bumped, need to pacakge publish a new 0.9.4 version

Create the tests for the hook script files

Given the crucial role these shell scripts play in the overall functionality, it would be great to include some automated tests that can be used to verify their behavior in our build and release pipelines.

Fix Windows Setup Script

Environment Details

• Operating System
  • Linux
  • Mac
  • Windows
• Rust Version: n/a
• Rust Release Channel
  • Stable
  • Nightly
  • Beta
• Cargo Version: n/a
• rusty-hook Version: n/a

Description

The dev setup script on Windows is not working well, even after the fix attempt in #20/#26.

The detection of the VC build tools is not reliable, and there's issues with certain steps when the script is running behind a proxy

Setup CI Pipeline

Exclude vendored shunit from shellcheck scan

Fix doc typos

Switch to nias for closures

Publish v0.9.3

Publish a new patch version with the update dep versions on toml and ci_info

Different behavior on missing config file

Description

Currently, when the config file is missing, rusty-hook exits with an error code resulting in all the git hooks being blocked/rejected (which prevents a user from being able to commit, or requires them to include the -n or --no-verify flags).

We could update the generated hook script files to handle the "no config file" error scenario differently than other errors so that the git hooks are not rejected.

Value

This would allow for folks to partially remove rusty-hook from their project (only remove config file and dev-dep), but leave the rusty-hook scripts in their hooks directory in such a way that would not cause the git hooks to continue to be failed/rejected.

Still a few things to think through:

1. Should this be the standard/default script behavior, or an init option to let users decide for their own projects?
2. On partial removal, when a config file is missing, should the hooks continue silently or display a warning/message to the user before continuing?

IMO it's not ideal to keep a set of git hook scripts that are triggered on every git hook, running rusty-hook, checking for a config file, and then failing silently. I'd vote that we make this the new default behavior for the "no config file" scenario, and display a warning to the user on the pre-commit hook (not every hook) so that they know they should remove the script files too.

CC @traviskosarek @beverts312

Don’t corrupt ./.git/hooks

Description

If rusty-hooks is removed, it will corrupt your ./.git/hooks because there is no longer a .toml file w/hooks. This results in a cryptic “Failed to locate or parse config file” message after removal

Value

The output of rusty-hook should not rely on the existence of artifacts generated by rusty-hook, if rusty-hook is removed from a project, it should not screw up the project.

Add LLDB/LLVM Setup for debugging

We should include scripts as part of general dev setup to ensure LLDB is available for debugging.

For Linux:
https://lldb.llvm.org/resources/download.html

For Mac:
I believe it's installed by default with XCode, but also available via homebrew https://formulae.brew.sh/formula/llvm

For Windows:
https://chocolatey.org/packages/llvm

Prep and release v0.11.0

Let's publish a minor-bump version that includes the ci_info bump (#95) and the hook streaming output enhancement (#96)

Add Docs

Make git params available as environment variable

Description

rusty-hook should take the git params and expose them as an environment variable

Value

This would make those git params accessible to the downstream tools/scripts that are invoked by rusty-hook

CI: Fix default toolchain on Windows

Apparently the default toolchain on the Windows runners is now 32 bit msvc? 🤔

Will need to update the Windows PR job to account for this and get more explicit about which triple to use