# github-remote-blamer

> git blame using the GitHub API--no local copy of the repository needed

Latest version **0.1.1** (published 2018-08-17) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install github-remote-blamer
pnpm add github-remote-blamer
yarn add github-remote-blamer
bun add github-remote-blamer
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2018-08-17 |
| First published | 2018-08-17 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 23.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Aaron Silverman |
| Maintainers | zugwalt |
| Keywords | git, blame, github, remote |

## Links

- npm: https://www.npmjs.com/package/github-remote-blamer
- Repository: https://github.com/Footage-Firm/github-blame-remote
- Homepage: https://github.com/Footage-Firm/github-blame-remote#readme
- Issues: https://github.com/Footage-Firm/github-blame-remote/issues
- npm.io page: https://npm.io/package/github-remote-blamer

## Dependencies (2)

- [lodash](https://npm.io/package/lodash.md) ^4.17.10
- [node-github-graphql](https://npm.io/package/node-github-graphql.md) ^0.2.7

## Recent versions

- 0.1.1 (latest) — 2018-08-17

## README

# github-remote-blamer

`github-remote-blamer` is a package to remotely perform a [git blame](https://git-scm.com/docs/git-blame) for a git 
repository hosted on [GitHub](github.com). No local copy of the repository is needed.

## QuickStart

```javascript
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:
```sh
{ line: 7,
  oid: '8eb95ae57973b2cbe7778bc2e10450a380ca2efe',
  date: 2017-03-05T18:44:22.000Z,
  name: 'chainhelen',
  email: 'chainhelen@gmail.com' }
```


## Installation

Requires node version 8 or higher.

```sh
$ 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.

```javascript
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.

```javascript
blameInfo = blamer.blame('expressjs', 'express', '40e04ec7a6d365a7e083b0fdf7f9d2c7afc036a0', 'examples/auth/index.js', [23,24,26])
    .then(blameInfo => console.log(blameInfo));
```
Output:
```sh
[ { line: 23,
    oid: 'ca306eace1befc9d290cd5f79be8e6ba7c01b917',
    date: 2014-07-03T14:49:53.000Z,
    name: 'Douglas Christopher Wilson',
    email: 'doug@somethingdoug.com' },
  { line: 24,
    oid: 'ca306eace1befc9d290cd5f79be8e6ba7c01b917',
    date: 2014-07-03T14:49:53.000Z,
    name: 'Douglas Christopher Wilson',
    email: 'doug@somethingdoug.com' },
  { line: 26,
    oid: '0f24f715bad686beb591d194888ee0a45253f0f3',
    date: 2012-02-18T21:16:17.000Z,
    name: 'TJ Holowaychuk',
    email: 'tj@vision-media.ca' } ]
```

---
_Source: https://npm.io/package/github-remote-blamer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._