Mirror
/
git-stats
mirror of https://github.com/IonicaBizau/git-stats.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

📝 Docs via Blah and relicense. 

Generated documentation using Blah 2.0.0 and relicensed the project under The KINDLY License.
This commit is contained in:
Ionică Bizău 2015-07-13 09:40:25 +03:00
parent 422d4c8855
commit 271e51dec7
3 changed files with 183 additions and 161 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
DOCUMENTATION.md Normal file
View File

@ -0,0 +1,110 @@
## Documentation
You can see below the API reference of this module.
### `GitStats(dataPath)`
#### Params
- **String** `dataPath`: Path to the data file.
#### Return
- **GitStats** The `GitStats` instance.
### `record(data, callback)`
Records a new commit.
#### Params
- **Object** `data`: The commit data containing:
- `date` (String|Date): The date object or a string in a format that can be parsed.
- `url` (String): The repository remote url.
- `hash` (String): The commit hash.
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` instance.
### `get(callback)`
Gets the git stats.
#### Params
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` instance.
### `save(stats, callback)`
Saves the provided stats.
#### Params
- **Object** `stats`: The stats to be saved.
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` instance.
### `iterateDays(data, callback)`
Iterate through the days, calling the callback function on each day.
#### Params
- **Object** `data`: An object containing the following fields:
- `start` (Moment): A `Moment` date object representing the start date (default: *an year ago*).
- `end` (Moment): A `Moment` date object representing the end date (default: *now*).
- `format` (String): The format of the date (default: `"MMM D, YYYY"`).
- **Function** `callback`: The callback function called with the current day formatted (type: string) and the `Moment` date object.
#### Return
- **GitStats** The `GitStats` instance.
### `graph(data, callback)`
Creates an object with the stats on the provided period (default: *last year*).
#### Params
- **Object** `data`: The object passed to the `iterateDays` method.
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` instance.
### `calendar(data, callback)`
Creates the calendar data for the provided period (default: *last year*).
#### Params
- **Object** `data`: The object passed to the `graph` method.
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` instance.
### `ansiCalendar(data, callback)`
Creates the ANSI contributions calendar.
#### Params
- **Object** `data`: The object passed to the `calendar` method.
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` instance.
### `authors(options, callback)`
Creates an array with the authors of a git repository.
#### Params
- **String|Object** `options`: The repo path or an object containing the following fields:
- `repo` (String): The repository path.
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` instance.
### `authorsPie(options, callback)`
Creates the authors pie.
#### Params
- **String|Object** `options`: The repo path or an object containing the following fields:
- `repo` (String): The repository path.
- `radius` (Number): The pie radius.
- `no_ansi` (Boolean): If `true`, the pie will not contain ansi characters.
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` instance.

37
LICENSE
View File

@ -1,21 +1,24 @@
The MIT License (MIT) The KINDLY License
Copyright (c) 2015 Ionică Bizău <bizauionica@gmail.com>
Copyright (c) 2015 Ionică Bizău You have the permission to use this software, read its source code, modify and
redistribute it under the following terms:
Permission is hereby granted, free of charge, to any person obtaining a copy - if you want to use this software or include parts of its code in a
of this software and associated documentation files (the "Software"), to deal closed-source or commercial project you should kindly ask the
in the Software without restriction, including without limitation the rights author (via a private message or email) and get a positive answer
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - this license should be included in the modified versions of this software
copies of the Software, and to permit persons to whom the Software is - in case of redistributing modified copies, you are encouraged to clearly
furnished to do so, subject to the following conditions: indicate that the copies are based on this work
- if you think that your redistributed copy is awesome, you are encouraged to
show the author of this software what you did and how you helped the others
The above copyright notice and this permission notice shall be included in all You are free to install and use this software on as many machines as you want,
copies or substantial portions of the Software. free of charge, making sure you met the terms above.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR You are encouraged to kindly support the software and its author by:
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - sharing his/her work
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - reporting issues/bugs and asking for feature requests
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - donating money or any other things that can help the author
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - contribute on the software code by fixing bugs and adding features
SOFTWARE.

197
README.md
View File

