git-stats/README.md

<!---------------------------------------------------------------------------->
<!-- STOP, LOOK & LISTEN!                                                   -->
<!-- ====================                                                   -->
<!-- Do NOT edit this file directly since it's generated from a template    -->
<!-- file, using https://github.com/IonicaBizau/node-blah                   -->
<!--                                                                        -->
<!-- If you found a typo in documentation, fix it in the source files       -->
<!-- (`lib/*.js`) and make a pull request.                                  -->
<!--                                                                        -->
<!-- If you have any other ideas, open an issue.                            -->
<!--                                                                        -->
<!-- Please consider reading the contribution steps (CONTRIBUTING.md).      -->
<!-- * * * Thanks! * * *                                                    -->
<!---------------------------------------------------------------------------->

![git-stats](http://i.imgur.com/Q7TQYHx.png)

# `$ git-stats` [![Donate now][donate-now]][paypal-donations]

Local git statistics, including a GitHub-like contributions calendars.

I'd be curious to see your calendar with all your commits. Ping me on Twitter ([**@IonicaBizau**](https://twitter.com/IonicaBizau)). :smile: Until then, here's my calendar:

![git-stats](http://i.imgur.com/LfLJAaE.png)

## Contents

 - [Installation](#installation)
 - [Catching the `git commit` command](#catching-the-git-commit-command)
   - [Using `git` hooks](#using-git-hooks)
   - [Overriding the `git` command](#overriding-the-git-command)
 - [Usage](#usage)
   - [Importing and deleting commits](#importing-and-deleting-commits)
   - [Importing all the commits from GitHub and BitBucket](#importing-all-the-commits-from-github-and-bitbucket)
   - [See the GitHub Contributions calendar](#see-the-github-contributions-calendar)
 - [Documentation](#documentation)
 - [How to contribute](#how-to-contribute)

## Installation

You can install the package globally and use it as command line tool:

```sh
# Install the package globally
npm i -g git-stats
# Initialize git hooks
curl -s https://raw.githubusercontent.com/IonicaBizau/git-stats/master/scripts/init-git-post-commit | bash
```

Then, run `git-stats --help` and see what the cli tool can do.

```sh
$ git-stats --help
git-stats --help
A GitHub-like contributions calendar, but locally, with all your git commits.

usage: git-stats [start] [end] [options] [data]

start:                    Optional start date
end:                      Optional end date

options:
  -v                      Displays version information.
  -h --help               Displays this help.
  --no-ansi               Doesn't use ANSI colors in the squares.
  --record <data>         Records a new commit. Don't use this unless you are
                          a mad scientist. If you are a developer, just use this
                          option as part of the module.
  --light                 Enable the light theme.

examples:
   git-stats # Displays your commit calendar
   git-stats -v
   git-stats -h
   git-stats --light # Light mode
   git-stats '1 January 2012' # All the commits from 1 January 2012, to now
   git-stats '1 January 2012' '31 December 2012' # All the commits from 2012

Your commit history is kept in the .git-stats, in your $HOME directory (~/)

Documentation can be found at https://github.com/IonicaBizau/git-stats
```

If you run `git-stats` to display graph on Windows, please use a terminal that can properly display ANSI colors.
Cygwin Terminal is known to work, while Windows Command Prompt and Git Bash do not.

### Importing and deleting commits
I know it's not nice to start your git commit calendar from scratch. That's why I
created a `git-stats-importer` that imports or deletes the commits from a repository.

Check it out here: https://github.com/IonicaBizau/git-stats-importer

The usage is simple:

```sh
# Install the importer tool
$ npm install -g git-stats-importer

# Go to the repository you want to import
$ cd path/to/my-repository

# Import the commits
$ git-stats-importer

# ...or delete them if that's a dummy repository
$ git-stats-importer --delete
```

### Importing all the commits from GitHub and BitBucket
Yes, you read correctly! That's also possible. I [built a tool for that too](https://github.com/IonicaBizau/repository-downloader)!

```sh
# Download the repository downloader
$ git clone https://github.com/IonicaBizau/repository-downloader.git

# Go to repository downloader
$ cd repository-downloader

# Install the dependencies
$ npm install

# Start downloading and importing
$ ./start
```
### See the GitHub Contributions calendar
There is a solution for that, too! :smile: It's called [`ghcal`](https://github.com/IonicaBizau/ghcal).

```sh
# Install ghcal
$ npm install -g ghcal

# Checkout my contributions
$ ghcal ionicabizau
```
For more detailed documentation, check out the repository: https://github.com/IonicaBizau/ghcal.

## Example

Here is an example how to use this package as library.

```js
// Dependencies
var GitStats = require("git-stats");

// Create the GitStats instance
var g1 = new GitStats();

// Display the ansi calendar
g1.ansiCalendar({
    theme: "DARK"
}, function (err, data) {
    console.log(err || data);
});

```

## Documentation

For full API reference, see the [DOCUMENTATION.md][docs] file.

## How to contribute
Have an idea? Found a bug? See [how to contribute][contributing].

## License
[KINDLY][license] © [Ionică Bizău][website]–The [LICENSE](/LICENSE) file contains
a copy of the license.

[license]: http://ionicabizau.github.io/kindly-license/?author=Ionic%C4%83%20Biz%C4%83u%20%3Cbizauionica@gmail.com%3E&year=2015
[contributing]: /CONTRIBUTING.md
[website]: http://ionicabizau.net
[docs]: /DOCUMENTATION.md
[paypal-donations]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=MG98D7NPFZ3MG
[donate-now]: http://i.imgur.com/jioicaN.png