@tenedev/git-log

@tenedev/git-log

Parse and format git commit history with ease supporting filters for tags, dates, authors, and ranges

🪵 A lightweight git log parser & formatter for Node.js. Parse commit history into JSON, CSV, or Markdown — perfect for changelogs, release notes, or analytics. Supports filtering by tags, dates, authors, ranges, branches, and works efficiently with large repositories.

Install

pnpm add -D @tenedev/git-log
# or
npm install -D @tenedev/git-log
# or
yarn add -D @tenedev/git-log

Usage

CLI

npx @tenedev/git-log --help

CLI Examples

# Export commits since the last tag as pretty JSON
npx @tenedev/git-log --style json --pretty --output changelog.json

# Export commits as CSV with custom delimiter
npx @tenedev/git-log --style csv --delimiter ";" --output commits.csv

# Generate a Markdown table with commits since Jan 2024
npx @tenedev/git-log --style md --md-style table --since "2024-01-01" --output commits.md

# Show only commits by a specific author on main branch
npx @tenedev/git-log --author "Alice" --branch main --style json

# Limit to 5 commits in short format
npx @tenedev/git-log --fields shortHash,subject --limit 5

# Show full history (ignoring tags)
npx @tenedev/git-log --range all

Programmatic API

import getGitLog, {
  getLatestTag,
  getDefaultRange,
  GitField,
  LogOptions,
  FormatOptions,
} from '@tenedev/git-log';

// Example 1: commits since last tag in markdown
const log = getGitLog({
  fields: ['shortHash', 'author', 'date', 'subject'] as GitField[],
  style: 'md',
  mdStyle: 'table',
  range: { from: getLatestTag(), to: 'HEAD' },
  limit: 20,
});
console.log(log);

// Example 2: JSON logs across all history, custom date format
const jsonLog = getGitLog({
  fields: ['shortHash', 'formattedDate', 'subject'],
  style: 'json',
  pretty: true,
  range: 'all',
  dateFormat: 'DD-MM-YYYY',
});
console.log(jsonLog);

// Example 3: filter by author + date range
const filtered = getGitLog({
  fields: ['shortHash', 'author', 'date', 'subject'],
  style: 'csv',
  delimiter: ';',
  since: '2024-01-01',
  until: '2024-06-30',
  author: 'Bob',
});
console.log(filtered);

Options

LogOptions

Option	Type	Default	Description
fields	GitField[]	['hash','shortHash','author','email','date','subject','body']	Commit fields to include
limit	number | null	null	Limit number of commits
range	'all' | { from: string; to?: string }	{ from: latestTag, to: 'HEAD' }	Commit range ('all' = full log)
since	string	undefined	Filter commits since given date
until	string	undefined	Filter commits until given date
author	string	undefined	Filter commits by author name/mail
branch	string	"all"	Branch to scan commits from

FormatOptions

Option	Type	Default	Description
style	'json' | 'csv' | 'md'	'json'	Output format
delimiter	',' | ';'	','	CSV delimiter
mdStyle	'block' | 'table' | 'list'	'block'	Markdown rendering style
pretty	boolean	true	Pretty-print JSON
dateFormat	'YYYY-MM-DD' | 'DD-MM-YYYY' | 'MM-DD-YYYY'	'YYYY-MM-DD'	Custom format for formattedDate

GitField

• hash — full commit hash (40 chars)
• shortHash — short commit hash (7 chars)
• author — author name
• email — author email
• date — commit date (git log --date=iso8601)
• formattedDate — date formatted according to dateFormat
• subject — commit subject (first line)
• body — commit body (remaining lines)

Example Outputs

JSON

[
  {
    "shortHash": "a1b2c3d",
    "author": "Jane Doe",
    "date": "2024-08-10T12:00:00+00:00",
    "formattedDate": "10-08-2024",
    "subject": "feat: add new API endpoint"
  }
]

CSV

shortHash;author;date;subject
a1b2c3d;"Jane Doe";"2024-08-10T12:00:00+00:00";"feat: add new API endpoint"

Markdown (list)

- **shortHash**: a1b2c3d, **author**: Jane Doe, **subject**: feat: add new API endpoint

Edge cases:

• Empty repository → returns [] (JSON) or empty string (CSV/MD).
• If no tag exists → range falls back to 'all'.

License

Released under the Apache License 2.0.