git-stats/README.md

232 lines
6.4 KiB
Markdown
Raw Normal View History

2015-02-09 14:34:08 +01:00
![](http://i.imgur.com/Q7TQYHx.png)
# `$ git-stats`
2015-01-26 09:08:11 +01:00
A GitHub-like contributions calendar, but locally, with all your git commits.
2015-02-09 15:07:37 +01:00
BTW, these are all my real commits in the last year.
2015-02-09 14:39:24 +01:00
![](http://i.imgur.com/LfLJAaE.png)
2015-01-26 09:08:11 +01:00
2015-02-09 14:39:24 +01:00
## Installation
2015-01-26 09:08:11 +01:00
```sh
2015-01-26 09:08:43 +01:00
$ npm install -g git-stats
2015-01-26 09:08:11 +01:00
```
2015-02-09 13:28:51 +01:00
### Catching the `git commit` command
Would you like to catch store automatically the commits when you do `git commit`?
If so, put the following lines in your `~/.bashrc` (or `~/.bash_profile` on OS X) file:
2015-02-01 07:24:53 +01:00
```sh
2015-02-09 13:28:51 +01:00
# Override the Git command
2015-02-01 07:24:53 +01:00
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
}
```
2015-02-09 13:36:44 +01:00
## Usage
2015-02-09 14:11:53 +01:00
```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 keept in the .git-stats, in your $HOME directory (~/)
Documentation can be found at https://github.com/IonicaBizau/git-stats
```
If you overriden the `git` command with a function, then your commits will be automatically recorded.
### Importing and deleting commits
I know it's not nice to start from scratch your git commit calendar. 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
2015-02-09 14:34:08 +01:00
Yes, you read correctly! That's also possible. I [build a tool for that too](https://github.com/IonicaBizau/repository-downloader)!
2015-02-09 14:11:53 +01:00
```sh
# Download the repository downloader
$ git clone git@github.com:IonicaBizau/repository-downloader.git
# Go to repository downloader
$ cd repository-downloader
# Install the dependencies
$ npm install
# Start downloading and importing
$ ./start
```
2015-02-09 14:39:24 +01:00
### 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
```
Fore more detailed documentation checkout the repository: https://github.com/IonicaBizau/ghcal.
2015-01-26 09:08:11 +01:00
## Documentation
2015-02-09 13:36:44 +01:00
If you want to use this as module, this is possible. See the content below.
2015-02-01 07:24:53 +01:00
### `record(data, callback)`
2015-01-26 09:08:11 +01:00
Records a new commit.
2015-02-01 07:24:53 +01:00
#### Params
2015-01-26 09:08:43 +01:00
- **Object** `data`: The commit data containing:
2015-02-09 14:14:10 +01:00
- `date` (String|Date): The date object or a string in a format that can be parsed.
2015-01-26 09:08:11 +01:00
- `url` (String): The repository remote url.
- `hash` (String): The commit hash.
- **Function** `callback`: The callback function.
2015-02-09 14:14:10 +01:00
#### Return
- **GitStats** The `GitStats` object.
### `get(callback)`
2015-01-26 09:08:11 +01:00
Gets the git stats.
2015-02-01 07:24:53 +01:00
#### Params
2015-01-26 09:08:11 +01:00
- **Function** `callback`: The callback function.
2015-02-09 14:14:10 +01:00
#### 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 the days, calling the callback function for 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.
2015-01-26 09:08:11 +01:00
## 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.
## License
See the [LICENSE](./LICENSE) file.