node-git-tools
Tools for parsing data out of git repositories.
Support this project by donating on Gittip.
About
The goal of node-git-tools is to provide a set of tools that can be used to easily write custom git commands or other scripts that are tightly integrated with git.
I expect the API to grow over time and will happily entertain any feature requests. If there is anything you'd like added, just file an issue.
Installation
npm install git-tools
Usage
var Repo = require( "git-tools" );
var repo = new Repo( "path/to/repo" );
repo.authors(function( error, authors ) {
console.log( authors );
});
API
Repo.clone( options, callback )
Clones a repository and returns the new Repo
instance.
-
options
(Object): Options for cloning the repository.-
repo
(String): The repository to clone from. -
path
(String): The path to clone into. - extra: Additional options can be provided, as documented below.
-
-
callback
(Function;function( error, repo )
): Function to invoke after cloning the repository.-
repo
(Object): A newRepo
instance for the cloned repository.
-
This function accepts arbitrary options to pass to git clone
.
For example, to create a bare repository:
Repo.clone({
repo: "git://github.com/scottgonzalez/node-git-tools.git",
dir: "/tmp/git-tools",
bare: true
});
Or to create a repo with limited history:
Repo.clone({
repo: "git://github.com/scottgonzalez/node-git-tools.git",
dir: "/tmp/git-tools",
depth: 5
});
Repo.isRepo( path, callback )
Determines if the specified path is a git repository.
-
path
(String): The path to check. -
callback
(Function;function( error, isRepo )
): Function to invoke after determining if the path is a git repository.-
isRepo
(Boolean): Whether the path is a git repository.
-
Note: This is equivalent to creating a Repo
instance with path
and calling isRepo()
on the instance.
activeDays( [committish], callback )
Gets the number of active days (unique days of authorship). Includes activity by day, month, year, and the entire history.
-
committish
(String; default:"master"
): Committish range to analyze. -
callback
(Function;function( error, activeDays )
): Function to invoke after getting active days.-
activeDays
(Object): Summary of active days.
-
The activeDays
object has the following form:
{
activeDays: Number,
commits: Number,
dates: {
"YYYY-MM-DD": Number( commits ),
...
},
years: {
"YYYY": {
activeDays: Number,
commits: Number,
months: {
"M": {
activeDays: Number,
commits: Number,
days: {
"D": {
commits: Number
},
...
}
},
...
}
},
...
}
}
age( callback )
Gets the age of the repository.
-
callback
(Function;function( error, age )
): Function to invoke after getting the age.-
age
(String): The age of the repository.
-
authors( [committish], callback )
Gets all authors, sorted by number of commits.
-
committish
(String; default:"master"
): Committish range to analyze. -
callback
(Function;function( error, authors )
): Function to invoke after getting authors.-
authors
(Array): All authors, sorted by number of commits.
-
Each author object contains the following properties:
-
email
(String): Author's email address. -
name
(String): Author's name. -
commits
(Number): Number of commits. -
commitsPercent
(Number): Percentage of commits.
blame( options, callback )
Determine what revision and author last modified each line of a file.
-
options
(Object): Options for the blame.-
path
(String): The path to the file to run the blame for. -
committish
(String; default:"HEAD"
): Revision or range to blame against.
-
-
callback
(Function;function( error, blame )
): Function to invoke after blaming the file.-
blame
(Array): Commit information for each line.
-
Each blame item contains the following properties:
-
commit
: SHA of commit that most recently modified the line. -
boundary
: Boolean indicating whether the commit is a boundary for the range. -
path
: Path to the file at the time of the most recent modification to the line. -
lineNumber
: Line number within the file. -
content
: Contents of the line.
branches( callback )
Gets all branches in order of most recent commit.
-
callback
(Function;function( error, branches )
): Function to invoke after getting branches.-
branches
(Array): All branches, sorted by most recent commit date.
-
Each branch object contains the following properties:
-
name
(String): Branch name. -
sha
(String): SHA-1 of most recent commit. -
date
(Date): Author date of most recent commit. -
subject
(String): Subject (first line) of most recent commit. -
author
(Object): Author of most recent commit.-
email
(String): Author's email address. -
name
(String): Author's name.
-
config( name, callback )
Gets the value of a configuration option.
-
name
(String): The name of the configuration option. -
callback
(Function;function( error, value )
): Function to invoke after getting the configuration option.-
value
(String|null): The value for the configuration option, ornull
if no value is set.
-
currentBranch( callback )
Gets the name of the currently checked out branch, if any.
-
callback
(Function;function( error, branch )
): Function to invoke after getting the branch.-
branch
(String|null): Branch name, ornull
if in detached HEAD state.
-
describe( [options], callback )
Describes a committish.
-
options
(Object): Options for describing the committish.-
committish
(String): The committish to describe. Defaults to currently checked-out commit. - extra: Additional options can be provided, as documented below.
-
-
callback
(Function;function( error, description )
): Function to invoke after getting the description.-
description
(String): Description of the committish.
-
This function accepts arbitrary options to pass to git describe
.
For example, to get the long description:
Repo.describe({
long: true
}, function( err, description ) {
console.log( description );
});
isRepo( callback )
Determines if the specified path is a git repository.
-
callback
(Function;function( error, isRepo )
): Function to invoke after determining if the path is a git repository.-
isRepo
(Boolean): Whether the path is a git repository.
-
remotes( callback )
Gets all remote repositories.
-
callback
(Function;function( error, remotes )
): Function to invoke after getting the remotes.-
remotes
(Array): All remote repositories.
-
Each remote object contains the following properties:
-
name
(String): Remote name. -
url
(String): URL for the remote repository.
resolveCommittish( committish, callback )
Resolves a committish to a SHA1.
-
committish
(String): Any committish to resolve. -
callback
(Function;function( error, sha )
): Function to invoke after resolving the comittish.-
sha
: SHA1 of the resolved committish.
-
tags( callback )
Gets all tags in reverse chronological order.
Lightweight tags are sorted by author date and annotated tags are sorted by tagger date.
-
callback
(Function;function( error, tags )
): Function to invoke after getting tags.-
tags
(Array): All tags, sorted by date.
-
Each tag object contains the following properties:
-
name
(String): Tag name. -
sha
(String): SHA-1 for the tag. For lightweight tags, this is the SHA-1 of the commit. -
date
(Date): Author date for ligthweight tags, tagger date for annotated tags.
License
Copyright Scott González and other contributors. Released under the terms of the MIT license.