# picklog

> Pickup the logs that you filter, so you can generation changelog from it.

Latest version **2.3.2** (published 2021-08-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install picklog
pnpm add picklog
yarn add picklog
bun add picklog
```

Provides the command `picklog`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.3.2 |
| Published | 2021-08-30 |
| First published | 2019-02-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=6.0.0 |
| Dependencies | 5 |
| Unpacked size | 227.4 KB |
| Known vulnerabilities | 0 (+6 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 2 |
| Author | BearJ |
| Maintainers | bearverygood |
| Keywords | changelog, git log, log, generate log |

## Links

- npm: https://www.npmjs.com/package/picklog
- Repository: https://github.com/BearJ/picklog
- Homepage: https://github.com/BearJ/picklog#readme
- Issues: https://github.com/BearJ/picklog/issues
- npm.io page: https://npm.io/package/picklog

## Dependencies (5)

- [ora](https://npm.io/package/ora.md) ^3.4.0
- [user](https://npm.io/package/user.md) 0.0.0
- [yargs](https://npm.io/package/yargs.md) ^13.2.4
- [simple-git](https://npm.io/package/simple-git.md) ^1.107.0
- [object.values](https://npm.io/package/object.values.md) ^1.1.0

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 2.3.2 (latest) — 2021-08-30
- 2.3.1 — 2021-08-18
- 2.3.0 — 2021-08-18
- 2.2.1 — 2020-03-12
- 2.2.0 — 2019-11-05
- 2.1.4 — 2019-09-26
- 2.1.3 — 2019-09-05
- 2.1.2 — 2019-09-03
- 2.1.1 — 2019-09-03
- 2.1.0 — 2019-09-03
- 2.0.1 — 2019-07-13
- 2.0.0 — 2019-07-12
- 1.2.3 — 2019-07-05
- 1.2.2 — 2019-05-22
- 1.2.1 — 2019-03-15
- … 13 more at https://npm.io/package/picklog/versions

## README

Picklog
====
[![npm version](https://img.shields.io/npm/v/picklog.svg)](https://www.npmjs.org/package/picklog)

根据你设置的filter，提取出你需要的log，从而生成changelog。可以生成`JSON`或`markdown`。

( Pickup the logs that you filter, so you can generation changelog from it. You can get `JSON` or `markdown` you want. )

### 快速上手 ( Usage )
```
$ npm install -g picklog
$ picklog init
$ picklog -o CHANGELOG.md
```
运行完 `picklog init` 后，会在你的项目下生成`.picklogrc.js`文件。你可以通过修改`.picklogrc.js`文件里的规则来控制changelog的生成。

( After running `picklog init`, it generator a file `.picklogrc.js` in your project. You can modify `.picklogrc.js` to control the rules to generator changelog. Scroll up to see more detail. )

### CLI
- **`init`**

  生成配置文件`.picklogrc.js` ( Generator a setting file `.picklogrc.js` )

  e.g: `picklog init`

- **`-w` or `--write`**

  把输出添加到指定文件 ( Append stdout to a file )

  e.g: `picklog -w CHANGELOG.md`

- **`-o` or `--overwrite`**

  把输出覆盖到指定文件 ( Overwrite stdout to a file )

  e.g: `picklog -o CHANGELOG.md`

- **`-l` or `--latest`**

  只获取距离上一次tag间的修改 ( Only pick latest changes after the last tag )

  e.g: `picklog -l -w CHANGELOG.md`


- **`-g` or `--gitLogArgs`**

  透传给`git log`的参数，以英文逗号分隔 ( Pass the arg to "git log". Splited by **comma** )

  e.g: `picklog -g v2.0.0 -w CHANGELOG.md`

- **`-c` or `--config`**

  指定配置文件，默认是`.picklogrc.js` ( Custom config file. Default ".picklogrc" )

  e.g: `picklog -c .picklogrc.dev.js`


### API
```javascript
const picklog = require('picklog');

picklog({
  latest: true, // The same as CLI '--latest'
  gitLogArgs: 'v2.0.0', // The same as CLI '--gitLogArgs'
}).then(function(markdownText){
  console.log(markdownText);
});
```


### .picklogrc.js

这是一个输出为json的demo。( Here is demo that the output is json. )

```javascript
module.exports = {
  filters: [
    {
      name: 'Features',
      regExp: /^(?:feat|add)/i,
    },
    {
      name: 'Bugfixes',
      regExp: /^fix/i,
    }
  ],
  parse(commits){
    return JSON.stringify(commits, null, 2);
  },
  tagFilter: /^v\d+\.\d+\.\d+$/, // Optional
};
```

| 参数 (Args) | 必填 (Required) | 说明 (Introduction) | 类型 (Type) |
| ------ | ------ | ------ | ------ |
| filters | Yes | 规定了选取log的正则，你也可以在output里获得它。( `filters` use regexp filter logs, you can alse get this in output. ) | Array |
| parse | Yes | 你可以对你过滤的logs进行解析的函数。参数`commits`的结构可看[这里](./test/getCommits/output.json)。( `parse` is the function that you can parse your output with the logs you filter. [Here](./test/getCommits/output.json) is the`commits` example. ) | Function |
| tagFilter | False | 规定了选取tag的正则。( `tagFilter` use regexp filter tag. ) | RegExp |


### 我想要Markdown ( I want Markdown )
如果你需要输出为markdown，你可以用以下的 `.picklogrc.js` 。( If you want markdown output, you can use `.picklogrc.js` like this: )

```javascript
module.exports = {
  filters: [
    {
      name: 'Features',
      regExp: /^(?:feat|add)/i,
    },
    {
      name: 'Bugfixes',
      regExp: /^fix/i,
    }
  ],
  parse(commits){
    let output = '';

    commits.forEach((log) => {
      let date = new Date(log.timestamp * 1000);
      date = `${date.getFullYear()}-${('0' + (date.getMonth() + 1)).substr(-2)}-${('0' + date.getDate()).substr(-2)}`;

      output += `### ${log.tag} (${date})\n\n`;

      log.results.forEach((result) => {
        result.commits.forEach((commit) => {
          output += `* ${commit.s}(${commit.h})\n`;
        });

        output += '\n';
      });

      output += '\n\n';
    });

    return output;
  },
  tagFilter: /^v\d+\.\d+\.\d+$/, // Optional
};
```

### 适配AngularJS推荐的Git Commit格式 ( AngularJS Git Commit Guidelines )

[AngularJS Git Commit Guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits)

```javascript
const origin = '<%= GitURL %>';
const comparePath = `${origin}/compare/`;
const commitPath = `${origin}/commit/`;

module.exports = {
  filters: [
    {
      name: 'Features',
      regExp: /^(?:feat|add)/i,
    },
    {
      name: 'Bugfixes',
      regExp: /^fix/i,
    }
  ],
  parse(commits){
    // RegExp.prototype.toJSON = RegExp.prototype.toString; // JSON.stringify会调用正则表达式的toJSON
    // return JSON.stringify(commits, null, 2); // output commits

    let output = '';

    commits.forEach((log) => {
      let date = new Date(log.timestamp * 1000);
      date = `${date.getFullYear()}-${('0' + (date.getMonth() + 1)).substr(-2)}-${('0' + date.getDate()).substr(-2)}`;

      let currentTag = log.tag || log.commits[0].h;
      let prevTag = log.previousTag || log.commits[log.commits.length - 1].h;
      output += `### [${currentTag}](${comparePath}${prevTag || ''}...${currentTag}) (${date})\n\n`;

      log.results.forEach((result) => {
        output += `#### ${result.filter.name}\n`;

        result.commits.forEach((commit) => {
          output += `* ${commit.s}([${commit.h}](${commitPath}${commit.h}))\n`;
        });

        output += '\n';
      });

      output += '\n\n';
    });

    return output;
  },
  tagFilter: /^v\d+\.\d+\.\d+$/, // Optional
};
```

---
_Source: https://npm.io/package/picklog · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._