# opt-cli
Execute CLI Statements based upon opt-in / out-out Rules.
[](http://npm.im/opt-cli)
[](https://travis-ci.org/ta2edchimp/opt-cli)
[](https://codecov.io/github/ta2edchimp/opt-cli)
[](https://david-dm.org/ta2edchimp/opt-cli#info=dependencies)
[](http://opensource.org/licenses/MIT)
[](http://npm-stat.com/charts.html?package=opt-cli&from=2016-03-20)
[](https://github.com/semantic-release/semantic-release)
[](http://makeapullrequest.com)
[](#contributors)
## Installation
Simply install locally as a development dependency to your project's package:
```
npm install --save-dev opt-cli
```
## Intended usage
Opting in/out of a configured tasks, **best use case is for ghooks**.
[This discussion](https://github.com/gtramontina/ghooks/issues/48#issuecomment-194002689) is the main motivation behind this module.
You can check out the [eslint-find-new-rules/package.json](https://github.com/kentcdodds/eslint-find-new-rules/blob/master/package.json#L67) for reference.
### `opt --in`
```JSON
"config": {
"ghooks": {
"pre-commit": "opt --in pre-commit --exec 'npm run validate'"
}
},
```
While `commit`ing, `npm run validate` **will not be executed** by default.
However, one can **opt in by creating a `.opt-in` file in the root of the project, with the content `pre-commit`**
#### `.opt-in`
Each line in the `.opt-in` file, is the keyword used after the `opt --in` rule.
So for the above example, it's `pre-commit`
```
cat .opt-in
# "ghooks": {
# "pre-commit": "opt --in pre-commit --exec 'npm run validate'"
# }
pre-commit # the keyword used after the opt --in command
```
### `opt --out`
`opt --out` works exactly, the opposite way of `opt --in`.
```JSON
"config": {
"ghooks": {
"pre-commit": "opt --out pre-commit --exec 'npm run validate'"
}
},
```
In this case, `npm run validate` **will be executed** before any changes can be `commit`ed.
In order to **opt out, you have to create a `.opt-out` file in the root of the project, with the content `pre-commit`**
#### `.opt-out`
Similar to `.opt-in` file, each line in `.opt-out` file, is the keyword used after the `opt --out` rule.
So for the above example, it's `pre-commit`
```
cat .opt-out
# "ghooks": {
# "pre-commit": "opt --out pre-commit --exec 'npm run validate'"
# }
pre-commit # the keyword used after the opt --out command
```
* **don't forget to update `.gitignore` to ignore this file.**
* `opt-in`, `opt-out` files can contain multiple rules
* every line must contain only a single rule.
* `#` can be used to comment any rule.
## Use As Library
You may also include opt-cli as a library:
```JavaScript
var opt = require( 'opt-cli' );
```
Given the example setup from above, usage would be as follows:
```JavaScript
opt.testOptIn( 'pre-commit' ) === true
opt.testOptOut( 'pre-push' ) === true
```
Using `opt.getExplicitOpts()` you would receive:
```JavaScript
{
'pre-commit': true,
'pre-push': false
}
```
## Advanced Usage
Rules to opt-into or opt-out of can also be specified using ...
- ... an `in` or `out` array of a `package.json`'s `config.opt` field:
```JSON
"config": {
"opt": {
"in": [ "pre-commit" ],
"out": [ "pre-push" ]
}
},
```
- ... the environment variables `OPT_IN` and `OPT_OUT`:
```
# Delimit multiple rules with ":" on *nix / ";" on Win
export OPT_IN="pre-commit"
export OPT_OUT="pre-push"
```
## Contributors
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
| [<img src="https://avatars3.githubusercontent.com/u/1500684?v=3" width="100px;"/><br /><sub>Kent C. Dodds</sub>](https://twitter.com/kentcdodds)<br />[💻](https://github.com/ta2edchimp/opt-cli/commits?author=kentcdodds) 👀 | [<img src="https://avatars2.githubusercontent.com/u/374635?v=3" width="100px;"/><br /><sub>Guilherme J. Tramontina</sub>](https://github.com/gtramontina)<br />[💻](https://github.com/ta2edchimp/opt-cli/commits?author=gtramontina) | [<img src="https://avatars1.githubusercontent.com/u/262436?v=3" width="100px;"/><br /><sub>Andreas Windt</sub>](https://twitter.com/ta2edchimp)<br />[💻](https://github.com/ta2edchimp/opt-cli/commits?author=ta2edchimp) [📖](https://github.com/ta2edchimp/opt-cli/commits?author=ta2edchimp) [⚠️](https://github.com/ta2edchimp/opt-cli/commits?author=ta2edchimp) | [<img src="https://avatars1.githubusercontent.com/u/949380?v=3" width="100px;"/><br /><sub>Sarbbottam Bandyopadhyay</sub>](https://twitter.com/sarbbottam)<br />[📖](https://github.com/ta2edchimp/opt-cli/commits?author=sarbbottam) | [<img src="https://avatars2.githubusercontent.com/u/22251956?v=4" width="100px;"/><br /><sub>Suhas Karanth</sub>](https://github.com/sudo-suhas)<br />[🐛](https://github.com/ta2edchimp/opt-cli/issues?q=author%3Asudo-suhas) [💻](https://github.com/ta2edchimp/opt-cli/commits?author=sudo-suhas) |
| :---: | :---: | :---: | :---: | :---: |
<!-- ALL-CONTRIBUTORS-LIST:END -->
This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)).
[Contributions of any kind welcome](CONTRIBUTING.md)!
Special thanks to [@kentcdodds](https://github.com/kentcdodds) for encouraging to engage in oss, for the wonderful resources (check out the [Egghead videos!](https://egghead.io/series/how-to-write-an-open-source-javascript-library)) and — together with [gtramontina](https://github.com/gtramontina) — for coming up with [the original idea to this module](https://github.com/gtramontina/ghooks/issues/48#issuecomment-194002689)!