The git hook runner for containerized dev. Run your linters and formatters inside DDEV or Docker — automatically, no wrapper scripts. A single Go binary, no Node.js required.

If your tools live inside a container — phpstan, ecs, php-cs-fixer in a DDEV or Docker environment — every other hook runner makes you write wrapper scripts to shell into the container. forge routes tools to the container for you: set backend = "ddev" (or a container name), and forge auto-detects the running environment and executes the tool where it actually lives.

It's also a solid general-purpose runner: one binary, no package.json, works in PHP, Go, Python, or mixed monorepos.

The top two rows are what no other runner does — that's the reason forge exists. If you don't need container-aware hooks, lefthook is a fine choice too; forge earns its place when your toolchain lives in a container or you want commit-message policy without wiring up commitlint.

curl -fsSL https://raw.githubusercontent.com/TerrorSquad/forge/main/install.sh | sh

go install github.com/TerrorSquad/forge/cmd/forge@latest

Download a pre-built binary from Releases and place it on your PATH.

# 1. Create forge.toml
forge init --preset go       # or: node, php, php-node, minimal

# 2. Install git hook shims
forge install

# 3. Commit — hooks fire automatically
git commit -m "feat: my change"

forge.toml lives at the repo root. Copy forge.toml.example to get started.

[hooks.pre-commit]
enabled = true

[hooks.pre-commit.tools.gofmt]
command = "gofmt"
args    = ["-w"]
type    = "system"
extensions = [".go"]
restage = true

[hooks.commit-msg]
enabled = true

[hooks.commit-msg.policy]
conventional_commits = true

[hooks.commit-msg.policy]
conventional_commits = true    # enforce feat/fix/chore/... prefix
append_ticket_footer = true    # append "Closes: PRJ-123" from branch name
require_ticket       = false   # fail if branch has no ticket

[execution]
default_backend = "ddev"   # route all tools through `ddev exec`

Or per tool: backend = "ddev" or a Docker container name like backend = "my-app-web". ddev is auto-detected when .ddev/config.yaml exists and the DDEV container is running (checked via docker inspect).

[workspace]
members = ["apps/*", "packages/*"]

When staged files belong to a member directory, forge runs the hook for that member only (using the member's own forge.toml if present, otherwise the root config).

forge migrate --from .git-hooks.config.json --to forge.toml

Reads the legacy JSON format and emits an equivalent forge.toml. Review and adjust before running forge install.

MIT

go build -o forge ./cmd/forge

# 1) Build or install forge on PATH
go build -o forge ./cmd/forge
mv forge /usr/local/bin/

# 2) In a git repo
forge init
forge install

# 3) Verify
forge doctor

After forge install, git core.hooksPath is set to .forge/hooks. Git automatically executes hook shims there on commit/push.

If the repo has .forge committed, users still need to run forge install after cloning so local git config is updated. If .forge is missing, forge install creates it and writes the hook shims.

forge init [--force]
forge install
forge uninstall
forge run <hook> [--edit FILE]
forge doctor

• pre-commit
  • reads staged files (git diff --cached --name-only --diff-filter=ACMR)
  • filters files by configured extensions/patterns
  • runs tools in the order they are declared in forge.toml
  • re-stages files for tools with restage = true
• commit-msg
  • validates conventional commit subject (if enabled)
  • appends Closes: TICKET from branch name (if enabled)
• pre-push
  • runs configured tools (no staged-file filtering unless tool needs files)

• FORGE_CONFIG: custom config file path
• HOOKS_ONLY: comma-separated tool groups (example: lint,format)
• SKIP_PRECOMMIT, SKIP_PREPUSH, SKIP_COMMITMSG: skip whole hook
• SKIP_<TOOL_NAME>: skip specific tool, normalized to uppercase snake case

Examples:

HOOKS_ONLY=lint git commit -m "fix: lint only"
SKIP_PHPSTAN=1 git commit -m "chore: bypass phpstan"

Generated starter config:

[hooks.pre-commit]
enabled = true

[hooks.pre-commit.tools.prettier]
command = "prettier"
args = ["--write", "--ignore-unknown"]
extensions = [".js", ".ts", ".json", ".md"]
restage = true
group = "format"

[hooks.commit-msg]
enabled = true

[hooks.commit-msg.policy]
conventional_commits = true
append_ticket_footer = true
require_ticket = false

This is a practical v1 prototype aimed at proving the install/run UX and config model. It intentionally keeps execution simple (host commands, sequential runs, no plugin system yet).