# git-history-changelog

> changelog builder framework from git history

Latest version **0.1.5** (published 2018-01-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install git-history-changelog
pnpm add git-history-changelog
yarn add git-history-changelog
bun add git-history-changelog
```

## Health

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

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.5 |
| Published | 2018-01-27 |
| First published | 2018-01-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | morglod |
| Maintainers | morglod |
| Keywords | git, changelog, history, log, nodegit |

## Links

- npm: https://www.npmjs.com/package/git-history-changelog
- Repository: https://github.com/Morglod/git-history-changelog
- Homepage: https://github.com/Morglod/git-history-changelog#readme
- Issues: https://github.com/Morglod/git-history-changelog/issues
- npm.io page: https://npm.io/package/git-history-changelog

## Dependencies (3)

- [nodegit](https://npm.io/package/nodegit.md) ^0.20.3
- [@types/node](https://npm.io/package/@types/node.md) ^8.5.5
- [@types/nodegit](https://npm.io/package/@types/nodegit.md) ^0.18.5

## 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

- 0.1.5 (latest) — 2018-01-27
- 0.1.4 — 2018-01-27
- 0.1.3 — 2018-01-14
- 0.1.2 — 2018-01-09
- 0.1.1 — 2018-01-07
- 0.1.0 — 2018-01-07
- 0.0.4 — 2018-01-04
- 0.0.3 — 2018-01-04
- 0.0.2 — 2018-01-04
- 0.0.1 — 2018-01-04

## README

# git-history-changelog

Framework for writing changelog generation tools based on git history.

Uses [nodegit](http://www.nodegit.org/).

* Split commit messages to custom categories.
* By default all stages autosaves in local config (check Store object).
* You can provide your render and formatting methods.
* Framework care and track branches.

Please [contact me](mailto:morglod@gmail.com?Subject=npm%20git%20history%20changelog) if you use this library in your projects or for support and proposals.

## [Example result](src/example/package-history.ts)
```md
Branch: refs/heads/master, 2018-1-7 06:00:38  
  
# 0.1.0  
## example  
* package-history added  
## critical  
* Store now handles Git.Repository instance  
* openOrCreate now with repository path argument  
* filterParsedCommits renamed to formatParsedCommits  
## log  
* custom message types now passing through mapping/formatting methods  
## new  
* reduceUnreleasedCommits, groupEveryKeyByKeys methods added  

# 0.0.3  
## log  
* link fixed in readme  
* repo updated  

# 0.0.1  
## dev  
* readme added  
* example with categories  
## bugfix  
* second parse error fixed
```

## [Simple use](src/example/example.ts)

* 1. Pick untracked commits
* 2. Format commit messages from '{messageCategory}: message;'
* 3. Accept all filtered and mapped commits
* 4. Render all categories with default simple markdown renderer

```ts
const store = await Store.openOrCreate('./changelog.json', './', 'autosave');

// 1. Pick untracked commits
const parsedCommits = await parseUntrackedCommits(store);

// 2. Format commit messages from '{messageCategory}: message;'
const formatted = await formatParsedCommits(store, parsedCommits, (x) => {
    const messages = x.message.split(';').map(y => y.trim());
    const categorized: ChangelogMessages<string[]> = {};
    const defaultCategory = 'log';

    for (const msg of messages) {
        const [ category, text ] = msg.includes(':') ? msg.split(':') : [ defaultCategory, msg ];
        if (!(category in categorized))
            categorized[category] = [];
        categorized[category].push(text.trim());
    }

    return categorized;
});

// 3. Accept all filtered and mapped commits
const changelog = await toChangelog(store, formatted);

// 4. Render all categories with default simple markdown renderer
const rendered = renderChangelog(store, {
    entries: changelog,
    categories: 'all',
});

fs.writeFile('./changelog.md', rendered, 'utf8', err => {
    if (err) console.error(err);
    else console.log('ok');
});
```

Result for this repo:

```md
# example  
* package-history added  
# critical  
* Store now handles Git.Repository instance  
* openOrCreate now with repository path argument  
* filterParsedCommits renamed to formatParsedCommits  
# log  
* custom message types now passing through mapping/formatting methods  
```

## Future plans

* git tags extraction
* more examples
* ui

## Api

### [Store](src/store.ts)

Cache control object. Provide simple methods for saving and loading config.

Fields:
* `filename` - absolute path to config
* `data` - config, typeof [GitHistoryType](src/types.ts)
* `autosave` - flag, if true, framework will save config after every step
* `repo` - NodeGit.Repository instance

Methods:
* `static async openOrCreate(filename, repositoryPath, autoSave: false|'autosave'): Store` - open or create config and open repository
* `async clearChangelog()` - clear changelog (from last step)
* `async save(): true` - save config to `filename`

### [git](src/git.ts)

This methods care about git commits, branches etc.

```ts
async function parseUntrackedCommits(store: Store, {
    branchName?: string,
    onlyLastCommit?: boolean
}): ParsedHistoryCommit[]
```

Parse untracked commits with specified options.  
Returns new parsed commits.

* `branchName` - target git branch, (current by default)
* `onlyLastCommit` - track only last commit, skip others (track all by default)

```ts
async function fileContentBlob(
    store: Store,
    commitHash: string,
    filePath: string
): NodeGit.Blob

async function fileContentBuffer(
    store: Store,
    commitHash: string,
    filePath: string
): Buffer

async function fileContentString(
    store: Store,
    commitHash: string,
    filePath: string
): string
```

Read file by it's path from specified commit.  
* `filePath` - relative to repository root (eg 'package.json')

### [commits](src/commits.ts)

This methods care about commits filtering and messages extraction.

```ts
async function formatParsedCommits(
    store: Store,
    parsedCommits: ParsedHistoryCommit[],
    format: FormatFunc,
    onlyMarked?: false|'onlyMarked'
): UnreleasedChangelogCommit[]
```

Format & filter commit messages.

* `parsedCommits` - commits that will be formatted & filtered.
* `format` - filtering and extraction method (check [example](src/example/example.ts)).
* `onlyMarked: false|'onlyMarked'` - pick commits only with `commitToUnreleasedChangelog=true` (all by default)

```ts
async function reduceUnreleasedCommits(
    store: Store,
    unreleasedCommits: UnreleasedChangelogCommit[]
): UnreleasedChangelogCommit[]
```

Pick last commit for each listed branch,  
take all messages to last commit,  
group all messages by categories.

For better example, check [package-history example](src/example/package-history.ts).

### [changelog](src/changelog.ts)

This methods care about changelog entries and rendering.

```ts
async function toChangelog(
    store: Store,
    commits: UnreleasedChangelogCommit[]
): ChangelogEntry[]
```

Fixes specified commits as changelog entries.

```ts
async function renderChangelog(store: Store, {
    entries: ChangelogEntry[],
    categories: 'all'|string[],
    messageRenderer?: RenderChangelogMessageFunc,
    changelogRenderer?: RenderChangelogFunc
}): string
```

Renders changelog entries with specified renderers.  
By default it uses simple markdown renderers (check [source code](src/changelog.ts)).

Better use custom rendering method (check [package-history example](src/example/package-history.ts)).

### [utils](src/utils.ts)

```ts
function groupByKeys<T>(items: { [keyName: string]: T }[] )
    : { [keyName: string]: T[] };
```

Group every item's values by it's keys.  
Example:
```ts
groupByKeys([ { a: 1 }, { a: 2 } ]) -> { a: [ 1, 2 ] }
```

```ts
function groupEveryKeyByKeys<T>(
    item: { [keyA: string]: { [keyB: string]: T }<T>[] }
):
    { [keyA: string]: { [keyB: string]: T[] } }
```

Example:
```ts
groupEveryKeyByKeys({ x: [ { a: 1 }, { a: 2 } ] }) -> { x: { a: [ 1, 2 ] } }
```

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