GitHub - hkdobrev/run-if-changed: Run a command if a file changes via Git hooks

Run a command if a file changes via Git hooks. Useful for lock files or build systems to keep dependencies and generated files up to date when changing branches, pulling or commiting.

Inspired by lint-staged and recommended to be used with husky.

State of the project

run-if-changed is small and focused, and used in production setups. It's still intentionally minimal, so issues, feature requests and pull requests are most welcome!

Installation and setup

npm install --save-dev husky @hkdobrev/run-if-changed

"run-if-changed": {
  "package-lock.json": "npm install --prefer-offline --no-audit"
}

yarn add --dev husky @hkdobrev/run-if-changed

"run-if-changed": {
  "yarn.lock": "yarn install --prefer-offline --pure-lockfile --color=always"
}

Set up Git hooks

echo "npx run-if-changed" > .husky/post-commit
echo "npx run-if-changed" > .husky/post-checkout
echo "npx run-if-changed" > .husky/post-merge
echo "npx run-if-changed" > .husky/post-rewrite

echo "npx run-if-changed" >> .git/hooks/post-commit && chmod +x .git/hooks/post-commit
echo "npx run-if-changed" >> .git/hooks/post-checkout && chmod +x .git/hooks/post-checkout
echo "npx run-if-changed" >> .git/hooks/post-merge && chmod +x .git/hooks/post-merge
echo "npx run-if-changed" >> .git/hooks/post-rewrite && chmod +x .git/hooks/post-rewrite

Why

The use case for run-if-changed is mostly for a team working on a project and push and pull code in different branches. When you share dependencies, database migrations or compilable code in the shared Git repository often some commands need to be run when a file or folder gets updated.

Check out the common use cases.

Configuration

• run-if-changed object in your package.json
• .run-if-changedrc file in JSON or YML format
• run-if-changed.config.js file in JS format

See cosmiconfig for more details on what formats are supported.

Configuration should be an object where each key is a micromatch pattern matched against the paths of the changed files, and the value is either a single command or an array of commands to run if a matching file has changed since the last Git operation.

Patterns are matched against the full file path, so to match everything inside a directory use a globstar — e.g. "src/**", not "src". A bare directory name only matches a file with that exact path.

What commands are supported?

Supported are any executables installed locally or globally via npm or Yarn as well as any executable from your $PATH.

Using globally installed scripts is discouraged, since run-if-changed may not work for someone who doesn't have it installed.

run-if-changed is using execa to locate locally installed scripts and run them. So in your .run-if-changedrc you can just write and it would use the local version:

Sequences of commands are supported. Pass an array of commands instead of a single one and they will run sequentially.

Monorepos

run-if-changed works in a monorepo where a single Git repository holds multiple packages. Give each package its own configuration (a run-if-changed key in that package's package.json, or a .run-if-changedrc next to it) and write the patterns relative to that package:

// packages/api/package.json
{
  "run-if-changed": {
    "proto/**": "npm run codegen"
  }
}

When a changed file is found, run-if-changed looks for the nearest configuration in that file's directory or above it, up to the repository root, and runs the matching commands with that package's directory as the working directory. So changing packages/api/proto/service.proto runs npm run codegen inside packages/api.

A few details worth knowing:

• Nearest config wins. A file is owned by the closest configuration at or above it; a configuration at the repository root only handles files that no nested package claims.
• Inheritance. A package without its own configuration falls through to the nearest ancestor configuration (up to the root). A package.json with no run-if-changed key does not stop this search.
• Single root lock file. npm/Yarn/pnpm workspaces usually keep a single lock file at the repository root, so the "install on lock file change" use case stays a root configuration ("pnpm-lock.yaml": "pnpm install"), not a per-package one. Per-package configurations are best for build, code generation and migrations that belong to one package.

Use cases

Install or update dependencies when lock file changes

If you use a dependency manager with a lock file like npm, Yarn, Composer, Bundler or others, you would usually add a dependency and the dependency manager would install it and add it to the lock file in a single run. However, when someone else has updated a dependency and you pull new code or checkout their branch you need to manually run the install command of your dependency manager.

Here's example configuration of run-if-changed:

{
  "run-if-changed": {
    "package-lock.json": "npm install --prefer-offline --no-audit --no-fund"
  }
}

{
  "package-lock.json": "npm install --prefer-offline --no-audit --no-fund"
}

{
  "run-if-changed": {
    "pnpm-lock.yaml": "pnpm install --prefer-offline"
  }
}

{
  "pnpm-lock.yaml": "pnpm install --prefer-offline"
}

{
  "run-if-changed": {
    "yarn.lock": "yarn install --prefer-offline --pure-lockfile --color=always --non-interactive"
  }
}

{
  "yarn.lock": "yarn install --prefer-offline --pure-lockfile --color=always --non-interactive"
}

{
  "run-if-changed": {
    "composer.lock": "composer install --ignore-platform-reqs --ansi"
  }
}

{
  "run-if-changed": {
    "Gemfile.lock": "bundle install --prefer-local"
  }
}

Run database migrations if there are new migrations

If you keep database migrations in your repository, you'd usually want to run them when you check out a branch or pull from master.

{
  "run-if-changed": {
    "migrations/**": "./console db:migrate --allow-no-migration --no-interaction"
  }
}

Compile sources in a build folder after pulling new code.

{
  "run-if-changed": {
    "src/**": "npm run build"
  }
}