Imagine you have a directory - maybe for migrations, test cases, or some other specific type of files - and you want to ensure every file inside follows a consistent naming pattern with a prefix like migration_ or testcase_. I recently ran into this exact need. Since our team use a pre-commit in our daily workflows, I decided to create a small hook to enforce this rule automatically. It’s lightweight, does one job well, and I’ve made it public in case it’s useful to others too. In this post, I’ll walk you through what the tool does, how it works, and how to get started using it.

I created check-filename-prefix to solve that exact problem in one of my projects. It’s a simple pre-commit hook that checks whether added or modified filenames start with a specific prefix. If not, it fails the commit with a clear message.

First, what is pre-commit?

As it stated on their site - it’s a framework for managing and maintaining multi-language pre-commit hooks. Pre-commit hooks help catch simple issues (like formatting or debug code) before review, allowing code reviewers to focus on more meaningful things. As teams grew and projects multiplied, maintaining custom hooks became tedious and error-prone. To solve this, pre-commit was created - a multi-language package manager for pre-commit hooks. It simplifies sharing, installing, and running hooks across different projects and languages, without requiring root access or complex setup, even for tools outside your project’s primary stack.

Getting started with pre-commit and check-filename-prefix

To start make sure you have:

• pre-commit installed
• a bash shell available
• a POSIX-compliant OS (Linux, macOS, WSL, etc.)

Once you there, create a file .pre-commit-config.yaml in a root of your project. Then add the following content to your .pre-commit-config.yaml:

- repo: https://github.com/dunterov/check-filename-prefix
  rev: v1.0.0
  hooks:
  - id: check-filename-prefix
    args:
    - "--prefix"
    - "my_prefix_"

Replace my_prefix_ with your desired prefix. And basically this should be enough to try it.

Try to run it

To run pre-commit, being in root directory (the directory with .pre-commit-config.yaml file) run the following command:

pre-commit run --all-files

As a result, you’ll see something like this in the good case:

Ensure filenames contain the required prefix.............................Passed

And some variation of this in the case of failure:

Ensure filenames contain the required prefix.............................Failed
- hook id: check-filename-prefix
- exit code: 1

Invalid file name: "new_file.txt". File names must start with "my_prefix_".

Couple of words about exit codes (as pre-commit will display it).

• 0: All filenames are valid
• 1: At least one filename is invalid
• 2: Missing required –prefix argument

Cool, but what if I need to only check files in a specific directory?

In this case, pre-commit config has special key - files. Here’s an example:

- repo: https://github.com/dunterov/check-filename-prefix
  rev: v1.0.0
  hooks:
  - id: check-filename-prefix
    args:
    - "--prefix"
    - "my_prefix_"
    files: ^my_dir/

This configuration scopes pre-commit to files inside my_dir only.

Right, but this directory already contains some file I want to exclude?

Also, not an issue. It’s possible to use an exclude configuration key:

- repo: https://github.com/dunterov/check-filename-prefix
  rev: v1.0.0
  hooks:
  - id: check-filename-prefix
    args:
    - "--prefix"
    - "my_prefix_"
    files: ^my_dir/
    exclude: ^my_dir2/myfile$

This configuration not only scopes pre-commit to files inside my_dir, but also configures pre-commit to exclude my_dir2/myfile from being processed by the hook.

You can combine those config keys or use them separatelly. Check the official pre-commit documentation for more details about regular expression suitable for exclude and files.

That’s a wrap! Feel free to use this small tool in your projects - and if you’d like to suggest improvements or fix something, don’t hesitate to open a pull request on the repository.

Take care!