mirror of
https://github.com/IonicaBizau/git-stats.git
synced 2024-12-22 05:12:11 +01:00
📝 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
parent
422d4c8855
commit
271e51dec7
3 changed files with 183 additions and 161 deletions
110
DOCUMENTATION.md
Normal file
110
DOCUMENTATION.md
Normal 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
37
LICENSE
|
|
@ -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
|
||||
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
|
||||
|
|
|
|||
197
README.md
197
README.md
|
|
@ -1,10 +1,27 @@
|
|||
|
||||
# `$ git-stats` [](https://github.com/IonicaBizau/git-stats/releases)
|
||||
A GitHub-like contributions calendar, but locally, with all your git commits.
|
||||
<!---------------------------------------------------------------------------->
|
||||
<!-- 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` [![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:
|
||||
|
||||
|
||||
|
||||
|
||||
## 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 [](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
|
||||
Loading…
Reference in a new issue