npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

git-is-clean

v3.0.4

Published

Check if the Git index and working tree are clean

Downloads

1,559

Readme

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.