is-git-clean

is-git-clean is a small, focused Node.js utility that answers a single question: is this Git directory clean or does it have uncommitted changes? It shells out to git status --porcelain and returns a boolean, so you can gate builds, releases, or scripts on a pristine working tree.

It offers both a promise-based API and a synchronous variant, accepts an optional target directory, and supports multimatch ignore patterns so specific files can be excluded from the dirtiness check. With a minimal dependency footprint, it slots easily into release tooling and CI scripts.

What You Get

• A promise-based isGitClean() that resolves to true when the working tree is clean
• A synchronous isGitClean.sync() variant returning a boolean directly
• Optional directory argument to check any repository path, not just the cwd
• multimatch-based ignore patterns to exclude specific files from the check
• A minimal, single-file implementation with a tiny dependency footprint

Common Use Cases

• Blocking a publish or release script unless the working tree is clean
• Guarding automated version bumps and tagging in CI pipelines
• Warning developers about uncommitted changes before a destructive operation
• Excluding generated or config files from a cleanliness check via ignore globs

Under The Hood

Architecture - The entire library is a single index.js module. It runs git status --porcelain via execa (async) or child_process.execFileSync (sync), then determines cleanliness by checking whether stdout is empty. When ignore options are supplied, a porcelain regex strips status prefixes and multimatch filters the file list against the provided globs. A normalizeArgs wrapper lets callers pass an options object in place of the directory argument.

Tech Stack - Node.js (engines >=0.10.0), CommonJS module. Runtime dependencies are execa for process execution, is-obj for argument normalization, and multimatch for glob filtering. Dev tooling uses ava for tests and xo for linting.

Code Quality - The code is concise and readable, sharing a filterIgnored helper between the async and sync paths. A test.js suite runs under ava with generated git fixtures (clean and not-clean directories). Error handling is minimal by design, delegating to git’s own behavior.

API Design - The public surface is intentionally tiny: a default export plus a .sync property, both accepting an optional directory and options. The flexible argument handling (options may replace dir) keeps common calls terse, and the boolean return value is trivial to consume.