check-empty

A simple, dependency-free and intuitive pre-commit / prek hook, CLI, library, uv tool and GitHub Action conglomerate written in Python that makes sure selected files, even within directories, are empty according to as little filesystem stat calls as possible and clears them effectively with minimal I/O if specified. Supports CPython 3.6+, PyPy 7.0+, GraalPy 19.0+ out-of-the-box, and most likely every Python 3.6 runtime you can think of.

Quickstart

If using double-asterisk globbing in the CLI, make sure it is enabled:

shopt -s globstar

similarly for extglob:

shopt -s extglob

Without installation (just trying out the capabilities):

uvx check-empty -Q src/mylib/py.typed docs/.nojekyll static/.gitkeep some_dir **/*.lock

Installation

# uv
uv tool install check-empty # bare executable on PATH
uv pip install check-empty # if you want to import check_empty for programmatic usage

pip install check-empty # pip

Show the help with:

check-empty --help # or check-empty -h

Usage

All the snippets below are equivalent, assuming globstar is on.

Run the CLI:

check-empty -Q src/mylib/py.typed docs/.nojekyll static/.gitkeep some_dir **/*.lock

In Python:

from check_empty import check
import glob

a = ['src/mylib/py.typed', 'docs/.nojekyll', 'static/.gitkeep', 'some_dir']
a.extend(glob.iglob('**/*.lock', recursive=True))
check(a, verbosity=1)
# default verbosity is 2; in the command line, each -Q decreases it by 1 and
# each -V increases it by 1

As a pre-commit hook:

# .pre-commit-config.yaml
repos:
- repo: https://github.com/jonathandung/check-empty
  rev: v1.1.0 # repository version
  hooks:
    - id: check-empty # the hook
      args: # example list of arguments
        - -Q # flag to decrease output, applicable twice (shorthand for --quiet)
      files: ^src/mylib/py\.typed|docs/\.nojekyll|static/\.gitkeep|some_dir/.*|.*\.lock$
      # paths to files/directories to clear or keep empty as a single regular
      # expression (as per the somewhat restrictive pre-commit config schema),
      # relative to project root; absolute paths are possible but highly discouraged

equivalent in prek.toml format:

[[repos]]
repo = "https://github.com/jonathandung/check-empty"
rev = "v1.1.0"

[[repos.hooks]]
id = "check-empty"
args = ["-Q"]

[[repos.hooks.files]]
glob = [
  "src/mylib/py.typed",
  "docs/.nojekyll",
  "static/.gitkeep",
  "some_dir/**",
  "**/*.lock"
]

or (TOML 1.1+):

[[repos]]
repo = "https://github.com/jonathandung/check-empty"
rev = "v1.1.0"
hooks = [{
  id = "check-empty",
  args = ["-Q"],
  files = {
    glob = [
      "src/mylib/py.typed",
      "docs/.nojekyll",
      "static/.gitkeep",
      "some_dir/**",
      "**/*.lock"
    ]
  },
}]

As a GitHub Actions workflow step:

steps:
- uses: jonathandung/check-empty@v1.1.0 # the latest version on the GitHub Actions
  # marketplace; this step will fail and subsequent jobs will not run if any file is
  # not empty
  with:
    python-version: '3.14' # run the script on the latest stable Python version
    # Python down to 3.6 is supported but not recommended due to end-of-life
    quiet: true
    filenames: |
      src/mylib/py.typed
      docs/.nojekyll
      static/.gitkeep
      some_dir
    globs: '**/*.lock' # can also be an array of globs joined into a newline-delimited
    # multiline string, as above

Notes

1. If your file name starts with a hyphen, to avoid having it misinterpreted as a flag, use a command of the form check-empty -- -this_is_actually_a_file.txt.
2. Forward slashes can be used even on Windows, so there is no need to escape anything.
3. Glob patterns are supported on *nix only. If on Windows, use a shell like Git Bash.
4. The program does not recurse into archives, since identification of compressed archives would require reading the first few bytes of each file seen, which is error-prone and inefficient.

Development

If you wish to contribute to this project, you are more than welcome, but please remember to read the contributing guide. Tests are run with:

python -m test_check_empty # explicit
python -m unittest discover # alternative

at the project root.