# node-git-2-json

> Simple tool to get a JSON from your git log. Inspired by @fabien0102/git2json

Latest version **1.10.0** (published 2022-10-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install node-git-2-json
pnpm add node-git-2-json
yarn add node-git-2-json
bun add node-git-2-json
```

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.10.0 |
| Published | 2022-10-31 |
| First published | 2022-07-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 25.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | mediatech15 |
| Maintainers | mediatech15 |
| Keywords | git, json, log, gitgraph |

## Links

- npm: https://www.npmjs.com/package/node-git-2-json
- Repository: https://gitlab.com/mediatech15/node-git-2-json
- Homepage: https://gitlab.com/mediatech15/node-git-2-json#readme
- Issues: https://gitlab.com/mediatech15/node-git-2-json/issues
- npm.io page: https://npm.io/package/node-git-2-json

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 1.10.0 (latest) — 2022-10-31
- 1.9.0 — 2022-10-30
- 1.8.0 — 2022-10-30
- 1.7.0 — 2022-10-30
- 1.2.1 — 2022-07-03
- 1.2.0 — 2022-07-03
- 1.1.0 — 2022-07-03

## README

# About
Simple tool to get a JSON from your git log. Inspired by @fabien0102/git2json

# Use-Cases
- gitgraph.js
- analytics
- repository history
- problem tracking

# Basic Usage
```typescript
import { generateJson } from 'node-git-2-json';

let json = await generateJson('path-to-repository');
```
By default your will be returned the entire history as a JSON string.

# Intermediate Usage
```typescript
// To return less history
let json = await generateJson('path-to-repository', 50);
// Returns only last 50 commits as JSON string

// To return a JS/TS Object
let json = await generateJson('path-to-repository', -1, 'Object');
// Returns all history as an Object
```
**Note**: If you need to specify all commits you can pass `-1` for all. 

**Note2**: The last `n` commits is across all branches not currently checked out branch.

# Advanced Usage
```typescript
let cleanOptions = {
	keys: [
		'body',
		'notes'
	]
}
let json = await generateJson('path-to-repository', -1, 'Object', cleanOptions);
// Returns an Object for the entire history and
// removes the "body" and "notes" keys from every commit

let cleanOptions = {
	sanitize: 'light'
}
let json = await generateJson('path-to-repository', -1, 'Object', cleanOptions);
// Returns an Object for the entire history and
// performs a light sanitize on strings known to contain problematic characters. 

let cleanOptions = {
	sanitize: 'heavy'
}
let json = await generateJson('path-to-repository', -1, 'Object', cleanOptions);
// Returns an Object for the entire history and
// performs a heavy sanitize on strings known to contain problematic characters. 
// Warning this is highly aggressive and basically removes all non-printable characters.

let cleanOptions = {
	sanitize: 'custom',
	sanitizeRule: /[0-9]/g,
	sanitizeReplace: '!'
}
let json = await generateJson('path-to-repository', -1, 'Object', cleanOptions);
// Returns an Object for the entire history and
// performs a custom sanitize on strings known to contain problematic characters. 
// This uses a regex supplied by the user and replacement string
// Will in this case replace every digit with !
```

# generateJson()

This is the only method needed in 95% of use. Helper functions are exported for extension but only needed if in specific use or modification is needed.

**Returns**: `string|Array<object>`

**Parameters**: `repo: string, count?: number, output?: 'JSON | Object', clean?: cleanOptsInterface`

|parameter|default|value|required|about|
|---|---|---|---|---|
|`repo`|N/A|`string`|yes|string of path to git repository (can be `./`)|
|`count`|`-1`|`int` (>-1)|no|number of commits in history to use. `-1` is all|
|`output`|`JSON`|`JSON`, `Object`|no|type of output to return|
|`clean`|`{}`|`cleanOptsInterface`|no|options for post-processing of data/cleaning|

# cleanOptsInterface

**type**: `object`

|key|type|notes|
|---|---|---|
|`keys`|`Array<string>`|top level keys in return data format|
|`sanitize`|`light\|heavy\|custom`| string for level of sanitization|
|`sanitizeRule`|`RegExp`|a global regex to use as replace filter for custom sanitize|
|`sanitizeReplace`|`string`|the replacement string for custom rule|

All options are optional but if you choose custom for `sanitize` then you will recieve an error if you dont provide `sanitizeRule` or `sanitizeReplace`

# git json format
```json
[
    {
        "refs": [
            "tag: 1.0.0-b.4",
            "origin/dvt.xyz"
        ],
        "hash": "4c106c65ef3a92e5760fe7379300f9478853f0f7",
        "hashAbbrev": "4c106c65",
        "tree": "2283acd8f4019a7119ac303ed882e5d32424b127",
        "treeAbbrev": "2283acd8",
        "parents": [
            "fe2c48aad4b85311b4a19958559687c70b596f63"
        ],
        "parentsAbbrev": [
            "fe2c48aa"
        ],
        "author": {
            "name": "user",
            "email": "user@email.com",
            "timestamp": 1656708382000
        },
        "committer": {
            "name": "user",
            "email": "user@email.com",
            "timestamp": 1656708382000
        },
        "subject": "jenkins-1.0.0-b.4 [ci skip]",
        "body": "",
        "notes": "",
        "stats": [
            {
                "additions": 1,
                "deletions": 1,
                "file": "package.json"
            },
            {
                "additions": 1,
                "deletions": 1,
                "file": "src/app/test/file.xyz"
            }
        ]
    },
    {}....
]
```

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