git-is-clean

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

Installation

npm install git-is-clean

Or, run with npx:

npx 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).

$ git status
On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   index.js

no changes added to commit (use "git add" and/or "git commit -a")
$ git-is-clean
 M index.js
$ echo $?
1
$ git checkout .
$ git-is-clean
$ echo $?
0

Ignoring certain file statuses

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

# Ignore any untracked files
git-is-clean --ignore-untracked

# Ignore any staged files
git-is-clean --ignore-staged

# Ignore any unstaged files
git-is-clean --ignore-unstaged

# Ignore any staged or unstaged files (ie only exit with status 1 if there are
# untracked files in the working tree):
git-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:

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

Including Git submodules

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

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)
  (commit or discard the untracked or modified content in submodules)

	modified:   path/to/submodule (modified content, untracked content)

no changes added to commit (use "git add" and/or "git commit -a")
$ git-is-clean; echo $?
0
$ git-is-clean --include-submodules; echo $?
 m path/to/submodule
1

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:

git-is-clean; echo $?
1
git-is-dirty; echo $?
0

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

npx --package git-is-clean git-is-dirty
# OR:
npx -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.

const isClean = require('git-is-clean')

isClean().then(clean => {
  console.log('Repository is clean')
})

// Using async/await syntax
;(async () => {
  const clean = await isClean()

  if (clean) {
    /* ...snip... */
  } else {
    /* ...snip... */
  }
})()

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

isClean({
  ignoreUntracked: true
}).then(...)

// Is equivalent to:
// 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:

{
  path: 'path/to/file',
  index: '<git status short format>',
  workingTree: '<git status short format>',
  isSubmodule: <boolean>
}

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

{
  path: 'myfile.js',
  index: '',
  workingTree: 'M',
  isSubmodule: false
}

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:

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

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

See also

• g-status: Underlying package used to get the list of staged/unstaged/untracked files.