node-gitlog

Git log parser for Node.JS

Installation

 npm install gitlog2

breaking change

v5.x

• from v5.x change date format, and make authorDate/committerDate is same format (2019-01-06 04:54:09 +0800)
• support return unix timestamp, so u don't need worry about how to convert date format back to timestamp
• allow await when use callback mode, but remember u can't change return value when use callback
• add options.displayFilesChangedDuringMerge, can work perfect with options.firstParent

Usage

API

const gitlog = require('gitlog2').gitlog;

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

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

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

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.

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).

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)

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

  { 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',
    body: '',
    rawBody: '.\n',
    status: [ 'M' ],
    files: [ 'package.json' ],
    fileStatus: [ [ 'M', 'package.json' ] ]}