Skip to main content
Pre-commit hooks let you run custom scripts that automatically validate your changes before each commit. If the script exits with a non-zero code, the commit is blocked - giving you a chance to fix issues before they reach the repository.

​
Overview

Hooks are executable scripts stored in a .dvhooks/ directory at the root of your repository. Because they live inside the repository, they sync to all collaborators just like any other file. Common use cases:
  • Lint and syntax checks
  • Code formatting enforcement
  • Preventing commits of large or forbidden files
  • Custom project-specific validation
How it works:
  • Before a commit, Diversion runs the .dvhooks/pre-commit script with the committed files as command-line arguments
  • Exit code 0 means the hook passed - the commit proceeds
  • Any non-zero exit code means the hook failed - the commit is blocked
  • The hook’s stdout/stderr output is displayed to the user
Pre-commit hooks are client-side only. They run when committing via the CLI or Desktop app. Commits made directly through the WebApp or API bypass hooks.

​
Creating a Pre-Commit Hook

1

Create the hooks directory

Create a .dvhooks directory at the root of your repository:
mkdir .dvhooks
2

Create the hook script

Create a pre-commit script inside .dvhooks/. The script can be written in any language, as long as it’s executable.
#!/bin/sh
echo "Running pre-commit checks..."

# Committed files are passed as arguments ($@)
for file in "$@"; do
  if echo "$file" | grep -q '\.js$'; then
    if grep -q "console.log" "$file"; then
      echo "Error: Remove console.log from $file before committing."
      exit 1
    fi
  fi
done

echo "All checks passed."
exit 0
On Mac/Linux, make the script executable:
chmod +x .dvhooks/pre-commit
3

Commit the hook

Commit the .dvhooks/ directory to share the hook with your collaborators:
dv commit .dvhooks -m "Add pre-commit hook"
Once committed, every collaborator on the branch will have the hook and it will run automatically before their commits.

​
File Arguments

The files being committed are passed to your hook script as command-line arguments. Your script can access them via $@ (Mac/Linux) or %* (Windows). When the file list is too large for a single command invocation, Diversion automatically splits it into chunks and runs the hook multiple times in parallel. If any invocation fails, the commit is blocked. Example - check committed files for large binaries: 
#!/bin/sh
# Reject files larger than 100MB
MAX_SIZE=$((100 * 1024 * 1024))
for file in "$@"; do
  if [ -f "$file" ]; then
    size=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null)
    if [ "$size" -gt "$MAX_SIZE" ]; then
      echo "Error: $file is too large ($(($size / 1024 / 1024))MB, limit 100MB)."
      exit 1
    fi
  fi
done

exit 0

​
Environment Variables

Diversion also passes context to your hook script via environment variables:
VariableDescription
DV_REPO_ROOTAbsolute path to the workspace root
DV_COMMIT_MESSAGEThe commit message
DV_BRANCHCurrent branch name
Example - require a ticket number in the commit message: 
#!/bin/sh
# Require commit messages to contain a ticket reference (e.g., PROJ-123)
if ! echo "$DV_COMMIT_MESSAGE" | grep -qE '[A-Z]+-[0-9]+'; then
  echo "Error: Commit message must include a ticket number (e.g., PROJ-123)."
  echo "Your message: $DV_COMMIT_MESSAGE"
  exit 1
fi

exit 0

​
Skipping Hooks

Use the --no-verify flag to bypass pre-commit hooks for a single commit: 
dv commit -a -m "quick fix" --no-verify
This is useful for urgent fixes when you need to commit without running validation.

​
Behavior Details

  • Timeout: Hooks have a 60-second timeout. If the hook doesn’t finish in time, the commit is blocked with a timeout message.
  • Working directory: The hook runs with the workspace root as its working directory.
  • Output limit: Hook output is capped at 1 MB. Output beyond that limit is truncated.
  • Output display: Hook output is always shown to the user, whether the hook passes or fails.
  • Platform detection:
    • Mac/Linux: Diversion looks for an executable file named pre-commit in .dvhooks/. If the file exists but isn’t executable, you’ll see an error prompting you to run chmod +x.
    • Windows: Diversion looks for pre-commit.bat, pre-commit.cmd, or pre-commit.ps1 in .dvhooks/ (checked in that order).