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](https://packagephobia.com/result?p=nano-staged) (142x+ lighter than **lint-staged**).
- 🥇 **No dependencies**
- ☯️ **Support multiple file states like staged, unstaged, last-commit, changed etc**
## Benchmarks
Benchmarks running time for 10 file:
```diff
$ node bench/running-time/index.js
- lint-staged 1.394 ms
+ nano-staged 0.968 ms
```
The space in node_modules including sub-dependencies:
```diff
$ 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](https://github.com/usmanyunusov/nano-staged/blob/master/bench/running-time/index.js)
## Usage
### Getting Started
1. Install `nano-staged`:
```terminal
npm install --save-dev nano-staged
```
or
```terminal
yarn add nano-staged -D
```
2. Add the `nano-staged` section and the commands to your `package.json`:
For example:
```json
"nano-staged": {
"*.{js,ts}": "prettier --write",
"*.css": ["stylelint", "eslint --fix"]
},
```
3. Run commands with Nano Staged:
```terminal
./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:
```terminal
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:
```json
"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:
```terminal
npx simple-git-hooks
```
4. To automatically have Git hooks enabled after install, edit `package.json`:
```json
"scripts": {
"postinstall": "npx simple-git-hooks"
}
```
Husky
1. Install `husky` as a dev dependency:
```terminal
npm install husky --save-dev
```
2. Enable Git hooks:
```terminal
npx husky install
```
3. Add a command to a hook:
```terminal
npx husky add .husky/pre-commit "./node_modules/.bin/nano-staged"
```
4. To automatically have Git hooks enabled after install, edit `package.json`:
```json
"scripts": {
"postinstall": "npx husky install"
}
```
## Configuration
Nano Staged supports multiple ways to define config.
1. `nano-staged` section in `package.json`:
```json
"nano-staged": {
"*": "your-cmd",
"*.ext": ["your-cmd", "your-cmd"]
}
```
2. or a separate `.nano-staged.json`, `nano-staged.json` or `.nanostagedrc` config file:
```json
{
"*": "your-cmd",
"*.ext": ["your-cmd", "your-cmd"]
}
```
3. or a more flexible `.nano-staged.cjs` or `nano-staged.cjs` config file to CommonJS modules:
```js
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:
```js
export default {
'*': 'your-cmd',
'*.ext': ['your-cmd', 'your-cmd'],
}
```
5. or a more flexible `.nano-staged.js` or `nano-staged.js` config file:
```js
// 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:
```js
export default (api) => {
const jsFiles = api.filenames.filter((file) => path.extname(file) === '.js')
return [`eslint --fix ${jsFiles.join(' ')}`, `prettier --write ${jsFiles.join(' ')}`]
}
```
```js
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 []` or `-c []`
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 [ ]`
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.
#### `--quiet`
Shows only that work is done and errors occured.
#### `--bail`
Stop running commands after the first failure.
## Thanks
Special thanks to [lint-staged](https://github.com/okonet/lint-staged). Some codes was borrowed from it.
## Community
The Nano Staged community can be found on [GitHub Discussions](https://github.com/usmanyunusov/nano-staged/discussions), where you can ask questions, voice ideas, and share your projects.