Overcommit Documentation

To enforce specific versions of Overcommit or other gems used in hooks, use the gemfile option in .overcommit.yml.

Performance Tip: Loading a large project Gemfile adds startup delay. It is recommended to create a dedicated, minimal Gemfile (e.g., .overcommit_gems.rb) containing only the gems required for your hooks.

1. Create .overcommit_gems.rb in your root.
2. Run bundle install --gemfile=.overcommit_gems.rb.
3. Commit both .overcommit_gems.rb and .overcommit_gems.rb.lock.
4. Set the gemfile option in .overcommit.yml to .overcommit_gems.rb.

To have Overcommit automatically populate the .git directory for every new repository you create or clone, set the GIT_TEMPLATE_DIR environment variable in your shell configuration to the directory provided by Overcommit.

export GIT_TEMPLATE_DIR="$(overcommit --template-dir)"

Overcommit uses signature checking to protect against malicious code execution. It stores a signature of your configuration and all hook plugin code; if the signature changes (due to changes in .overcommit.yml or plugin source code), Overcommit will issue a warning.

Initial Setup

Regardless of your verification settings, you must run the following command once to sign your configuration and record your intent in your local git repository:

overcommit --sign

Disabling Signature Verification

In trusted environments (e.g., proprietary repositories with cleared developers), you can disable this check by setting verify_signatures to false in your .overcommit.yml file. Note: This is not recommended for public/open-source workflows.

Install the overcommit gem via RubyGems. It is recommended to use a Ruby version manager (like rbenv or rvm) to avoid using sudo for gem installation.

To set up Overcommit in a specific repository:

1. Install the gem.
2. Initialize a Git repository.
3. Run overcommit --install within the repository directory.

Note: overcommit --install will back up any existing Git hooks it replaces. You can restore them by running overcommit --uninstall.

gem install overcommit

mkdir important-project
cd important-project
git init
overcommit --install

Within a hook category (like PreCommit), you can use a special ALL key to apply configuration settings to every hook in that category. This helps keep your configuration DRY.

Note on Merging: Array configuration options (like include or exclude) in the ALL section are not merged with individual hook configurations. If a specific hook defines its own include or exclude, it will completely replace the ALL setting for that hook. To extend ALL settings for a specific hook, use YAML references.

PreCommit:
  ALL:
    exclude: &default_excludes
      - 'node_modules/**/*'
      - 'vendor/**/*'
  MyHook:
    exclude:
      - *default_excludes
      - 'another/directory/in/addition/to/default/excludes/**/*'

Overcommit configuration is stored in .overcommit.yml in the top-level directory of your repository. Your configuration automatically extends the default configuration, so you only need to specify overrides.

To enable/disable hooks or change their execution context (e.g., using Bundler), add them under their respective category (e.g., PreCommit).

For local-only configurations that are not shared with the repository, use a .local-overcommit.yml file in the top-level directory and add it to your .gitignore.

PreCommit:
  RuboCop:
    enabled: true
    command: ['bundle', 'exec', 'rubocop'] # Invoke within Bundler context

If you need to bypass a specific hook that is reporting an error, use the SKIP environment variable with the name of the hook.

Alternatively, you can use the ONLY environment variable to specify a whitelist of hooks that should run, effectively skipping everything else.

The Overcommit::Printer class manages how hook execution results are reported to the user. It handles status reporting (success, warning, failure, interruption) and manages output formatting.

Key behaviors include:

• Quiet Mode: When the quiet configuration key is set to true, the printer suppresses most success messages and headers to reduce noise.
• Status Reporting: The printer maps hook statuses to specific visual indicators:
  • :pass -> OK (suppressed in quiet mode or for quiet hooks)
  • :warn -> WARNING
  • :fail -> FAILED
  • :interrupt -> INTERRUPTED
• Thread Safety: The printer uses internal synchronization to ensure that output from different threads is not interleaved during hook execution.

You can adjust several global settings in .overcommit.yml to change how the entire engine behaves:

• quiet: Set to true to make all hooks completely silent unless there is a problem.
• concurrency: Adjust the number of concurrent workers. You can use mathematical expressions involving %{processors}.
• plugin_directory: Change the directory where project-specific hooks are loaded from (defaults to .git-hooks).
• verify_signatures: Set to false to disable manual verification of signatures.

Example of adjusting concurrency:

concurrency: '%{processors} / 4'

PrePush

Runs during git push after remote refs are updated but before objects are transferred. If a hook fails, the push is aborted.

Available hooks:

• Brakeman, FlutterTest, Minitest, PhpUnit, Pronto, ProtectedBranches, PubTest, Pytest, PythonNose, RakeTarget, RSpec, TestUnit

PreRebase

Runs during git rebase before any commits are rebased. If a hook fails, the rebase is aborted.

Available hooks:

• MergedCommits

Enable commit-msg hooks in your .overcommit.yml to enforce policies on commit messages (e.g., task IDs or formatting). A failed hook prevents the commit from being created.

Note: Hooks marked with * are enabled by default.

Available hooks:

• CapitalizedSubject (default)
• EmptyMessage (default)
• GerritChangeId
• HardTabs
• MessageFormat
• RussianNovel
• SingleLineSubject (default)
• SpellCheck
• TextWidth (default)
• TrailingPeriod (default)