node-gitlog

Git log parser for Node.JS

Installation

npm install gitlog --save

Usage

const gitlog = require("gitlog").default;

const options = {
  repo: __dirname + "/test-repo-folder",
  number: 20,
  author: "Dom Harrington",
  fields: ["hash", "abbrevHash", "subject", "authorName", "authorDateRel"],
  execOptions: { maxBuffer: 1000 * 1024 },
};

// Synchronous
const commits = gitlog(options);
console.log(commits);

// Asynchronous (with Callback)
gitlog(options, function (error, commits) {
  // Commits is an array of commits in the repo
  console.log(commits);
});

const { gitlogPromise } = require("gitlog");

// Asynchronous (with Promise)
gitlogPromise(options)
  .then((commits) => console.log(commits))
  .catch((err) => console.log(err));

gitlog comes with full typescript support!

import gitlog, { GitlogOptions } from "gitlog";

// Option 1: Just use the function, returned commit type has specified fields
gitlog({
  repo: "foo",
  fields: ["subject", "authorName", "authorDate"],
});

// Option 2: Use Options type to create options
const options: GitlogOptions<"subject" | "authorName" | "authorDate"> = {
  repo: "foo",
  fields: ["subject", "authorName", "authorDate"],
};

gitlog(options);

// Option 3: Typescript Magic
const options = {
  repo: "foo",
  fields: ["subject", "authorName", "authorDate"] as const,
};

gitlog(options);

// NOT SUPPORTED: Without "as const" gitlog can't create a good return type
const options = {
  repo: "foo",
  fields: ["subject", "authorName", "authorDate"],
};

gitlog(options);

Options

See git log

repo

The location of the repo, required field.

number

The number of commits to return, defaults to 10.

since/after

Show commits more recent than a specific date.

until/before

Show commits older than a specific date.

author/committer

Limit the commits output to ones with author/committer header lines that match the specified pattern.

nameStatus

Below fields was returned from the log:

files - changed files names (array)
status - changed files status (array)

This option is enabled by default.

findCopiesHarder

Much more likely to set status codes to 'C' if files are exact copies of each other.

This option is disabled by default.

includeMergeCommitFiles

Pass the -m option to includes files in a merge commit.

This option is disabled by default.

all

Find commits on all branches instead of just on the current one.

This option is disabled by default.

branch (revision range)

Show only commits in the specified branch or revision range.

By default uses the current branch and defaults to HEAD (i.e. the whole history leading to the current commit).

fileLineRange

Optional field for getting only the commits that affected a specific line range of a given file.

file

Optional file filter for the git log command

execOptions

Type: Object

Specify some options to be passed to the .exec() method:

cwd String Current working directory of the child process
env Object Environment key-value pairs
setsid Boolean
encoding String (Default: 'utf8')
timeout Number (Default: 0)
maxBuffer Number (Default: 200*1024)
killSignal String (Default: 'SIGTERM')

optional fields

An array of fields to return from the log, here are the possible options:

hash - the long hash of the commit e.g. 7dd0b07625203f69cd55d779d873f1adcffaa84a
abbrevHash - the abbreviated commit hash e.g. 7dd0b07
treeHash - the tree hash of the commit
abbrevTreeHash - the abbreviated commit hash
parentHashes - the parent hashes
abbrevParentHashes - the abbreviated parent hashes
authorName - author name of the commit
authorEmail - author email of the commit
authorDate - author date of the commit
authorDateRel - relative author date of the commit
committerName - committer name
committerEmail - committer email
committerDate - committer date
committerDateRel - relative committer date
subject - commit message (first line)
body - commit body
rawBody - raw body (subject + body)
tag - raw tag information of commit

Defaults to 'abbrevHash', 'hash', 'subject' and 'authorName'.

How it works

This module works by executing a child process (using child_process.exec()) to the git executable, then parsing the stdout into commits. This is done using the --pretty command line option which allows you to provide a custom formatter to git log. To enable easy parsing the format is delimited by a tab (\t) character.

Example

The following is an example of what a parsed commit might look like.

{
  "hash": "6a7ef5e3b3d9c77743140443c8f9e792b0715721",
  "abbrevHash": "6a7ef5e",
  "treeHash": "f1bf51b15b48a00c33727f364afef695029864c0",
  "abbrevTreeHash": "f1bf51b",
  "parentHashes": "cfe06dbdb8d0a193640977e016a04678f8f3b04f",
  "abbrevParentHashes": "cfe06dbdb8d0a193640977e016a04678f8f3b04f",
  "authorName": "Dom Harrington",
  "authorEmail": "dom@harringtonxxxxx",
  "authorDate": "2015-04-09 09:39:23 +0100",
  "authorDateRel": "6 days ago",
  "committerName": "Dom Harrington",
  "committerEmail": "dom@harringtonxxxxx",
  "committerDate": "Thu Apr 9 09:39:23 2015 +0100",
  "committerDateRel": "6 days ago",
  "subject": "1.0.0",
  "status": ["M"],
  "files": ["package.json"]
}

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{domharrington} 💻 📖 💡 🤔	_{Andrew Lisowski} 💻 📖 🚇 🚧	_{Stefan Oderbolz} 🐛 💻	_palortoff 🐛 💻	_Malys 🐛 💻 📖	_{Mike Mellor} 💻	_{Hunter Medney} 💻
_{Peter Baranyi} 💻 🐛	_{Benjamin Blackwood} 📖	_{Ash Summers} 💻 ⚠️	_007design 💻	_{tobaccoplaybook} 💻	_Nicola 💻	_bluelovers 💻
_{Marwan Butrous} 💻	_FishOrBear 💻	_{Asjid Kalam} 💻	_{Jamie Slome} 💻	_huntr-helper 💻	_{Chris NeJame} 📖 ⚠️ 💻	_Ron ⚠️ 💻
_{Juan Ignacio Garzón} 📖 💻	_{Vitali Lovich} ⚠️ 💻