pull-git-repo/README.md

utility methods for git repos using pull streams

# pull-git-repo

Wrap a module implementing the [abstract-pull-git-repo][] interface, adding
utility methods

## API

Below, `source(obj)` means returns a [readable stream][pull-stream] for objects of type `obj`

#### `Repo(repo): repo`

Mixin `pull-git-repo` methods into `repo`

#### `Repo.parseCommitOrTag(object): source({name, value})`

Read a git object and transform it into a stream of `{name, value}` properties,
as in `repo.readCommit` or `repo.readTag`.

#### `Repo.parseTree(object): source({id, mode, name})`

Read a tree and transform it into a stream of `{name, value}` properties.
`name` may be `id` for the tree object id, or `entry` for a file entry in the
tree.

#### `repo.getRefNames([pretty, ]cb(err, refs))

Get a repo's refs as an object.

- `pretty`: format ref type/prefix nicely
- `refs`: refs object, in format `{<type>: [name]}}`,
  where `type` is e.g. "heads" (or "Branches" if option `pretty` is set)

#### `repo.getSymRef(name[, short], cb(err, value))`

Get a symref of a repo.

- `name`: the symref to resolve. e.g. `"HEAD"`
- `short`: whether to shorten the value, e.g. from `"refs/heads/master"`
  to `"master"`.

- `value`: head pointed to by name. e.g. `"refs/heads/master"`

#### `repo.readCommit(rev): source({name, value})`

Read a commit. Returns a readable stream of objects for fields in the
commit.  The commit message is treated as a field of type `"title"` for the
first line, and a field of type `"body"` for the rest.

- `rev`: SHA1 hash of the commit to read, or a ref pointing to it
- `name`: name of a field, one of
    `["tree", "parent", "author", "committer", "body"]`
- `value`: string value of the field

#### `repo.readTag(rev): source({name, value})`

Read a tag. Returns a readable stream of objects for fields in the
tag.  The tag message is treated as a field of type `"title"` for the
first line, and a field of type `"body"` for the rest.

- `rev`: SHA1 hash of the tag to read, or a ref pointing to it
- `name`: name of a field, one of
    `["object", "type", "tag", "tagger", "title", "body"]`
- `value`: string value of the field

#### `repo.readTree(rev): source({id, mode, name})`

Get a tree and stream its entries

#### `repo.readDir(rev, path): source({id, mode, name})`

Stream entries from a tree down a given path

#### `repo.readLog(head): source(hash)`

Stream commit IDs of the repo, following the commit history backwards

- `head`: hash or rev of the commit from which to start reading history

#### `repo.resolveRef(name, cb(err, hash))`

Get the hash that a ref (or symref) points to. Errors if the ref is not found.

#### `repo.getRef(name, cb(err, object, id))`

Get a git object

- `name`: name of a branch, tag, or ref pointing to the object,
  or SHA1 of the object

#### `repo.getCommit(rev, cb(err, object, id))`

Get a commit object. If the object refered to by `rev` is a tag, get the commit
that it points to.

#### `repo.getTag(rev, cb(err, object))`

Get a tag object.

#### `repo.getTree(rev, cb(err, object))`

Get a tree object. If `rev` refers to a commit or tag, get the tree that it
points to.

#### `Repo.getCommitParsed(object, cb(err, commit))`

Read a commit object and parse it into a JSON object, as in
`repo.getCommitParsed`.

#### `repo.getCommitParsed(rev, cb(err, commit))`

Get a commit buffered and parsed into a JSON object

- `commit.id`: ID of the commit
- `commit.tree`: ID of the tree of the commit
- `commit.parents`: IDs of parent commits. There will be more than one if it is
  a merge commit.
- `commit.title`: first line of the commit message
- `commit.body`: text from the commit message following the first line and an
  optional blank line
- `commit.author`: `user` object for info about the commit author
- `commit.committer`: `user` object for info about the committer
- `commit.separateAuthor`: convenience value indicating the user or email in
  `commit.author` and `commit.committer` are different
- `commit.separateAuthorDate`: convenience value indicating
  `commit.author.date` and `commit.committer.date` are different

Example:

```js
{
  "parents": [
    "f7c37c43a136064e07328ee7501fad8ed7bcc4d6"
  ],
  "author": {
    "str": "root <root@localhost> 1455078653 -0500",
    "name": "root",
    "email": "root@localhost",
    "date": new Date(1455078653)
  },
  "committer": {
    "str": "root <root@localhost> 1455078653 -0500",
    "name": "root",
    "email": "root@localhost",
    "date": new Date(1455078653)
  },
  "body": "",
  "id": "9a385c1d6b48b7f472ac507a3ec08263358e9804",
  "tree": "68aba62e560c0ebc3396e8ae9335232cd93a3f60",
  "title": "Initial commit",
  "separateAuthor": false
}
```

#### `Repo.getTagParsed(object, cb(err, tag))`

Read a tag object and parse it into a JSON object

- `tag.id`: ID of the tag
- `tag.object`: ID of the tagged object
- `tag.type`: type of the tagged object
- `tag.tagger`: `user` object for info about the creator of the tag
- `tag.title`: first line of the tag message
- `tag.body`: text from the tag message following the first line and an
  optional blank line

#### `repo.getTagParsed(rev, cb(err, tag))`

Get a tag object and parse into a JSON object

#### `Repo.getTreeParsed(object, cb(err, tree))`

Read a tree object and parse it an object.

- `tree.id`: ID of the tree
- `tree.entries`: array of entries in the tree
  - `entry.id`: ID of the item object
  - `entry.mode`: permission mode of the file
  - `entry.name`: name of the file in the directory

#### `repo.getFile(rev, path, cb(err, {length, mode, read)`

Get a file from tree at the given path.

`length`: size of the file in bytes
`mode`: mode of the file, e.g. `"100644"`
`read`: readable stream of the file's contents

#### `repo.isCommitHash(str): bool`

[pull-stream]: https://github.com/dominictarr/pull-stream/
[abstract-pull-git-repo]: https://github.com/clehner/abstract-pull-git-repo

#### `repo.diffTrees(treeIds, recursive): source({key, values, diff})`

Get a diff of changed files between two trees

#### `Repo.diffTrees(repos, trees, recursive): source({key, values, diff})`

Get a diff of changed files between trees of possibly different repos

#### `Repo.getMergeBase(baseRepo, baseBranch, headRepo, headBranch, cb)`

Find a common ancestor commit of two commits/branches

#### `repo.getPack(heads, haves, [opts, ]cb(err, readPack))`

Build a packfile that includes objects reachable from heads and not reachable
from haves.

- `heads`: set of revs for head commits to include
- `haves`: set of revs of commits to not include
- `opts.verbosity`: git verbosity level. normal is 1, `-v` is 2, `-q` is 0
- `cb`: callback for a stream of packfile data

#### `repo.getFirstAvailableRev(timeout, cb): sink(rev)`

Pull revs into this sink, and it will try to retrieve them, and callback the
first one that resolves within the given timeout.

- `timeout`: milliseconds to wait for a rev before giving up on it
- `rev`: hash of an object to try to retrieve

## License

Copyright (c) 2016 Charles Lehner

Usage of the works is permitted provided that this instrument is
retained with the works, so that any entity that uses the works is
notified of this instrument.

DISCLAIMER: THE WORKS ARE WITHOUT WARRANTY.