Skip to main content

goose
💻🪿

A picky and eager Git hook runner

  • 🔒 Reproducible builds
  • ⚡ Dynamic parallelism
  • 💨 Small file-system footprint
  • 🏃 Fast Python installs with uv

Installation

Refer to the documentation for alternative installation instructions.

Via uvx

uvx install git-goose

Github Actions

name: CI
on:
  push:
    branches: ["main"]
  pull_request:
jobs:
  lint:
    name: Run goose checks
    uses: antonagestam/goose/.github/workflows/run.yaml@main

Features

  • Smart parallelism schedules hooks across CPUs while avoiding concurrent writes.
  • Deterministic environments by using ecosystem-specific lock files.
  • Environments are shared across hooks.
  • Self-contained definitions means there's no need to push tool-specific configuration upstream, or to maintain brittle mirroring schemes.

Parallelism

Goose takes care to keep your CPUs as busy as possible, optimizing to have the full suite of hooks finish as soon as possible. It does this by distributing units of work to all available processing cores.

Parameterized hooks, or hooks that take files as command line arguments, are divided to one unit of work per available core. Whenever a core becomes available for more work, a new unit is chosen for execution.

The scheduler takes care to never run more than one mutating hook on the same file. It does this by taking into account hooks marked as read_only and by comparing sets of files a unit of work is assigned to. Two incompatible hooks can be simultaneously working on two separate parts of the code-base.

Deterministic environments

Goose uses lock files to facilitate deterministic results across developer environments and CI. You specify dependencies in goose.yaml, and invoking goose run will produce the appropriate lock files under a .goose/ directory. The .goose/ directory is meant to be checked into git, so that future invocations of goose run can use the lock files it contains to produce identical environments for hooks to run in.

---
title: Lock file workflow
---
flowchart LR
  cfg["Config in goose.yaml"] -- goose upgrade --> lf
  lf["Lock files under .goose/"] -- goose run --> env
  env["Environments"]
  • Invoking goose upgrade creates lock files under the in-tree .goose directory.
  • Invoking goose run creates out-of-tree environments from the lock files. By default they live under ~/.cache/goose.
  • Hooks are executed in the generated environments.

Usage

Create a goose.yaml file in the repository root.

environments:
  - id: python
    ecosystem:
      language: python
      version: "3.15"
    dependencies:
      - ruff

hooks:
  - id: ruff
    environment: python
    command: ruff
    args: [check, --force-exclude, --fix]
    types: [python]

  - id: ruff-format
    environment: python
    command: ruff
    args: [format, --force-exclude]
    types: [python]

Bootstrap environments, generate lock files, and install dependencies.

$ goose upgrade

Run all hooks over all files.

$ goose run --select=all

Commit configuration and lock files.

$ git add goose.yaml .goose
$ git commit -m 'Add goose configuration'

Configure goose to run as git hook. Supported hooks are pre-commit and pre-push.

$ goose git-hook pre-commit
$ goose git-hook pre-push

Upgrading hook versions

As pinning of hook versions is handled with lock files, there's no need to change configuration to upgrade hook dependency versions, instead you just run the upgrade command.

$ goose upgrade
$ git add .goose
$ git commit -m 'Bump goose dependencies'

Example node hook

Goose currently supports Python and Node environments, here's an example using Prettier to format Markdown files.

environments:
  - id: node
    ecosystem:
      language: node
      version: "21.7.1"
    dependencies:
      - prettier

hooks:
  - id: prettier
    environment: node
    command: prettier
    types: [markdown]
    args:
      - --write
      - --ignore-unknown
      - --parser=markdown
      - --print-width=88
      - --prose-wrap=always

Read-only hooks

You will likely want to use a mix of pure linters, as well as formatters and auto-fixers. Tools that don't mutate files can be more heavily parallelized by Goose, because they can inspect overlapping sets of files simultaneously as other tools. To enable this you set read_only: true in hook configuration.

environments:
  - id: python
    ecosystem:
      language: python
      version: "3.15"
    dependencies:
      - pre-commit-hooks

hooks:
  - id: check-case-conflict
    environment: python
    command: check-case-conflict
    read_only: true

  - id: check-merge-conflict
    environment: python
    command: check-merge-conflict
    read_only: true
    types: [text]

  - id: python-debug-statements
    environment: python
    command: debug-statement-hook
    read_only: true
    types: [python]

  - id: detect-private-key
    environment: python
    command: detect-private-key
    read_only: true
    types: [text]

  - id: end-of-file-fixer
    environment: python
    command: end-of-file-fixer
    types: [text]

  - id: trailing-whitespace-fixer
    environment: python
    command: trailing-whitespace-fixer
    types: [text]

Hooks that do not specify read_only: true will never run simultaneously as other tools over the same file.

Non-parameterized hooks

Some tools don't support passing files, or just work better if given the responsibility to parallelize work itself. One such tool is mypy. You can instruct goose to not pass filenames to a hook (and as a consequence, also not spawn multiple parallel jobs for this hook).

environments:
  - id: mypy
    ecosystem:
      language: python
      version: "3.15"
    dependencies:
      - mypy

hooks:
  - id: mypy
    environment: mypy
    command: mypy
    read_only: true
    parameterize: false

Environment variables

Hook invocations are called with the same environment variables as goose is invoked with, other than PATH being overridden to point at the environment of the hook.

Static environment variables can be configured in hook definitions. These will overwrite inherited values, but cannot overwrite PATH.

hooks:
  - id: mypy
    environment: type-check
    command: mypy
    env_vars:
      FORCE_COLOR: "1"
    read_only: true
    parameterize: false

Terse and loose environment configs

Environments can be configured less verbosely. The id field can be omitted and will then default to the name of the ecosystem language.

Version can also be omitted in the configuration and will then cause the highest available version to be pinned when calling goose upgrade. Since the ecosystem version is pinned in the manifest regardless of whether it is specified in the config or not, this omitting the version from the config is not any less safe.

environments:
  - ecosystem: python
    dependencies:
      - ruff

hooks:
  - id: ruff
    environment: python
    command: ruff
    args: [check, --force-exclude, --fix]
    types: [python]

  - id: ruff-format
    environment: python
    command: ruff
    args: [format, --force-exclude]
    types: [python]

Metadata

Release files for git-goose 0.15.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for git-goose 0.15.2
File Size Uploaded Provenance Actions
git_goose-0.15.2.tar.gz 111.8 kB With provenance Details for git_goose-0.15.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for git-goose 0.15.2
File Interpreter ABI Platform Actions
git_goose-0.15.2-py3-none-any.whl Python 3 none any Details for git_goose-0.15.2-py3-none-any.whl

Total release size: 146.4 kB

Release files / git_goose-0.15.2.tar.gz

Download URL git_goose-0.15.2.tar.gz
Size 111.8 kB
Tags Source
SHA-256 checksum
How to use checksums
60893c52c5d43f58f3dfb52957e3f7016b6107e53b62e5a5910509389fde08f6
BLAKE2b-256 checksum
How to use checksums
ba21d432da8826ba7d7ff3713340edff876d5840b279bb47376537bcfbed4725
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / git_goose-0.15.2-py3-none-any.whl

Download URL git_goose-0.15.2-py3-none-any.whl
Size 34.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d99921838bd5d645dda1d6291144ecddfb070bc3cc48a3b8a51ac12d96a30f91
BLAKE2b-256 checksum
How to use checksums
a21162a603e395ded2d10dfc4d0eee713a061a42c3567fe7b2d0ffb3a4f5691e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for git-goose 0.15.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for git_goose-0.15.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.15.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page