diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 0000000..539aac8 --- /dev/null +++ b/DOCUMENTATION.md @@ -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. + diff --git a/LICENSE b/LICENSE index ad4ac1b..44f5049 100644 --- a/LICENSE +++ b/LICENSE @@ -1,21 +1,24 @@ -The MIT License (MIT) +The KINDLY License +Copyright (c) 2015 Ionică Bizău -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 -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: + - if you want to use this software or include parts of its code in a + closed-source or commercial project you should kindly ask the + author (via a private message or email) and get a positive answer + - this license should be included in the modified versions of this software + - in case of redistributing modified copies, you are encouraged to clearly + 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 -copies or substantial portions of the Software. +You are free to install and use this software on as many machines as you want, +free of charge, making sure you met the terms above. -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. +You are encouraged to kindly support the software and its author by: + + - sharing his/her work + - reporting issues/bugs and asking for feature requests + - donating money or any other things that can help the author + - contribute on the software code by fixing bugs and adding features diff --git a/README.md b/README.md index a4ed623..a554778 100644 --- a/README.md +++ b/README.md @@ -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) -A GitHub-like contributions calendar, but locally, with all your git commits. + + + + + + + + + + + + + + + +![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: -![](http://i.imgur.com/LfLJAaE.png) +![git-stats](http://i.imgur.com/LfLJAaE.png) ## 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 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-) + - [Documentation](#documentation) - [How to contribute](#how-to-contribute) ## Installation -```sh -$ npm install -g git-stats -``` -### Catching the `git commit` command -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. +You can install the package globally and use it as command line tool: ```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 - -# ...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 -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 +Then, run `git-stats --help` and see what the cli tool can do. ```sh $ 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 ``` -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. 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 ``` - ### See the GitHub Contributions calendar 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 $ ghcal ionicabizau ``` - 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)` -Records a new commit. +```js +// Dependencies +var GitStats = require("git-stats"); -#### 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. +// Create the GitStats instance +var g1 = new GitStats(); -- **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)` -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. +## Documentation +For full API reference, see the [DOCUMENTATION.md][docs] file. ## How to contribute - -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. +Have an idea? Found a bug? See [how to contribute][contributing]. ## 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 \ No newline at end of file