Skip to content
Ultracite
Esc
↑↓navigate↵open⌘Jpreview
On this page

Git Hooks

Run Ultracite automatically before each commit with Husky, Lefthook, lint-staged, or pre-commit so staged files stay clean and consistent.

Ultracite integrates with popular Git hook tools to automatically format and lint your code before every commit. This ensures all committed code follows your project’s standards without manual intervention.

Setup

During initialization, you can select which Git hook tool to use:

npx ultracite init --integrations husky lint-staged

Or select them interactively when prompted. In a project that’s already set up, this keeps its current linter and your changes to its configs.

Supported Tools

Every hook runs the ultracite installed in your project rather than downloading the latest release, so commits use the version your lockfile pins. The command depends on your package manager: npx ultracite fix (npm), yarn ultracite fix, pnpm exec ultracite fix, bunx ultracite fix, deno run -A npm:ultracite fix, nub exec ultracite fix, or aube exec ultracite fix. The examples below use npm.

Re-running ultracite init updates a hook it wrote earlier instead of adding a second one, and leaves commands you wrote yourself alone. That includes hooks from before v8, which ran ultracite fix on the whole project and matched fewer file types, and ones that used pnpm dlx or yarn dlx.

Husky

Husky is a popular tool for managing Git hooks. Ultracite adds a marker-wrapped section to your .husky/pre-commit file. When files are staged, it runs ultracite fix on just those files, re-stages them, and fails the commit if any issues couldn’t be auto-fixed:

# ultracite
#!/bin/sh
# Fix only the staged files
STAGED_FILES=$(git -c core.quotePath=false diff --cached --name-only --diff-filter=ACMR)
if [ -z "$STAGED_FILES" ]; then
  echo "No staged files to format"
else
  # Staged files that also have unstaged changes, found before fixing
  UNSTAGED_FILES=$(git -c core.quotePath=false diff --name-only)
  PARTIALLY_STAGED=""
  FULLY_STAGED=$STAGED_FILES
  if [ -n "$UNSTAGED_FILES" ]; then
    PARTIALLY_STAGED=$(printf '%s\n' "$STAGED_FILES" | grep -Fx -- "$UNSTAGED_FILES" || true)
  fi
  if [ -n "$PARTIALLY_STAGED" ]; then
    FULLY_STAGED=$(printf '%s\n' "$STAGED_FILES" | grep -Fxv -- "$PARTIALLY_STAGED" || true)
  fi

  # Run the fixer on the staged files, capturing the exit code so we can
  # still re-stage and report
  FORMAT_EXIT_CODE=0
  git diff --cached --name-only -z --diff-filter=ACMR | xargs -0 npx ultracite fix || FORMAT_EXIT_CODE=$?

  # Re-stage the fully staged files; staging the others would add their
  # unstaged changes to the commit
  printf '%s\n' "$FULLY_STAGED" | while IFS= read -r file; do
    if [ -f "$file" ]; then
      git add -- "$file"
    fi
  done

  if [ -n "$PARTIALLY_STAGED" ]; then
    echo "These files also have unstaged changes, so Ultracite's fixes to them were left unstaged. Review and stage them:"
    printf '%s\n' "$PARTIALLY_STAGED" | sed 's/^/  /'
  fi

  if [ $FORMAT_EXIT_CODE -ne 0 ]; then
    echo "Ultracite found issues that could not be auto-fixed."
    exit $FORMAT_EXIT_CODE
  fi

  echo "✨ Files formatted by Ultracite"
fi
# ultracite end

A file you staged only part of is fixed but not re-staged, since git add would also stage the changes you left out. The hook lists those files so you can review the fixes and stage them yourself; until you do, the commit takes the version you staged.

Anything you’ve added to the hook outside the # ultracite markers is preserved when Ultracite updates it, and still runs when nothing is staged. If you also select lint-staged, the section runs lint-staged (npx lint-staged) instead of the script above.

Ultracite also adds husky to your prepare script so hooks are installed on npm install. An existing prepare script is kept, with && husky appended.

Lefthook

Lefthook is a fast Git hooks manager written in Go. If your project has no Lefthook config, Ultracite creates a lefthook.yml:

