git-is-clean

Check if a Git repository's index or working tree contains changes

Installation

1npm install git-is-clean

Or, run with npx:

1npx git-is-clean

Usage

CLI

Without any arguments, git-is-clean will exit with status 0 if there are no changes to either the Git index or the working tree, or status 1 if there are (if any errors occur, the program will exit with status 2).

From v2.0.0+, if the exit status is 1 a list of the files which caused the check to fail will be printed (a la git status --short). To prevent this use the --quiet or -q (or the alias option --silent).

1$ git status
2On branch master
3Changes not staged for commit:
4  (use "git add <file>..." to update what will be committed)
5  (use "git checkout -- <file>..." to discard changes in working directory)
6
7	modified:   index.js
8
9no changes added to commit (use "git add" and/or "git commit -a")
10$ git-is-clean
11 M index.js
12$ echo $?
131
14$ git checkout .
15$ git-is-clean
16$ echo $?
170

Ignoring certain file statuses

The behaviour can be customised to ignore one or more of staged, unstaged or untracked files:

1# Ignore any untracked files
2git-is-clean --ignore-untracked
3
4# Ignore any staged files
5git-is-clean --ignore-staged
6
7# Ignore any unstaged files
8git-is-clean --ignore-unstaged
9
10# Ignore any staged or unstaged files (ie only exit with status 1 if there are
11# untracked files in the working tree):
12git-is-clean --ignore-unstaged --ignore-staged

Only checking certain file statuses

Instead of specifying multiple --ignore-* options, you can use one of:

• --only-staged - equivalent to setting --ignore-untracked and --ignore-unstaged
• --only-unstaged: equivalent to setting --ignore-untracked and --ignore-staged
• --only-untracked: equivalent to setting --ignore-staged and --ignore-unstaged

Note that each of these options is mutually exclusive, and also imply that no extra --ignore-* options are set.

Checking a different Git directory

By default, Git commands will execute in the current working directory. Use the --dir (or just -d) option to check a different directory:

1git-is-clean --dir /tmp/my-repo

Including Git submodules

Submodules are ignored by default. To turn on submodule checking, pass the --include-submodules flag:

1$ git status
2On branch master
3Your branch is up-to-date with 'origin/master'.
4Changes not staged for commit:
5  (use "git add <file>..." to update what will be committed)
6  (use "git checkout -- <file>..." to discard changes in working directory)
7  (commit or discard the untracked or modified content in submodules)
8
9	modified:   path/to/submodule (modified content, untracked content)
10
11no changes added to commit (use "git add" and/or "git commit -a")
12$ git-is-clean; echo $?
130
14$ git-is-clean --include-submodules; echo $?
15 m path/to/submodule
161

Checking if Git is dirty instead of clean

For convenience, this package also ships a git-is-dirty binary which is identical to git-is-clean except with a flipped exit status:

1git-is-clean; echo $?
21
3git-is-dirty; echo $?
40

To run the git-is-dirty script through npx:

1npx --package git-is-clean git-is-dirty
2# OR:
3npx -p git-is-clean git-is-dirty

API

To use this is in other Node.js programs:

isClean(options: {}) => Promise<boolean>

Default export, which is a function that returns a Promise which resolves with a boolean value.

1const isClean = require('git-is-clean')
2
3isClean().then(clean => {
4  console.log('Repository is clean')
5})
6
7// Using async/await syntax
8;(async () => {
9  const clean = await isClean()
10
11  if (clean) {
12    /* ...snip... */
13  } else {
14    /* ...snip... */
15  }
16})()

Options are the same as the CLI program, just camel-cased instead of kebab-cased:

1isClean({
2  ignoreUntracked: true
3}).then(...)
4
5// Is equivalent to:
6// git-is-clean --ignore-untracked

getFiles(options: {}) => Promise<Array<{}>>

Returns the list of files that isClean() uses to determine cleanliness - if the resolved array is empty, the repository is clean.

When populated, each entry in the resolved array will have the following shape:

1{
2  path: 'path/to/file',
3  index: '<git status short format>',
4  workingTree: '<git status short format>',
5  isSubmodule: <boolean>
6}

For example, a tracked file with unstaged modifications would look like this:

1{
2  path: 'myfile.js',
3  index: '',
4  workingTree: 'M',
5  isSubmodule: false
6}

For a list of the short code statuses, see git-status short format.

When a submodule has been modified and is included in the output (includeSubmodules: true option), the modified status is a lowercase m, as per git status --short.

Again, options are the same as the CLI options except they are camel-cased instead of kebab-cased.

Debugging

Set the environment variable DEBUG to git-is-clean to debug the module:

1DEBUG=git-is-clean git-is-clean

See the documentation for the debug package for further debugging options.