Skip to content

Tiny tool to run commands for modified, staged, and committed files in a GIT repository.

License

Notifications You must be signed in to change notification settings

usmanyunusov/nano-staged

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Nano Staged

Tiny tool to run commands for modified, staged, and committed files in a GIT repository.
It helps speed up running of the tests, linters, scripts, and more.

Features

  • 📦 Small: 47kB (142x+ lighter than lint-staged).
  • 🥇 Single dependency (picocolors).
  • ☯️ Support multiple file states like staged, unstaged, last-commit, changed etc

Benchmarks

Benchmarks running time for 10 file:

$ node bench/running-time/index.js
- lint-staged 1.394 ms
+ nano-staged 0.968 ms

The space in node_modules including sub-dependencies:

$ node bench/size/index.js
Data from packagephobia.com
- lint-staged   6688 kB
+ nano-staged     47 kB

The performance results were generated on a MBP Late 2013, 2.3 GHz Intel Core i7 by running npm run bench in the library folder. See bench/running-time/index.js

Usage

Getting Started

  1. Install nano-staged:

    npm install --save-dev nano-staged
    

    or

    yarn add nano-staged -D
    
  2. Add the nano-staged section and the commands to your package.json:

    For example:

    "nano-staged": {
       "*.{js,ts}": "prettier --write",
       "*.css": ["stylelint", "eslint --fix"]
    },
  3. Run commands with Nano Staged:

    ./node_modules/.bin/nano-staged
    

    Nano Staged by default to run commands from the config for staged files.

Pre-commit Hook

You can use Nano Staged with a pre-commit tools to run it automatically before every commit.

Simple Git Hooks
  1. Install simple-git-hooks as a dev dependency:

    npm install simple-git-hooks --save-dev
    
  2. Add the simple-git-hooks section to your package.json and fill in the pre-commit:

    For example:

    "simple-git-hooks": {
       "pre-commit": "./node_modules/.bin/nano-staged"
    }
  3. Run the CLI script to update the git hooks with the commands from the config:

    npx simple-git-hooks
    
  4. To automatically have Git hooks enabled after install, edit package.json:

    "scripts": {
       "postinstall": "npx simple-git-hooks"
    }
Husky
  1. Install husky as a dev dependency:

    npm install husky --save-dev
    
  2. Enable Git hooks:

    npx husky install
    
  3. Add a command to a hook:

    npx husky add .husky/pre-commit "./node_modules/.bin/nano-staged"
    
  4. To automatically have Git hooks enabled after install, edit package.json:

    "scripts": {
       "postinstall": "npx husky install"
    }

Configuration

Nano Staged supports multiple ways to define config.

  1. nano-staged section in package.json:

    "nano-staged": {
       "*": "your-cmd",
       "*.ext": ["your-cmd", "your-cmd"]
    }
  2. or a separate .nano-staged.json, nano-staged.json or .nanostagedrc config file:

    {
      "*": "your-cmd",
      "*.ext": ["your-cmd", "your-cmd"]
    }
  3. or a more flexible .nano-staged.cjs or nano-staged.cjs config file to CommonJS modules:

    module.exports = {
      '*': 'your-cmd',
      '*.ext': ['your-cmd', 'your-cmd'],
    }
  4. or a more flexible .nano-staged.mjs or nano-staged.mjs config file to ECMAScript modules:

    export default {
      '*': 'your-cmd',
      '*.ext': ['your-cmd', 'your-cmd'],
    }
  5. or a more flexible .nano-staged.js or nano-staged.js config file:

    // package.json => "type": "module"
    export default {
      '*': 'your-cmd',
      '*.ext': ['your-cmd', 'your-cmd'],
    }
    
    // package.json => "type": "commonjs"
    module.exports = {
      '*': 'your-cmd',
      '*.ext': ['your-cmd', 'your-cmd'],
    }

Format priorities:

If there are multiple configuration files in the same directory, Nano Staged will only use one. The priority order is as follows:

  1. .nano-staged.js
  2. nano-staged.js
  3. .nano-staged.cjs
  4. nano-staged.cjs
  5. .nano-staged.mjs
  6. nano-staged.mjs
  7. .nano-staged.json
  8. nano-staged.json
  9. .nanostagedrc
  10. package.json

Config Function API:

JS config files may export export either a single function or an object:

export default (api) => {
  const jsFiles = api.filenames.filter((file) => path.extname(file) === '.js')

  return [`eslint --fix ${jsFiles.join(' ')}`, `prettier --write ${jsFiles.join(' ')}`]
}
export default {
  '*.js': (api) => `eslint --fix ${api.filenames.join(' ')}`,
}

The api object exposes:

api.filenames - working filenames

api.type - run type: staged, unstaged, diff

Command Line Interface

--config [<path>] or -c [<path>]

Path to file that contains your configuration object. The path should be either absolute or relative to the directory that your process is running from.

--unstaged or -u

Run commands from the config only for git unstaged files. Nano Staged by default uses only staged git files.

--diff [<ref1> <ref2>]

Run commands on files changed between the working tree and the index or a tree, on files changed between the index and a tree, files changed between two trees, or on files changed between two indexes (commit hashes).

--allow-empty

Will allow creating an empty commit.

Thanks

Special thanks to lint-staged. Some codes was borrowed from it.

Community

The Nano Staged community can be found on GitHub Discussions, where you can ask questions, voice ideas, and share your projects.