Sharing hooks with the team (husky) in Git - Deep Dive

Overview - Sharing hooks with the team (husky)

What is it?

Sharing hooks with the team using Husky means setting up automatic scripts that run before or after Git actions, like commits or pushes, and making sure everyone on the team uses the same scripts. Husky is a tool that helps manage these scripts easily by storing them in the project, so they work the same way for everyone. This avoids mistakes and keeps code quality high. It works by hooking into Git events and running your scripts automatically.

Why it matters

Without shared hooks, each developer might have different checks or none at all, leading to inconsistent code quality and bugs slipping into the project. Sharing hooks ensures everyone follows the same rules automatically, saving time and avoiding errors. It creates a smoother team workflow and helps catch problems early, improving the overall project health.

Where it fits

Before learning this, you should understand basic Git commands and what Git hooks are. After this, you can explore advanced Git automation, continuous integration (CI) pipelines, and other developer experience tools that improve team collaboration.

Mental Model

Core Idea

Husky shares Git hooks by storing scripts in the project so they run automatically and consistently for every team member.

Think of it like...

It's like setting a house rule that everyone must follow before leaving the door, such as locking it. Husky makes sure everyone locks the door the same way every time without asking.

┌───────────────┐
│  Git Action   │
│ (commit, push)│
└──────┬────────┘
       │ triggers
┌──────▼────────┐
│   Husky Hook  │
│ (runs scripts)│
└──────┬────────┘
       │ runs
┌──────▼────────┐
│  Team Scripts │
│ (lint, tests) │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

What are Git hooks?

Concept: Introduce Git hooks as scripts that run automatically on Git events.

Git hooks are small scripts that run before or after Git actions like commit or push. They help automate checks or tasks, such as verifying code style or running tests, to keep code quality high.

Result

Learner understands that Git hooks automate tasks tied to Git commands.

Knowing Git hooks exist helps you see how automation can improve code quality and workflow.

2

Foundation

Why share hooks with the team?

Concept: Explain the need for consistent hooks across all developers.

If each developer sets up hooks differently or not at all, the team loses consistency. Sharing hooks ensures everyone runs the same checks automatically, avoiding errors and saving time.

Result

Learner understands the importance of sharing hooks for team consistency.

Understanding team-wide consistency prevents bugs and saves time by automating shared rules.

3

Intermediate

Introducing Husky for hook management

🤔Before reading on: do you think Git hooks are easy to share without extra tools? Commit to your answer.

Concept: Show how Husky simplifies sharing and managing Git hooks in a project.

Husky is a tool that stores Git hooks inside your project files, usually in package.json or a config file. When team members install the project, Husky sets up the hooks automatically, so everyone runs the same scripts.

Result

Learner sees how Husky automates hook sharing and setup.

Knowing Husky automates hook setup removes manual errors and onboarding friction.

4

Intermediate

Setting up Husky in a project

🤔Before reading on: do you think Husky requires global installation or just project setup? Commit to your answer.

Concept: Teach how to install and configure Husky in a project for shared hooks.

1. Run 'npm install husky --save-dev' to add Husky. 2. Run 'npx husky install' to set up Git hooks folder. 3. Add 'prepare' script in package.json: "prepare": "husky install". 4. Add hooks with 'npx husky add .husky/pre-commit "npm test"' to run tests before commit. 5. Commit these files to share with the team.

Result

Project has Husky installed and a pre-commit hook that runs tests.

Knowing the exact commands to set up Husky ensures reproducible, shared hooks.

5

Intermediate

How Husky runs hooks on team machines

Concept: Explain how Husky activates hooks automatically when team members clone and install the project.

When a team member clones the repo and runs 'npm install', the 'prepare' script runs 'husky install', which sets up the Git hooks folder locally. This means hooks like pre-commit scripts run automatically without extra manual setup.

Result

Hooks run automatically on every team member's machine after install.

Understanding this automatic setup explains how Husky keeps hooks consistent without manual steps.

6

Advanced

Customizing and chaining multiple hooks

🤔Before reading on: do you think you can run multiple scripts in one hook easily? Commit to your answer.

Concept: Show how to run multiple commands in one hook and customize hooks for different Git events.

You can chain commands in a hook script using '&&' or create separate scripts. For example, in .husky/pre-commit: #!/bin/sh npm run lint && npm test This runs linting and tests before commit. You can also add hooks for push, commit-msg, etc., customizing checks per event.

Result

Hooks run multiple checks automatically before Git actions.

Knowing how to chain and customize hooks lets you enforce complex quality gates automatically.

7

Expert

Avoiding common pitfalls with Husky hooks

🤔Before reading on: do you think Husky hooks run in the same environment as your terminal? Commit to your answer.

Concept: Explain environment differences and how to debug hook failures in production.

Husky hooks run in a minimal shell environment, which may lack some environment variables or PATH settings. This can cause scripts to fail unexpectedly. To fix, explicitly set environment variables or use full paths in scripts. Also, avoid heavy tasks in hooks to keep commits fast.

