github-remote-blamer

github-remote-blamer is a package to remotely perform a git blame for a git repository hosted on GitHub. No local copy of the repository is needed.

QuickStart

const GithubRemoteBlamer = require('github-remote-blamer');
const blamer = new GithubRemoteBlamer('MY_GITHUB_API_TOKEN');

const organization = 'expressjs';
const repository = 'express';
const oid = '40e04ec7a6d365a7e083b0fdf7f9d2c7afc036a0'; //GitHub Object ID; can be commit hash or branch name.
const path = 'examples/auth/index.js';
const lineNumber = 7;

blamer.blame(organization, repository, oid, path, lineNumber)
    .then(blameInfo => console.log(blameInfo));

Output:

{ line: 7,
  oid: '8eb95ae57973b2cbe7778bc2e10450a380ca2efe',
  date: 2017-03-05T18:44:22.000Z,
  name: 'chainhelen',
  email: '[email protected]' }

Installation

Requires node version 8 or higher.

$ npm install --save github-remote-blamer

Configuration

GithubRemoteBlamer's constructor takes two parameters:

• apiToken - Github api token with read access to the repository, users, and organization. This is required.
• options - an object with additional options. Currently debug is the only supported option. Set to true for additional debug statements.

const blamer = new GithubRemoteBlamer(myGitHubApiToken, {debug: true});

Usage

Parameters

GithubRemoteBlamer.blame() requires five parameters:

• organization - the GitHub organization which the respository being blamed belongs to.
• respository - the name of the repostiroy containing the file being blamed
• oid - the github object id for which version of the repository to blame. Can be a commit hash, or the name of a branch. If its the name of a branch, the latest version for that branch will be used.
• path - the path within the repository to the file being blamed
• lines - can be either a single integer representing the line to blame, or an array of integers to blame multiple lines in the same file.

Result

GithubRemoteBlamer.blame() returns a Promise that resolves to either a single object or an array of objects depending on whether or not you are blaming multiple lines. If blaming a single line, a single object is returned,. If blaming multiple lines, the array will have an object for each line, in order of the lines as they appear in the file.

blameInfo = blamer.blame('expressjs', 'express', '40e04ec7a6d365a7e083b0fdf7f9d2c7afc036a0', 'examples/auth/index.js', [23,24,26])
    .then(blameInfo => console.log(blameInfo));

Output:

[ { line: 23,
    oid: 'ca306eace1befc9d290cd5f79be8e6ba7c01b917',
    date: 2014-07-03T14:49:53.000Z,
    name: 'Douglas Christopher Wilson',
    email: '[email protected]' },
  { line: 24,
    oid: 'ca306eace1befc9d290cd5f79be8e6ba7c01b917',
    date: 2014-07-03T14:49:53.000Z,
    name: 'Douglas Christopher Wilson',
    email: '[email protected]' },
  { line: 26,
    oid: '0f24f715bad686beb591d194888ee0a45253f0f3',
    date: 2012-02-18T21:16:17.000Z,
    name: 'TJ Holowaychuk',
    email: '[email protected]' } ]