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

Tested in all stable versions of node.

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

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

$ npm install gift

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>

String - The path to the repository.

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

Get the current commit.

The callback receives (err, commit).

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

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

Get the difference between the trees.

The callback receives (err, diffs).

Get the commit identity for this repository.

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

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

The callback receives (err).

Get the repository's remotes.

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

Get a list of the repository's remote names.

Get the string names of each of the remotes.

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

Remove a remote.

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

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

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

git fetch <name>

git push <name>

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

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.

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

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

callback receives (err, heads).

Get a branch.

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

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

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

git merge <name>

Get a list of Tags.

Create a tab with the given name.

Delete the tag with the given name.

Commit some changes.

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

git add <files>

git rm <files>

git checkout <treeish>

Checkout a branch/commit/...

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

Checkout some files.

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

Pull a branch from remote.

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

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

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

String - The commit's SHA.

Commit[]

Tree - The commit's content tree.

Actor

Date

Actor

Date

String

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

String

Commit

String

Commit

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

The callback receives (err, actor).

The callback receives (err, date).

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

Boolean

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:

• staged - Boolean
• tracked - Boolean

String

String

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

String - SHA1

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

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

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

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

String - SHA1

String

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

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

String

String

String

Get the url the submodule points to.

See LICENSE.