Result

Learner can troubleshoot and optimize Husky hooks for real projects.

Understanding environment differences prevents mysterious hook failures and improves developer experience.

Under the Hood

Husky works by creating a .husky directory with shell scripts named after Git hook events (like pre-commit). When Git runs a hook, it executes the corresponding script. Husky installs these scripts by modifying the .git/hooks folder to point to the Husky scripts, ensuring the hooks run the project-defined commands.

Why designed this way?

Git hooks are local and not shared by default, causing inconsistency. Husky was designed to store hooks in the project files, which are version controlled, so all team members get the same hooks. It uses shell scripts for compatibility and simplicity across systems.

┌───────────────┐
│  Git Command  │
│  (commit etc) │
└──────┬────────┘
       │ triggers
┌──────▼────────┐
│ .git/hooks/   │
│ (Git hook dir)│
└──────┬────────┘
       │ points to
┌──────▼────────┐
│ .husky/       │
│ (Husky scripts│
│  in project)  │
└──────┬────────┘
       │ runs
┌──────▼────────┐
│  User scripts │
│ (lint, tests) │
└───────────────┘

Myth Busters - 3 Common Misconceptions

Quick: do you think Git hooks are automatically shared when you push code? Commit yes or no.

Common Belief: Git hooks are shared automatically when pushing code to the repository.

Reality: Git hooks live locally and are not shared via Git push or pull. They must be shared by other means like Husky.

Why it matters: Assuming hooks are shared causes inconsistent checks and bugs slipping into the codebase.

Quick: do you think Husky requires global installation on every developer machine? Commit yes or no.

Common Belief: Husky must be installed globally on every developer's machine to work.

Reality: Husky is installed as a dev dependency in the project and runs locally after 'npm install', no global install needed.

Why it matters: Thinking global install is needed complicates setup and onboarding unnecessarily.

Quick: do you think Husky hooks run with the same environment variables as your terminal? Commit yes or no.

Common Belief: Husky hooks run with the same environment and PATH as my normal terminal.

Reality: Husky hooks run in a minimal shell environment, which may lack some environment variables or PATH entries.

Why it matters: Ignoring this causes confusing script failures that are hard to debug.

Expert Zone

1

Husky hooks run in a minimal shell environment, so environment variables and PATH may differ from your interactive shell.

2

Husky uses shell scripts for hooks, which means cross-platform compatibility requires care, especially on Windows.

3

The 'prepare' script in package.json ensures Husky hooks are installed automatically after 'npm install', streamlining onboarding.

When NOT to use

Husky is not ideal if your team uses non-Node.js environments or package managers. Alternatives like Lefthook or native Git hooks managed by other tools may be better. Also, avoid Husky if you want hooks managed centrally in CI pipelines rather than locally.

Production Patterns

Teams commit Husky config and hook scripts to version control. They use pre-commit hooks for linting and tests, commit-msg hooks for message format checks, and pre-push hooks for integration tests. Hooks are kept fast to avoid slowing developers. Some teams combine Husky with CI checks for layered quality control.

Connections

Continuous Integration (CI)

Builds-on

Shared Git hooks with Husky catch issues early on developer machines, reducing CI failures and speeding up feedback loops.

Version Control Systems

Same domain

Understanding how Git hooks integrate with version control helps grasp how automation fits into code management.

Organizational Behavior

Analogy in team rules enforcement

Just like shared house rules keep a home orderly, shared hooks enforce team coding standards automatically, improving collaboration.

Common Pitfalls

#1 Hooks not running after cloning the repo.

Wrong approach:

git clone https://repo.git
cd repo
# No further steps
# Try to commit, but hooks don't run

Correct approach:

git clone https://repo.git
cd repo
npm install
# 'prepare' script runs 'husky install' to set up hooks
# Now hooks run on commit

Root cause:

Forgetting to run 'npm install' means Husky hooks are not installed locally.

#2 Hooks fail because scripts can't find commands.

Wrong approach:

# .husky/pre-commit
#!/bin/sh
eslint .
# Fails with 'eslint: command not found'

Correct approach:

# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx eslint .
# Uses npx to run eslint from local node_modules

Root cause:

Husky runs in minimal shell without PATH to local node_modules binaries.

#3 Adding heavy tasks in hooks causing slow commits.

Wrong approach:

# .husky/pre-commit
#!/bin/sh
npm run full-build
# Commits take minutes

Correct approach:

# .husky/pre-commit
#!/bin/sh
npm run lint
npm test
# Fast checks keep commits quick

Root cause:

Not balancing hook tasks leads to poor developer experience and skipped hooks.

Key Takeaways

Git hooks automate tasks tied to Git actions but are local and not shared by default.

Husky stores hooks in the project and installs them automatically for every team member, ensuring consistency.

Setting up Husky involves installing it as a dev dependency, running 'husky install', and adding hook scripts.

Husky hooks run in a minimal shell environment, so scripts must handle environment differences carefully.

Shared hooks improve team code quality by enforcing rules automatically before code is committed or pushed.