Gift ](https://www.npmjs.com/package/gift)

A simple Node.js wrapper for the Git CLI. The API is based on
Grit.

Tested in all stable versions of node.

  

Table of Contents

- Installation
- API
- Repo
- Commit
- Head
- Tag
- Config
- Status
- Actor
- Tree
- Blob
- Submodule
- License

Installation

This fork is now in the npm package repository. Install it like you would any other package:

$ npm install gift

API

For existing repositories:

git = require 'gift'

repo = git "path/to/repo"
# => #

Initialize a new repository:

git = require 'gift'

git.init "path/to/repo", (err, _repo) ->
repo = _repo
# => #

Initialize a new bare repository:

git = require 'gift'

git.init "path/to/bare/repo", true, (err, _repo) ->
repo = _repo
# => #

Clone a repository:

git = require 'gift'

git.clone "git@host:path/to/remote/repo.git", "path/to/local/clone/repo", depth, branch, (err, _repo) ->
repo = _repo
# => #

Repo

$3

String - The path to the repository.

$3

Get a list of commits.

* treeish - String (optional).
* limit - Integer (optional).
* skip - Integer (optional).
* callback - Function which receives (err, commits), where commits is
an Array of Commits.

Get the 10 most recent commits to master.

repo.commits (err, commits) ->

Or to a different tag or branch.

repo.commits "v0.0.3", (err, commits) ->

Limit the maximum number of commits returned (by default limit is 10).

repo.commits "master", 30, (err, commits) ->

Skip some (for pagination):

repo.commits "master", 30, 30, (err, commits) ->

Or get an unlimited number of commits (there could be a lot):

repo.commits "master", -1, (err, commits) ->

$3

Get the current commit.

The callback receives (err, commit).

$3

The Tree object for the treeish (which defaults to "master").

repo.tree().contents (err, children) ->
for child in children
console.log child.name

$3

Get the difference between the trees.

The callback receives (err, diffs).

$3

Get the commit identity for this repository.

The callback receives (err, actor), where actor is an Actor.

$3

Set your account's default identity for commits to this repository.

The callback receives (err).

$3

Get the repository's remotes.

Receives (err, remotes), where each remote is a Ref.

$3

Get a list of the repository's remote names.

Get the string names of each of the remotes.

$3

Equivalent to git remote add .

$3

Remove a remote.

$3

Equivalent to git remote set-url --add .

$3

Equivalent to git remote set-url .

$3

Equivalent to git remote set-url --delete .

$3

git fetch

$3

git push

with branch parameter specified:
git push

$3

Uses --porcelain to parse repository status in a way that is agnostic of system language.
options is a string of any other options you'd like to pass to the status command. For example, the -u option will list each file in an untracked directory rather than simply listing the directory itself.
The callback receives (err, status). See below for a definition of what status is.

$3

List out the files in the index and working tree. Optionally filtered by a given array of files (paths or filenames).

$3

git config parsed as a simple, one-level object. The callback receives (err, config).

$3

callback receives (err, heads).

$3

Get a branch.

* branch - The name of the branch to get. Defaults to the
currently checked out branch.
* callback - Receives (err, head).

$3

Create a new branch with name, and call the callback when complete
with an error, if one occurred.

$3

Delete the branch name, and call the callback with an error, if one occurred.

$3

git merge

$3

Get a list of Tags.

$3

Create a tab with the given name.

$3

Delete the tag with the given name.

$3

Commit some changes.

* message - String
* options -
- all - Boolean
- amend - Boolean
- author - String that must match "Au thor Author "
* callback - Receives (err).

$3

git add

$3

git rm

$3

git checkout

Checkout a branch/commit/...

* treeish - Branch or treeish to checkout.
* options -
- b - Boolean to create a new branch
* callback - Receives (err).

$3

Checkout some files.

* files - File(s) to checkout. Pass '.' or nothing to checkout all files.
* options -
- force - Boolean
* callback - Receives (err).

$3

Pull a branch from remote.

* remote - String (defaults to origin).
* branch - String (defaults to master).
* callback - Receives (err).

$3

Sync the current branch with the remote, keeping all local changes intact.

The following steps are carried out: stash, pull, push, stash pop. If there were no changes to stash, the last stash pop is not executed.

* remote - String (defaults to origin).
* branch - String (defaults to master).
* callback - Receives (err).

$3

Checkout files.

* treeish - The git object to reset to. Defaults to HEAD.
* options -
- soft - Boolean
- mixed - Boolean __default__
- hard - Boolean
- merge - Boolean
- keep - Boolean
* callback - Receives (err).

Commit

$3

String - The commit's SHA.

$3

Commit[]

$3

Tree - The commit's content tree.

$3

Actor

$3

Date

$3

Actor

$3

Date

$3

String

$3

* refs - String (all, tags, or null for default of unannotated tags).
* first_parent - Boolean (follow lineage or include all ancestry).
* callback - (err, description) (description is String).

Head

$3

String

$3

Commit

Tag

$3

String

$3

Commit

$3

The callback receives (err, message) (message is a String).

$3

The callback receives (err, actor).

$3

The callback receives (err, date).

Config

$3

Object - The keys are dotted precisely as the console output from git config. E.g., {'user.name': 'John Doe'}

Status

$3

Boolean

$3

Object - The keys are files, the values objects indicating whether or not
the file is staged, tracked, etc.

Each file has the following properties:

* type which translates to:

| _type_ | index | working tree |
| :--- | :-------: | :-----------:|
| A | added | - |
| M | modified | - |
| D | deleted | - |
| AM | added | modified |
| MM | modified | modified |
| AD | staged | deleted |
| MD | modified | deleted |

* staged - Boolean
* tracked - Boolean

Actor

$3

String

$3

String

$3

String - The MD5 hash of the actor's email. Useful for displaying
Gravatar avatars.

Tree

$3

String - SHA1

$3

* callback - Receives (err, children).
* children - An array of Blobs, Trees, and Submodules.

$3

* callback - Receives (err, child_blobs).
* children - [Blob]

$3

* callback - Receives (err, child_trees).
* children - [Tree]

$3

* directory - String
* callback - Receives (err, thing).

Blob

$3

String - SHA1

$3

String

$3

* callback - (err, data)

Warning: this method only returns the complete file up to 200k, which is the default
buffer size for running child_process.exec(). If the file you're reading is bigger than
that, or if you're not sure, you need to use dataStream()

$3

* returns - [dataStream, errorStream]

Returns streams for you to use to get the data.

Usage:

data = ""
[dataStream, _] = blob.dataStream()
dataStream.on 'data', (buf) ->
data += buf.toString()
.on 'end', ->
callback(data)

Submodule

$3

String

$3

String

$3

String

$3

Get the url the submodule points to.

License

See LICENSE.