README

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 new Repo 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, or null 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, or null 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.

git-tools

Usage no npm install needed!