gift
gift copied to clipboard
A wrapper for the Git CLI in Node.js
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)
, wherecommits
is anArray
ofCommit
s.
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 Tag
s.
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 toorigin
). -
branch
-String
(defaults tomaster
). -
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 toorigin
). -
branch
-String
(defaults tomaster
). -
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
, ornull
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 ofBlob
s,Tree
s, andSubmodule
s.
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.