git-stats/README.md

301 lines
11 KiB
Markdown
Raw Normal View History

2017-09-08 12:56:03 +02:00
<!-- Please do not edit this file. Edit the `blah` field in the `package.json` instead. If in doubt, open an issue. -->
2016-04-26 06:55:05 +02:00
2015-11-08 16:53:04 +01:00
[![git-stats](http://i.imgur.com/Q7TQYHx.png)](#)
2016-05-02 16:20:50 +02:00
# `$ git-stats`
2017-09-08 12:56:03 +02:00
[![Support me on Patreon][badge_patreon]][patreon] [![Buy me a book][badge_amazon]][amazon] [![PayPal][badge_paypal_donate]][paypal-donations] [![Ask me anything](https://img.shields.io/badge/ask%20me-anything-1abc9c.svg)](https://github.com/IonicaBizau/ama) [![Version](https://img.shields.io/npm/v/git-stats.svg)](https://www.npmjs.com/package/git-stats) [![Downloads](https://img.shields.io/npm/dt/git-stats.svg)](https://www.npmjs.com/package/git-stats)
2015-11-12 11:11:27 +01:00
2016-01-14 11:25:43 +01:00
> Local git statistics including GitHub-like contributions calendars.
2015-01-26 09:08:11 +01:00
2016-04-26 06:55:05 +02:00
2015-02-16 13:37:44 +01:00
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:
2015-02-09 14:39:24 +01:00
2015-11-08 16:53:04 +01:00
![](http://i.imgur.com/PpM0i3v.png)
2015-01-26 09:08:11 +01:00
2015-02-15 19:51:33 +01:00
## Contents
2015-02-15 19:52:44 +01:00
- [Installation](#installation)
- [Usage](#usage)
2016-04-26 06:55:05 +02:00
2015-11-08 16:53:04 +01:00
- [Importing and deleting commits](#importing-and-deleting-commits)
- [Importing all the commits from GitHub and BitBucket](#importing-all-the-commits-from-github-and-bitbucket)
- [What about the GitHub Contributions calendar?](#what-about-the-github-contributions-calendar)
2017-03-23 16:16:15 +01:00
- [Documentation](#documentation)
2015-02-15 19:52:44 +01:00
- [How to contribute](#how-to-contribute)
2015-02-15 19:51:33 +01:00
2017-03-23 16:16:15 +01:00
2016-04-26 06:55:05 +02:00
## :cloud: Installation
2015-01-26 09:08:11 +01:00
You can install the package globally and use it as command line tool:
2015-02-11 19:07:10 +01:00
2016-05-02 06:23:16 +02:00
2016-05-02 16:06:49 +02:00
```sh
# Install the package globally
2015-12-08 09:02:23 +01:00
npm i -g git-stats
# Initialize git hooks
2015-09-14 23:54:00 +02:00
# This is for tracking the new commits
2015-02-11 19:08:49 +01:00
curl -s https://raw.githubusercontent.com/IonicaBizau/git-stats/master/scripts/init-git-post-commit | bash
2015-02-11 19:07:10 +01:00
```
2015-11-08 16:53:04 +01:00
Then, run `git-stats --help` and see what the CLI tool can do.
2015-02-09 13:36:44 +01:00
2016-04-26 06:55:05 +02:00
```
2015-11-08 16:53:04 +01:00
$ git-stats --help
2015-09-21 20:07:58 +02:00
Usage: git-stats [options]
2016-10-23 11:05:22 +02:00
Local git statistics including GitHub-like contributions calendars.
2015-09-21 20:07:58 +02:00
Options:
2016-10-23 11:05:22 +02:00
-r, --raw Outputs a dump of the raw JSON data.
--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.
2016-04-26 06:55:05 +02:00
-s, --since <date> Optional start date.
-u, --until <date> Optional end date.
2016-10-23 11:05:22 +02:00
-g, --global-activity Shows global activity calendar in the current
repository.
-n, --disable-ansi Forces the tool not to use ANSI styles.
2016-04-26 06:55:05 +02:00
-l, --light Enables the light theme.
2016-10-23 11:05:22 +02:00
-d, --data <path> Sets a custom data store file.
2016-04-26 06:55:05 +02:00
-a, --authors Shows a pie chart with the author related
contributions in the current repository.
-h, --help Displays this help.
-v, --version Displays version information.
2015-09-21 20:07:58 +02:00
Examples:
2016-10-23 11:05:22 +02:00
$ git-stats # Default behavior (stats in the last year)
$ git-stats -l # Light mode
$ git-stats -s '1 January 2012' # All the commits from 1 January 2012 to now
$ git-stats -s '1 January 2012' -u '31 December 2012' # All the commits from 2012
2015-09-21 20:07:58 +02:00
2016-10-23 11:05:22 +02:00
Your commit history is kept in ~/.git-stats by default. You can create
~/.git-stats-config.json to specify different defaults.
2015-09-21 20:07:58 +02:00
2016-10-23 11:05:22 +02:00
Documentation can be found at https://github.com/IonicaBizau/git-stats.
2015-02-09 14:11:53 +01:00
```
2015-09-21 20:49:43 +02:00
## Usage
2015-02-09 14:11:53 +01:00
### Importing and deleting commits
2015-11-08 16:53:04 +01:00
I know it's not nice to start your git commit calendar from scratch. That's why I created [`git-stats-importer`](https://github.com/IonicaBizau/git-stats-importer)a tool which imports or deletes the commits from selected repositories.
2015-02-09 14:11:53 +01:00
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
2015-11-08 16:53:04 +01:00
2015-09-14 23:54:00 +02:00
Yes, that's also possible. I [built a tool which downloads and then imports all the commits you have pushed to GitHub and BitBucket](https://github.com/IonicaBizau/repository-downloader)!
2015-02-09 14:11:53 +01:00
```sh
# Download the repository downloader
$ git clone https://github.com/IonicaBizau/repository-downloader.git
2015-02-09 14:11:53 +01:00
# Go to repository downloader
$ cd repository-downloader
# Install the dependencies
$ npm install
# Start downloading and importing
$ ./start
```
2015-09-14 23:54:00 +02:00
### What about the GitHub Contributions calendar?
2015-11-08 16:53:04 +01:00
2015-09-14 23:54:00 +02:00
If you want to visualize the calendars that appear on GitHub profiles, you can do that using [`ghcal`](https://github.com/IonicaBizau/ghcal).
2015-02-09 14:39:24 +01:00
```sh
# Install ghcal
$ npm install -g ghcal
2015-09-14 23:54:00 +02:00
# Check out @alysonla's contributions
$ ghcal -u alysonla
2015-02-09 14:39:24 +01:00
```
2015-09-14 23:54:00 +02:00
2015-02-15 19:20:49 +01:00
For more detailed documentation, check out the repository: https://github.com/IonicaBizau/ghcal.
2015-02-09 14:39:24 +01:00
2015-10-10 18:58:46 +02:00
If want to get even more GitHub stats in your terminal, you may want to try [`github-stats`](https://github.com/IonicaBizau/github-stats)--this is like `git-stats` but with data taken from GitHub.
2015-09-14 23:54:00 +02:00
## Using the configuration file
2015-11-08 16:53:04 +01:00
You can tweak the git-stats behavior using a configuration file in your home directory: `~/.git-stats-config.js`.
2015-09-14 23:54:00 +02:00
This file should export an object, like below (defaults are listed):
2015-09-14 23:54:00 +02:00
```js
module.exports = {
2015-09-14 23:54:00 +02:00
// "DARK", "LIGHT" or an object interpreted by IonicaBizau/node-git-stats-colors
"theme": "DARK"
// The file where the commit hashes will be stored
, "path": "~/.git-stats"
// First day of the week
, first_day: "Sun"
// This defaults to *one year ago*
// It can be any parsable date
, since: undefined
// This defaults to *now*
// It can be any parsable date
, until: undefined
// Don't show authors by default
// If true, this will enable the authors pie
, authors: false
// No global activity by default
// If true, this will enable the global activity calendar in the current project
, global_activity: false
2015-11-01 11:40:47 +01:00
};
2015-09-14 23:54:00 +02:00
```
Since it's a js file, you can `require` any other modules there.
## Saving the data as HTML and images
`git-stats --raw` outputs raw JSON format which can be consumed by other tools to generate results such as HTML files or images.
[`git-stats-html`](https://github.com/IonicaBizau/git-stats-html) interprets the JSON data and generates an HTML file. Example:
```sh
# Install git-stats-html
npm install -g git-stats-html
# Export the data from the last year (generate out.html)
git-stats --raw | git-stats-html -o out.html
# Export data since 2015 (save the results in out.html)
git-stats --since '1 January 2015' --raw | ./bin/git-stats-html -o out.html --big
```
After we have the HTML file, we can generate an image file using [`pageres`](https://github.com/sindresorhus/pageres) by [**@sindresorhus**](https://github.com/sindresorhus/):
```sh
# Install pageres
npm install -g pageres-cli
# Generate the image from HTML
pageres out.html 775x250
```
2015-09-14 23:54:00 +02:00
## Cross-platform compatibility
`git-stats` is working fine in terminal emulators supporting ANSI styles. It should work fine on Linux and OS X.
If you run `git-stats` to display graph on Windows, please use a terminal that can properly display ANSI colors.
2015-11-08 16:53:04 +01:00
2015-09-14 23:54:00 +02:00
Cygwin Terminal is known to work, while Windows Command Prompt and Git Bash do not. Improvements are more than welcome! :dizzy:
2016-04-26 06:55:05 +02:00
## :clipboard: Example
2015-01-26 09:08:11 +01:00
2015-11-08 16:53:04 +01:00
Here is an example how to use this package as library. To install it locally, as library, you can do that using `npm`:
```sh
2015-12-03 14:02:50 +01:00
$ npm i --save git-stats
2015-11-08 16:53:04 +01:00
```
2015-01-26 09:08:11 +01:00
2016-04-26 06:55:05 +02:00
```js
// Dependencies
var GitStats = require("git-stats");
2015-02-09 14:14:10 +01:00
// Create the GitStats instance
var g1 = new GitStats();
2015-01-26 09:08:11 +01:00
// Display the ansi calendar
g1.ansiCalendar({
theme: "DARK"
}, function (err, data) {
console.log(err || data);
});
```
2015-02-09 14:14:10 +01:00
2017-09-08 12:56:03 +02:00
2017-03-23 16:16:15 +01:00
## :question: Get Help
There are few ways to get help:
1. Please [post questions on Stack Overflow](https://stackoverflow.com/questions/ask). You can open issues with questions, as long you add a link to your Stack Overflow question.
2. For bug reports and feature requests, open issues. :bug:
2017-09-08 12:56:03 +02:00
3. For direct and quick help, you can [use Codementor](https://www.codementor.io/johnnyb). :rocket:
2017-03-23 16:16:15 +01:00
2016-04-26 06:55:05 +02:00
## :memo: Documentation
2015-02-09 14:14:10 +01:00
For full API reference, see the [DOCUMENTATION.md][docs] file.
2015-02-09 14:14:10 +01:00
2016-04-26 06:55:05 +02:00
## :newspaper: Press Highlights
2015-11-08 16:53:04 +01:00
- [*A GitHub-like contributions calendar, but locally, with all your git commits*, The Changelog](https://changelog.com/github-like-contributions-calendar-locally-git-commits/)
2017-03-23 16:16:15 +01:00
2016-04-26 06:55:05 +02:00
## :yum: How to contribute
Have an idea? Found a bug? See [how to contribute][contributing].
2015-01-26 09:08:11 +01:00
2016-10-11 15:32:20 +02:00
2017-03-20 18:18:24 +01:00
## :sparkling_heart: Support my projects
I open-source almost everything I can, and I try to reply everyone needing help using these projects. Obviously,
this takes time. You can integrate and use these projects in your applications *for free*! You can even change the source code and redistribute (even resell it).
2016-10-10 20:37:05 +02:00
2017-03-20 18:18:24 +01:00
However, if you get some profit from this or just want to encourage me to continue creating stuff, there are few ways you can do it:
2016-10-10 20:37:05 +02:00
2017-03-20 18:18:24 +01:00
- Starring and sharing the projects you like :rocket:
2017-09-08 12:56:03 +02:00
- [![Buy me a book][badge_amazon]][amazon]—I love books! I will remember you after years if you buy me one. :grin: :book:
2017-03-20 18:18:24 +01:00
- [![PayPal][badge_paypal]][paypal-donations]—You can make one-time donations via PayPal. I'll probably buy a ~~coffee~~ tea. :tea:
- [![Support me on Patreon][badge_patreon]][patreon]—Set up a recurring monthly donation and you will get interesting news about what I'm doing (things that I don't share with everyone).
- **Bitcoin**—You can send me bitcoins at this address (or scanning the code below): `1P9BRsmazNQcuyTxEqveUsnf5CERdq35V6`
![](https://i.imgur.com/z6OQI95.png)
2016-10-10 20:37:05 +02:00
Thanks! :heart:
2017-03-20 18:18:24 +01:00
2016-04-26 06:55:05 +02:00
## :dizzy: Where is this library used?
2015-11-08 16:53:04 +01:00
If you are using this library in one of your projects, add it in this list. :sparkles:
2017-01-15 19:14:45 +01:00
- [`git-stats-fcc-importer`](https://github.com/cmal/git-stats-fcc-importer#readme) (by Yu Zhao)—git-stats importer for FreeCodeCamp users
2016-04-26 06:55:05 +02:00
- [`git-stats-importer`](https://github.com/IonicaBizau/git-stats-importer)—Imports your commits from a repository into git-stats history.
## :scroll: License
2015-11-08 16:53:04 +01:00
2015-12-03 14:02:50 +01:00
[MIT][license] © [Ionică Bizău][website]
2017-03-20 18:18:24 +01:00
[badge_patreon]: http://ionicabizau.github.io/badges/patreon.svg
[badge_amazon]: http://ionicabizau.github.io/badges/amazon.svg
[badge_paypal]: http://ionicabizau.github.io/badges/paypal.svg
[badge_paypal_donate]: http://ionicabizau.github.io/badges/paypal_donate.svg
2016-10-10 20:37:05 +02:00
[patreon]: https://www.patreon.com/ionicabizau
2017-03-20 18:18:24 +01:00
[amazon]: http://amzn.eu/hRo9sIZ
[paypal-donations]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=RVXDDLKKLQRJW
2015-11-08 16:53:04 +01:00
[donate-now]: http://i.imgur.com/6cMbHOC.png
2017-03-20 18:18:24 +01:00
[license]: http://showalicense.com/?fullname=Ionic%C4%83%20Biz%C4%83u%20%3Cbizauionica%40gmail.com%3E%20(https%3A%2F%2Fionicabizau.net)&year=2015#license-mit
[website]: https://ionicabizau.net
2015-11-08 16:53:04 +01:00
[contributing]: /CONTRIBUTING.md
2016-04-26 06:55:05 +02:00
[docs]: /DOCUMENTATION.md