gift/README.md

Gift

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

Tested in all stable versions of node.

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 author@nowhere.org"
• 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.