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"
# => #<Repo>

Initialize a new repository:

git = require 'gift'

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

Initialize a new bare repository:

git = require 'gift'

git.init "path/to/bare/repo", true, (err, _repo) ->
  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>

Repo

Repo#path

String - The path to the repository.

Repo#commits([treeish, [limit, [skip, ]]]callback)

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

Repo#current_commit(callback)

Get the current commit.

The callback receives (err, commit).

Repo#tree([treeish]) => Tree

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

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

Repo#diff(commitA, commitB, [paths, ]callback)

Get the difference between the trees.

The callback receives (err, diffs).

Repo#identity(callback)

Get the commit identity for this repository.

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

Repo#identify(actor, callback)

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

The callback receives (err).

Repo#remotes(callback)

Get the repository's remotes.

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

Repo#remote_list(callback)

Get a list of the repository's remote names.

Get the string names of each of the remotes.

Repo#remote_add(name, url, callback)

Equivalent to git remote add <name> <url>.

Repo#remote_remove(name, callback)

Remove a remote.

Repo#remote_add_url(name, url, callback)

Equivalent to git remote set-url --add <name> <url>.

Repo#remote_set_url(name, url, callback)

Equivalent to git remote set-url <name> <url>.

Repo#remote_delete_url(name, url, callback)

Equivalent to git remote set-url --delete <name> <url>.

Repo#remote_fetch(name, [options, ]callback)

git fetch <name>

Repo#remote_push(name, [branch, options, ]callback)

git push <name>

with branch parameter specified: git push <name> <branch>

Repo#status([options, ]callback)

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.

Repo#ls_files([files, ]options, callback)

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

Repo#config(callback)

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

Repo#branches(callback)

callback receives (err, heads).

Repo#branch([branch, ]callback)

Get a branch.

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

Repo#create_branch(name, callback)

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

Repo#delete_branch(delete, force, callback)

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

Repo#merge(name, [options, ]callback)

git merge <name>

Repo#tags(callback)

Get a list of Tags.

Repo#create_tag(name, [options, ]callback)

Create a tab with the given name.

Repo#delete_tag(name, callback)

Delete the tag with the given name.

Repo#commit(message, [options, ]callback)

Commit some changes.

• message - String
• options -
  • all - Boolean
  • amend - Boolean
  • author - String that must match "Au thor Author [email protected]"
• callback - Receives (err).

Repo#add(files, callback)

git add <files>

Repo#remove(files, callback)

git rm <files>

Repo#checkout(treeish, [options], callback)

git checkout <treeish>

Checkout a branch/commit/...

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

Repo#checkoutFile([files, options, ]callback)

Checkout some files.

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

Repo#pull([[remote, ]branch, ]callback)

Pull a branch from remote.

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

Repo#sync([[remote, ]branch, ]callback)

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

Repo#reset([treeish, options, ]callback)

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

Commit#id

String - The commit's SHA.

Commit#parents

Commit[]

Commit#tree()

Tree - The commit's content tree.

Commit#author

Actor

Commit#authored_date

Date

Commit#committer

Actor

Commit#committed_date

Date

Commit#message

String

Commit#describe([refs, [first_parent, ]]callback)

• 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

Head#name

String

Head#commit

Commit

Tag

Tag#name

String

Tag#commit

Commit

Tag#message(callback)

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

Tag#tagger(callback)

The callback receives (err, actor).

Tag#tag_date(callback)

The callback receives (err, date).

Config

Config#items

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

Status

Status#clean

Boolean

Status#files

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

Actor#name

String

Actor#email

String

Actor#hash

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

Tree

Tree#id

String - SHA1

Tree#contents(callback)

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

Tree#blobs(callback)

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

Tree#trees(callback)

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

Tree#find(directory, callback)

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

Blob

Blob#id

String - SHA1

Blob#mode

String

Blob#data(callback)

• 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()

Blob#dataStream()

• 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

Submodule#id

String

Submodule#name

String

Submodule#mode

String

Submodule#url(callback)

Get the url the submodule points to.

License

See LICENSE.