@ -1,10 +1,27 @@
![](http://i.imgur.com/Q7TQYHx.png) <!---------------------------------------------------------------------------->
# `$ git-stats` [![Release 1.4.1](https://img.shields.io/badge/Release-1.4.1-green.svg)](https://github.com/IonicaBizau/git-stats/releases) <!-- STOP, LOOK & LISTEN! -->
A GitHub-like contributions calendar, but locally, with all your git commits. <!-- ==================== -->
<!-- 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: 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:
![](http://i.imgur.com/LfLJAaE.png) ![git-stats](http://i.imgur.com/LfLJAaE.png)
## Contents ## Contents
@ -16,67 +33,21 @@ I'd be curious to see your calendar with all your commits. Ping me on Twitter ([
- [Importing and deleting commits](#importing-and-deleting-commits) - [Importing and deleting commits](#importing-and-deleting-commits)
- [Importing all the commits from GitHub and BitBucket](#importing-all-the-commits-from-github-and-bitbucket) - [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) - [See the GitHub Contributions calendar](#see-the-github-contributions-calendar)
- [Documentation](#documentation-) - [Documentation](#documentation)
- [How to contribute](#how-to-contribute) - [How to contribute](#how-to-contribute)
## Installation ## Installation
```sh
$ npm install -g git-stats
```
### Catching the `git commit` command You can install the package globally and use it as command line tool:
Would you like to catch and automatically store the commits when you do `git commit`? If so, try one of the following solutions.
#### Using `git` hooks
The way I recommend to track your git commits is to use git hooks. Run the following command to initialize the `post-commit` git hook.
```sh ```sh
# Using curl # 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 curl -s https://raw.githubusercontent.com/IonicaBizau/git-stats/master/scripts/init-git-post-commit | bash
# ...or wget
wget -qO- https://raw.githubusercontent.com/IonicaBizau/git-stats/master/scripts/init-git-post-commit | bash
``` ```
Then, you have to run `git init` into your existing git repositories from your local machine (that's because the `post-commit` should be updated). This Then, run `git-stats --help` and see what the cli tool can do.
step will not be needed after cloning a repository (the git hooks will be added automatically from `~/.git-templates`).
#### Overriding the `git` command
One of the solutions is becoming a mad scientist, overriding the `git` command with a function. However, this may not work for you if you're using `zsh`.
Add the following lines in your `~/.bashrc` (or `~/.bash_profile` on OS X) file:
```sh
# Override the Git command
git() {
cmd=$1
shift
extra=""
quoted_args=""
whitespace="[[:space:]]"
for i in "$@"
do
quoted_args="$quoted_args \"$i\""
done
cmdToRun="`which git` "$cmd" $quoted_args"
cmdToRun=`echo $cmdToRun | sed -e 's/^ *//' -e 's/ *$//'`
bash -c "$cmdToRun"
if [ $? -eq 0 ]; then
# Commit stats
if [ "$cmd" == "commit" ]; then
commit_hash=`git rev-parse HEAD`
repo_url=`git config --get remote.origin.url`
commit_date=`git log -1 --format=%cd`
commit_data="\"{ \"date\": \"$commit_date\", \"url\": \"$repo_url\", \"hash\": \"$commit_hash\" }\""
git-stats --record "$commit_data"
fi
fi
}
```
## Usage
```sh ```sh
$ git-stats --help $ git-stats --help
@ -110,8 +81,6 @@ Your commit history is kept in the .git-stats, in your $HOME directory (~/)
Documentation can be found at https://github.com/IonicaBizau/git-stats Documentation can be found at https://github.com/IonicaBizau/git-stats
``` ```
If you override the `git` command with a function, then your commits will be automatically recorded.
If you run `git-stats` to display graph on Windows, please use a terminal that can properly display ANSI colors. 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. Cygwin Terminal is known to work, while Windows Command Prompt and Git Bash do not.
@ -153,7 +122,6 @@ $ npm install
# Start downloading and importing # Start downloading and importing
$ ./start $ ./start
``` ```
### See the GitHub Contributions calendar ### See the GitHub Contributions calendar
There is a solution for that, too! :smile: It's called [`ghcal`](https://github.com/IonicaBizau/ghcal). There is a solution for that, too! :smile: It's called [`ghcal`](https://github.com/IonicaBizau/ghcal).
@ -164,101 +132,42 @@ $ npm install -g ghcal
# Checkout my contributions # Checkout my contributions
$ ghcal ionicabizau $ ghcal ionicabizau
``` ```
For more detailed documentation, check out the repository: https://github.com/IonicaBizau/ghcal. For more detailed documentation, check out the repository: https://github.com/IonicaBizau/ghcal.
## Documentation [![Inline docs](http://inch-ci.org/github/IonicaBizau/git-stats.svg?branch=master)](http://inch-ci.org/github/IonicaBizau/git-stats) ## Example
If you want to use this as a module, that is possible. See the content below. Here is an example how to use this package as library.
### `record(data, callback)` ```js
Records a new commit. // Dependencies
var GitStats = require("git-stats");
#### Params // Create the GitStats instance
- **Object** `data`: The commit data containing: var g1 = new GitStats();
- `date` (String|Date): The date object or a string in a format that can be parsed.
- `url` (String): The repository remote url.
- `hash` (String): The commit hash.
- **Function** `callback`: The callback function. // Display the ansi calendar
g1.ansiCalendar({
theme: "DARK"
}, function (err, data) {
console.log(err || data);
});
#### Return ```
- **GitStats** The `GitStats` object.
### `get(callback)` ## Documentation
Gets the git stats.
#### Params
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` object.
### `save(stats, callback)`
Saves the provided stats.
#### Params
- **Object** `stats`: The stats to be saved.
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` object.
### `iterateDays(data, callback)`
Iterate through the days, calling the callback function on each day.
#### Params
- **Object** `data`: An object containing the following fields:
- `start` (Moment): A `Moment` date object representing the start date (default: *an year ago*).
- `end` (Moment): A `Moment` date object representing the end date (default: *now*).
- `format` (String): The format of the date (default: `"MMM D, YYYY"`).
- **Function** `callback`: The callback function called with the current day formatted (type: string) and the `Moment` date object.
#### Return
- **GitStats** The `GitStats` object.
### `graph(data, callback)`
Creates an object with the stats on the provided period (default: *last year*).
#### Params
- **Object** `data`: The object passed to the `iterateDays` method.
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` object.
### `calendar(data, callback)`
Creates the calendar data for the provided period (default: *last year*).
#### Params
- **Object** `data`: The object passed to the `graph` method.
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` object.
### `ansiCalendar(data, callback)`
Creates the ANSI contributions calendar.
#### Params
- **Object** `data`: The object passed to the `calendar` method.
- **Function** `callback`: The callback function.
#### Return
- **GitStats** The `GitStats` object.
For full API reference, see the [DOCUMENTATION.md][docs] file.
## How to contribute ## How to contribute
Have an idea? Found a bug? See [how to contribute][contributing].
1. File an issue in the repository, using the bug tracker, describing the
contribution you'd like to make. This will help us to get you started on the
right foot.
2. Fork the project in your account and create a new branch:
`your-great-feature`.
3. Commit your changes in that branch.
4. Open a pull request, and reference the initial issue in the pull request
message.
## License ## License
See the [LICENSE](./LICENSE) file. [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