Git Pre-Commit Hook & Configuration

Never let broken code or exposed keys leave your developer workstation. Install Ship as an automated, team-committed git pre-commit hook and persist scan rules via .ship.toml.

01. Setup Protocol (ship init)

Zero-Config Repository Integration

Running ship init inside any git project configures a shared repository hook:

ship init
# or tailor what runs during pre-commit:
ship init --skip tests,logs      # fast check (default skips tests)
ship init --only secrets,todos   # focus only on secrets and TODO markers
ship init --all                  # execute every check including tests

01 Shared Hook Directory

Creates .githooks/pre-commit (with execute permissions 0755). Unlike .git/hooks/, this folder can be checked into git.

02 Git Config Binding

Configures git core settings: git config core.hooksPath .githooks so git immediately fires the script upon git commit.

03 Project Config

Generates a starter .ship.toml config file (unless --no-config is supplied) to enforce default skips and filters across your team.

04 Sub-Second Execution

By default skips the test suite (which belongs in CI or manual pre-push) so local commits remain instant and painless.

02. Team Onboarding Workflow

Commit Once, Protect Everyone

Commit the created hooks directory and config file so everyone on your team shares identical pre-commit safety policies:

git add .githooks .ship.toml
git commit -m "chore: add ship pre-commit hook and repository config"

When other engineers clone or pull the repository, they enable the shared hooks with one quick git command:

git config core.hooksPath .githooks

03. Repository Configuration (.ship.toml)

Declarative Rule Definition

Ship reads .ship.toml from your project root. Any option specified in the file sets the default behavior for both manual ship runs and pre-commit hook executions:

# .ship.toml — Ship project configuration
# Placed in the root of your repository

# Checks to skip by default:
# Options: "tests", "secrets", "todos", "logs", "flags", "version", "migrations", "changelog"
skip = ["todos", "logs"]

# Or run exclusively a specific set of checks (mutually exclusive in practice):
# only = ["secrets", "tests"]

Key	Type	Description
`skip`	`Array<String>`	List of check names to ignore during execution (e.g. `["todos", "logs"]`). Command-line `--skip` flags merge with or override this.
`only`	`Array<String>`	List of checks to run exclusively (e.g. `["secrets", "tests"]`). If specified, all other checks are omitted.