pre-commit:
  jobs:
    - run: npx ultracite fix {staged_files}
      glob:
        - "*.js"
        - "*.jsx"
        - "*.mjs"
        - "*.cjs"
        - "*.ts"
        - "*.tsx"
        - "*.mts"
        - "*.cts"
        - "*.json"
        - "*.jsonc"
        - "*.css"
        - "*.scss"
        - "*.less"
        - "*.vue"
        - "*.svelte"
        - "*.astro"
        - "*.html"
        - "*.md"
        - "*.mdx"
        - "*.yaml"
        - "*.yml"
        - "*.graphql"
        - "*.gql"
      stage_fixed: true

Lefthook replaces {staged_files} with the staged files that match the globs, so only those are fixed, and stage_fixed re-stages them. The globs cover every file type Biome, Oxlint and Oxfmt, or ESLint, Prettier and Stylelint lint or format. With Lefthook’s default glob matcher, *.js matches files in every directory, including the project root. If your config sets glob_matcher: doublestar, Ultracite writes **/*.js-style globs instead.

If you already have a Lefthook config, Ultracite edits the one Lefthook actually loads (lefthook.yml, .lefthook.yml, .config/lefthook.yml, or their .yaml variants) and adds the job first in pre-commit, keeping your comments and formatting. JSON and TOML configs aren’t edited: Ultracite prints the job to add instead. Ultracite also appends lefthook install to your prepare script, keeping any existing command.

lint-staged

lint-staged runs linters only on staged files. If your project has no lint-staged config, Ultracite creates a .lintstagedrc.json:

{
  "*.{js,jsx,mjs,cjs,ts,tsx,mts,cts,json,jsonc,css,scss,less,vue,svelte,astro,html,md,mdx,yaml,yml,graphql,gql}": [
    "npx ultracite fix"
  ]
}

If you already have one, Ultracite adds its task to the config lint-staged actually uses: a dedicated config file (.lintstagedrc in any format, including .ts, .mts, and .cts, or lint-staged.config.*) wins over a "lint-staged" key in package.json, which wins over one in package.yaml. YAML configs keep their comments, ES module and TypeScript configs are edited in place, and CommonJS configs are rewritten from their loaded values. If a config can’t be merged safely (for example, one that exports a function or wraps its object in defineConfig()), Ultracite leaves it untouched and prints the command to add, rather than creating a second config that would shadow yours.

The glob covers the same file types as the Lefthook globs, in every directory, and lint-staged passes the staged files that match it to ultracite fix and re-stages them. Re-running init widens the narrower glob earlier versions wrote (*.{js,jsx,ts,tsx,json,jsonc,css,scss,md,mdx}) while its task is still only Ultracite’s command.

lint-staged needs a Git hook to trigger it, so it’s typically used alongside Husky or Lefthook.

pre-commit

pre-commit is a Python-based framework for managing Git hooks. Ultracite creates a .pre-commit-config.yaml, or adds a local repo entry to the top of your existing one, keeping its comments and indentation style:

repos:
  - repo: local
    hooks:
      - id: ultracite
        name: ultracite
        entry: npx ultracite fix
        language: system
        files: \.(js|jsx|mjs|cjs|ts|tsx|mts|cts|json|jsonc|css|scss|less|vue|svelte|astro|html|md|mdx|yaml|yml|graphql|gql)$
        require_serial: true

The files pattern covers the same file types as the Lefthook globs. It’s a pattern rather than types_or because pre-commit has no file type tags for .jsonc, .mts, .cts, or .gql. pre-commit passes the staged files that match it to ultracite fix, and sets your unstaged changes aside while the hook runs. require_serial keeps it to a single ultracite fix run instead of one per CPU. If the fixes change any files, pre-commit stops the commit so you can stage them. After setup, run pre-commit install to activate the hooks.

How It Works

  1. You make changes and stage files with git add
  2. You run git commit
  3. The pre-commit hook runs ultracite fix on the files you staged
  4. Code is formatted, auto-fixable issues are resolved, and the fixed files are re-staged (Husky, Lefthook, and lint-staged; pre-commit asks you to stage them)
  5. The commit proceeds, or stops if issues remain that couldn’t be auto-fixed

Benefits

  • Consistency: All committed code follows the same standards
  • Automation: No need to remember to format code manually
  • Clean History: Formatting issues never enter your repository
  • Team Collaboration: Everyone follows the same rules automatically

Bypassing Hooks

In rare cases where you need to skip the pre-commit hook:

git commit --no-verify

Use this sparingly, as it bypasses the automated formatting.

Last updated on

Was this page helpful?