{"_id":"@marionebl/conventional-commits-parser","_rev":"52960","name":"@marionebl/conventional-commits-parser","description":"Parse raw conventional commits","dist-tags":{"latest":"3.0.0"},"maintainers":[{"name":"marionebl","email":"root@mario-nebl.de"}],"time":{"modified":"2021-06-03T10:16:09.000Z","created":"2017-11-01T07:09:10.736Z","3.0.0":"2017-11-01T07:09:10.736Z"},"users":{},"author":{"name":"Steve Mao","email":"maochenyan@gmail.com","url":"https://github.com/stevemao"},"repository":{"type":"git","url":"git+https://github.com/conventional-changelog/conventional-commits-parser.git"},"versions":{"3.0.0":{"name":"@marionebl/conventional-commits-parser","version":"3.0.0","description":"Parse raw conventional commits","homepage":"https://github.com/conventional-changelog/conventional-commits-parser","author":{"name":"Steve Mao","email":"maochenyan@gmail.com","url":"https://github.com/stevemao"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/conventional-changelog/conventional-commits-parser.git"},"license":"MIT","files":["index.js","cli.js","lib"],"keywords":["conventional-commits-parser","changelog","conventional","parser","parsing","logs"],"dependencies":{"JSONStream":"^1.0.4","is-text-path":"^1.0.0","lodash":"^4.2.1","meow":"^3.3.0","split2":"^2.0.0","through2":"^2.0.0","trim-off-newlines":"^1.0.0"},"devDependencies":{"chai":"^3.0.0","concat-stream":"^1.4.7","istanbul":"^0.4.2","jscs":"^3.0.7","jshint":"^2.7.0","mocha":"*"},"scripts":{"lint":"jshint *.js lib test && jscs *.js lib test","test":"npm run lint && mocha --timeout=30000","test-windows":"echo 'make work on windows'"},"bin":{"conventional-commits-parser":"cli.js"},"bugs":{"url":"https://github.com/conventional-changelog/conventional-commits-parser/issues"},"_id":"@marionebl/conventional-commits-parser@3.0.0","_shasum":"9da29b4d2c8f05c0f9cdd02936713b8096c958d3","_from":".","_npmVersion":"2.15.11","_nodeVersion":"8.5.0","_npmUser":{"name":"marionebl","email":"hello@mario-nebl.de"},"dist":{"shasum":"9da29b4d2c8f05c0f9cdd02936713b8096c958d3","size":11110,"noattachment":false,"key":"/@marionebl/conventional-commits-parser/-/@marionebl/conventional-commits-parser-3.0.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/@marionebl/conventional-commits-parser/download/@marionebl/conventional-commits-parser-3.0.0.tgz"},"maintainers":[{"name":"marionebl","email":"root@mario-nebl.de"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/conventional-commits-parser-3.0.0.tgz_1509520149782_0.7084117149934173"},"directories":{},"publish_time":1509520150736,"_hasShrinkwrap":false,"_cnpm_publish_time":1509520150736}},"readme":"#  [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][daviddm-image]][daviddm-url] [![Coverage Status][coveralls-image]][coveralls-url]\n\n> Parse raw conventional commits\n\n\n## Conventional Commit Message Format\n\nA minimum input should contain a raw message.\n\nEach commit message consists of a **merge header**, a **header** (mandatory), a **body** and a **footer**. **Mention** (optional) someone using the `@` notation.\n\n```\n<merge>\n<header>\n<body>\n<footer>\n```\n\n### merge\n\nThe merge header may optionally have a special format that includes other parts, such as **branch**, **issueId** or **source**.\n\n```\nMerge branch <branch>\nMerge pull request <issue-id> from <source>\n```\n\n### header\n\nThe header may optionally have a special format that includes other parts, such as **type**, **scope** and **subject**. You could **reference** (optional) issues here.\n\n```\n<type>(<scope>): <subject>\n```\n\n### footer\n\nThe footer should contain any information about **Important Notes** (optional) and is also the place to **reference** (optional) issues.\n\n```\n<important note>\n<references>\n```\n\n### other parts\n\nThis module will only parse the message body. However, it is possible to include other fields such as hash, committer or date.\n\n```\nMy commit message\n-sideNotes-\nIt should warn the correct unfound file names.\nAlso it should continue if one file cannot be found.\nTests are added for these\n```\n\nThen `sideNotes` will be `It should warn the correct unfound file names.\\nAlso it should continue if one file cannot be found.\\nTests are added for these`. You can customize the `fieldPattern`.\n\n\n## Install\n\n```sh\n$ npm install --save conventional-commits-parser\n```\n\n\n## Usage\n\n```js\nvar conventionalCommitsParser = require('conventional-commits-parser');\n\nconventionalCommitsParser(options);\n```\n\nIt returns a transform stream and expects an upstream that looks something like this:\n\n```\n'feat(scope): broadcast $destroy event on scope destruction\\nCloses #1'\n'feat(ng-list): Allow custom separator\\nbla bla bla\\n\\nBREAKING CHANGE: some breaking change.\\nThanks @stevemao\\n'\n```\n\nEach chunk should be a commit. The downstream will look something like this:\n\n```js\n{ type: 'feat',\n  scope: 'scope',\n  subject: 'broadcast $destroy event on scope destruction',\n  merge: null,\n  header: 'feat(scope): broadcast $destroy event on scope destruction',\n  body: null,\n  footer: 'Closes #1',\n  notes: [],\n  references:\n   [ { action: 'Closes',\n       owner: null,\n       repository: null,\n       issue: '1',\n       raw: '#1',\n       prefix: '#' } ],\n  mentions: [],\n  revert: null }\n{ type: 'feat',\n  scope: 'ng-list',\n  subject: 'Allow custom separator',\n  merge: null,\n  header: 'feat(ng-list): Allow custom separator',\n  body: 'bla bla bla',\n  footer: 'BREAKING CHANGE: some breaking change.\\nThanks @stevemao',\n  notes:\n   [ { title: 'BREAKING CHANGE',\n       text: 'some breaking change.\\nThanks @stevemao' } ],\n  references: [],\n  mentions: [ 'stevemao' ],\n  revert: null }\n```\n\n\n## API\n\n### conventionalCommitsParser([options])\n\nReturns an transform stream. If there is any malformed commits it will be gracefully ignored (an empty data will be emitted so down stream can notice).\n\n#### options\n\nType: `object`\n\n##### mergePattern\n\nType: `regex` or `string` Default: null\n\nPattern to match merge headers. EG: branch merge, GitHub or GitLab like pull requests headers. When a merge header is parsed, the next line is used for conventionnal header parsing.\n\nFor example, if we have a commit\n\n```\nMerge pull request #1 from user/feature/feature-name\n\nfeat(scope): broadcast $destroy event on scope destruction\n```\n\nWe can parse it with these options and the default headerPattern:\n\n```js\n{\n  mergePattern: /^Merge pull request #(\\d+) from (.*)$/,\n  mergeCorrespondence: ['id', 'source']\n}\n```\n\n##### mergeCorrespondence\n\nType: `array` of `string` or `string` Default: null\n\nUsed to define what capturing group of `mergePattern`.\n\nIf it's a `string` it will be converted to an `array` separated by a comma.\n\n##### headerPattern\n\nType: `regex` or `string` Default: `/^(\\w*)(?:\\(([\\w\\$\\.\\-\\* ]*)\\))?\\: (.*)$/`\n\nUsed to match header pattern.\n\n##### headerCorrespondence\n\nType: `array` of `string` or `string` Default `['type', 'scope', 'subject']`\n\nUsed to define what capturing group of `headerPattern` captures what header part. The order of the array should correspond to the order of `headerPattern`'s capturing group. If the part is not captured it is `null`. If it's a `string` it will be converted to an `array` separated by a comma.\n\n##### referenceActions\n\nType: `array` of `string` or `string` Default:\n`[\n  'close',\n  'closes',\n  'closed',\n  'fix',\n  'fixes',\n  'fixed',\n  'resolve',\n  'resolves',\n  'resolved'\n]`\n\nKeywords to reference an issue. This value is case **insensitive**. If it's a `string` it will be converted to an `array` separated by a comma.\n\nSet it to `null` to reference an issue without any action.\n\n##### issuePrefixes\n\nType: `array` of `string` or `string` Default: `['#']`\n\nThe prefixes of an issue. EG: In `gh-123` `gh-` is the prefix.\n\n##### noteKeywords\n\nType: `array` of `string` or `string` Default: `['BREAKING CHANGE']`\n\nKeywords for important notes. This value is case **insensitive**. If it's a `string` it will be converted to an `array` separated by a comma.\n\n##### fieldPattern\n\nType: `regex` or `string` Default: `/^-(.*?)-$/`\n\nPattern to match other fields.\n\n##### revertPattern\n\nType: `regex` or `string` Default: `/^Revert\\s\"([\\s\\S]*)\"\\s*This reverts commit (\\w*)\\./`\n\nPattern to match what this commit reverts.\n\n##### revertCorrespondence\n\nType: `array` of `string` or `string` Default: `['header', 'hash']`\n\nUsed to define what capturing group of `revertPattern` captures what reverted commit fields. The order of the array should correspond to the order of `revertPattern`'s capturing group.\n\nFor example, if we had commit\n\n```\nRevert \"throw an error if a callback is passed\"\n\nThis reverts commit 9bb4d6c.\n```\n\nIf configured correctly, the parsed result would be \n\n```js\n{\n  revert: {\n    header: 'throw an error if a callback is passed',\n    hash: '9bb4d6c'\n  }\n}\n```\n\nIt implies that this commit reverts a commit with header `'throw an error if a callback is passed'` and hash `'9bb4d6c'`.\n\nIf it's a `string` it will be converted to an `array` separated by a comma.\n\n##### warn\n\nType: `function` or `boolean` Default: `function() {}`\n\nWhat warn function to use. For example, `console.warn.bind(console)` or `grunt.log.writeln`. By default, it's a noop. If it is `true`, it will error if commit cannot be parsed (strict).\n\n### conventionalCommitsParser.sync(commit, [options])\n\nThe sync version. Useful when parsing a single commit. Returns the result.\n\n#### commit\n\nA single commit to be parsed.\n\n#### options\n\nSame as the `options` of `conventionalCommitsParser`.\n\n\n## CLI\n\nYou can use cli to practice writing commit messages or parse messages from files. Note: the sample output might be different. It's just for demonstration purposes.\n\n```sh\n$ npm install --global conventional-commits-parser\n```\n\nIf you run `conventional-commits-parser` without any arguments\n\n```sh\n$ conventional-commits-parser\n```\n\nYou will enter an interactive shell. To show your parsed output enter \"return\" three times (or enter your specified separator).\n\n```sh\n> fix(title): a title is fixed\n\n\n{\"type\":\"fix\",\"scope\":\"title\",\"subject\":\"a title is fixed\",\"header\":\"fix(title): a title is fixed\",\"body\":null,\"footer\":null,\"notes\":[],\"references\":[],\"revert\":null}\n```\n\nYou can also use cli to parse messages from files.\n\nIf you have log.txt\n\n```text\nfeat(ngMessages): provide support for dynamic message resolution\n\nPrior to this fix it was impossible to apply a binding to a the ngMessage directive to represent the name of the error.\n\nBREAKING CHANGE: The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive.\n\nCloses #10036\nCloses #9338\n```\n\nAnd you run\n\n```sh\n$ conventional-commits-parser log.txt\n# or\n$ cat log.txt | conventional-commits-parser\n```\n\nAn array of json will be printed to stdout.\n\n```sh\n[\n{\"type\":\"feat\",\"scope\":\"ngMessages\",\"subject\":\"provide support for dynamic message resolution\",\"header\":\"feat(ngMessages): provide support for dynamic message resolution\",\"body\":\"Prior to this fix it was impossible to apply a binding to a the ngMessage directive to represent the name of the error.\",\"footer\":\"BREAKING CHANGE: The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive.\\nCloses #10036\\nCloses #9338\",\"notes\":[{\"title\":\"BREAKING CHANGE\",\"text\":\"The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive.\"}],\"references\":[{\"action\":\"Closes\",\"owner\":null,\"repository\":null,\"issue\":\"10036\",\"raw\":\"#10036\"},{\"action\":\"Closes\",\"owner\":null,\"repository\":null,\"issue\":\"9338\",\"raw\":\"#9338\"}],\"revert\":null}\n]\n```\n\nCommits should be split by at least three newlines (`\\n\\n\\n`) or you can specify a separator as the second argument.\n\nEg: in log2.txt\n\n```text\n\ndocs(ngMessageExp): split ngMessage docs up to show its alias more clearly\n===\n\nfix($animate): applyStyles from options on leave\n\nCloses #10068\n```\n\nAnd you run\n\n```sh\n$ conventional-commits-parser log2.txt '==='\n```\n\n```sh\n[\n{\"type\":\"docs\",\"scope\":\"ngMessageExp\",\"subject\":\"split ngMessage docs up to show its alias more clearly\",\"header\":\"docs(ngMessageExp): split ngMessage docs up to show its alias more clearly\",\"body\":null,\"footer\":null,\"notes\":[],\"references\":[],\"revert\":null}\n,\n{\"type\":\"fix\",\"scope\":\"$animate\",\"subject\":\"applyStyles from options on leave\",\"header\":\"fix($animate): applyStyles from options on leave\",\"body\":null,\"footer\":\"Closes #10068\",\"notes\":[],\"references\":[{\"action\":\"Closes\",\"owner\":null,\"repository\":null,\"issue\":\"10068\",\"raw\":\"#10068\"}],\"revert\":null}\n]\n```\n\nWill be printed out.\n\nYou can specify one or more files. The output array will be in order of the input file paths. If you specify more than one separator, the last one will be used.\n\n\n## License\n\nMIT © [Steve Mao](https://github.com/stevemao)\n\n\n[npm-image]: https://badge.fury.io/js/conventional-commits-parser.svg\n[npm-url]: https://npmjs.org/package/conventional-commits-parser\n[travis-image]: https://travis-ci.org/conventional-changelog/conventional-commits-parser.svg?branch=master\n[travis-url]: https://travis-ci.org/conventional-changelog/conventional-commits-parser\n[daviddm-image]: https://david-dm.org/conventional-changelog/conventional-commits-parser.svg?theme=shields.io\n[daviddm-url]: https://david-dm.org/conventional-changelog/conventional-commits-parser\n[coveralls-image]: https://coveralls.io/repos/conventional-changelog/conventional-commits-parser/badge.svg\n[coveralls-url]: https://coveralls.io/r/conventional-changelog/conventional-commits-parser\n","_attachments":{},"homepage":"https://github.com/conventional-changelog/conventional-commits-parser","bugs":{"url":"https://github.com/conventional-changelog/conventional-commits-parser/issues"},"license":"MIT"}