Merge pull request #199 from git-quick-stats/task/issues-3

Enhance daily statistics tracking

CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+title: Git Quick Stats
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - name-particle: tomice
+  - name-particle: arzzen
+identifiers:
+  - type: url
+    value: "https://github.com/git-quick-stats"
+    description: >-
+      Simple and efficient way to access various statistics
+      in a git repository
+repository-code: "https://github.com/git-quick-stats/git-quick-stats"
+url: "https://git-quick-stats.sh/"
+abstract: >-
+  Git-quick-stats is a simple and efficient way to access
+  various statistics in a git repository.
+keywords:
+  - git
+  - stats
+license: MIT
+version: 2.6.2

Dockerfile

@@ -4,7 +4,7 @@ FROM alpine
 COPY . /app
 
 # Install required packages & build git-quick-stats
-RUN     apk add --no-cache bash git make ncurses util-linux \
+RUN     apk add --no-cache bash git make ncurses coreutils util-linux \
     &&  cd /app \
     &&  make install \
     &&  rm -rf /app \

README.md

@@ -6,7 +6,7 @@
 >
 > Any git repository may contain tons of information about commits, contributors, and files. Extracting this information is not always trivial, mostly because there are a gadzillion options to a gadzillion git commands - I don't think there is a single person alive who knows them all. Probably not even [Linus Torvalds](https://github.com/torvalds) himself :).
 
-![mainMenuScreenshot](https://github.com/user-attachments/assets/05a20ff1-44f6-4e44-9d62-c2c089f9ff4e)
+![mainImageScreenshot](https://github.com/user-attachments/assets/7d8637a4-5a67-49f6-8724-ca7548b987c6)
 
 ## Table of Contents
 
@@ -54,9 +54,11 @@
 
 ## Screenshots
 
-![commitsByWeekdayScreenshot](https://github.com/user-attachments/assets/3a55f3ac-8801-4bbf-9b3a-92b53a64631e)
+![commitsByWeekdayScreenshot](https://github.com/user-attachments/assets/3496d245-6385-47d1-878a-726e79100eb1)
 
-![commitsByHourScreenshot](https://github.com/user-attachments/assets/d7de5280-8bb9-4391-9c6c-7e688f2df171)
+![commitsByHourScreenshot](https://github.com/user-attachments/assets/9f1d69d9-46e0-411d-a5ed-905ffdfb887a)
+
+![commitActivityScreenshot](https://github.com/user-attachments/assets/693fff31-65c7-4b9f-a011-6114a2d10a26)
 
 ## Usage
 
@@ -118,14 +120,16 @@ LIST OPTIONS
         see a list of everyone who contributed to the repo
     -n, --new-contributors
         list everyone who made their first contribution since a specified date
+    -N, --new-contributors-since-tag
+        list everyone who made their first contribution since a specified git tag
     -a, --commits-per-author
         displays a list of commits per author
     -d, --commits-per-day
         displays a list of commits per day
-    -Y, --commits-by-year
-        displays a list of commits per year
     -m, --commits-by-month
         displays a list of commits per month
+    -Y, --commits-by-year
+        displays a list of commits per year
     -w, --commits-by-weekday
         displays a list of commits per weekday
     -W, --commits-by-author-by-weekday
@@ -139,6 +143,12 @@ LIST OPTIONS
     -Z, --commits-by-author-by-timezone
         displays a list of commits per timezone by author
 
+CALENDAR OPTIONS
+    -k, --commits-calendar-by-author
+        shows a calendar heatmap of commits per day-of-week per month for a given author
+    -H, --commits-heatmap
+        shows a heatmap of commits per day-of-week per month for the last 30 days
+
 SUGGEST OPTIONS
     -r, --suggest-reviewers
         show the best people to contact to review code
@@ -165,6 +175,14 @@ You can set variable `_GIT_LIMIT` for limited output. It will affect the "change
 export _GIT_LIMIT=20
 ```
 
+### Git tag
+
+You can set `_GIT_TAG` to define the default tag used by the "new contributors since tag" option.
+
+```bash
+export _GIT_TAG="foo"
+```
+
 ### Git log options
 
 You can set `_GIT_LOG_OPTIONS` for [git log options](https://git-scm.com/docs/git-log#_options):
@@ -204,18 +222,39 @@ You can set the variable `_GIT_BRANCH` to set the branch of the stats. Works wit
 export _GIT_BRANCH="master"
 ```
 
+### Ignore authors
+
 You can set the variable `_GIT_IGNORE_AUTHORS` to filter out specific authors. It will affect the "All contributors", ""Suggested code reviewers" and "New contributors" options.
 
 ```bash
 export _GIT_IGNORE_AUTHORS="(author@examle.com|username)"
 ```
 
+### Sorting contribution stats
+
+You can sort contribution stats by field `name`, `commits`, `insertions`, `deletions`, or `lines` (total lines changed) and order (`asc`, `desc`). e.g.: `commits-desc`
+
+```bash
+export _GIT_SORT_BY="name-asc"
+```
+
+### Commit days
+
+You can set \_GIT_DAYS to set the number of days for the heatmap
+
+```bash
+export _GIT_DAYS=30
+```
+
 ### Color themes
 
-You can change to the legacy color scheme by toggling the variable `_MENU_THEME` between `default` and `legacy`
+You can change to the legacy color scheme by toggling the variable `_MENU_THEME` between `default` and `legacy`.
+You can completely disable the color theme by setting the `_MENU_THEME` variable to `none`.
 
 ```bash
 export _MENU_THEME="legacy"
+# or
+export _MENU_THEME="none"
 ```
 
 ![legacyThemeScreenshot](https://github.com/user-attachments/assets/3b319c1a-827f-47b8-bbfa-b8b59a39deef)
@@ -251,15 +290,16 @@ sudo make reinstall
 
 ### macOS (homebrew)
 
-macOS requires GNU coreutils to be installed and for the non "g" aliased
-versions to be exported to your path. The following is an example of how to
-perform this if you are using Homebrew as your package manager.
+`git-quick-stats` requires GNU `date`. On macOS, install GNU coreutils:
 
 ```bash
 brew install coreutils
 export PATH="$HOMEBREW_PREFIX/opt/coreutils/libexec/gnubin:$PATH"
 ```
 
+The script auto-detects GNU date as either `date` or `gdate`, so exporting
+`gnubin` is optional for this project.
+
 From there, you can install via Homebrew as follows:
 
 ```bash
@@ -268,10 +308,20 @@ brew install git-quick-stats
 
 Or you can follow the UNIX and Linux instructions if you wish.
 
-If you would like to default to using the GNU coreutils (recommended), then you
-can add `export PATH="$HOMEBREW_PREFIX/opt/coreutils/libexec/gnubin:$PATH"` to
-your applicable `~/.bash_profile`, `~/.zprofile`, or other relevant profile
-based on the shell of your choice.
+If you would like to default to using GNU coreutils system-wide, add
+`export PATH="$HOMEBREW_PREFIX/opt/coreutils/libexec/gnubin:$PATH"` to your
+applicable `~/.bash_profile`, `~/.zprofile`, or other relevant profile based
+on the shell of your choice.
+
+### FreeBSD
+
+`git-quick-stats` requires GNU `date`. On FreeBSD, install GNU coreutils:
+
+```bash
+pkg install coreutils
+```
+
+FreeBSD provides GNU date as `gdate`, and the script auto-detects it.
 
 ### Windows
 
@@ -293,6 +343,7 @@ You can use the Docker image provided:
 ## System requirements
 
 - An OS with a Bash shell
+- GNU `date` available as either `date` or `gdate`
 - Tools we use:
 
 ```bash
@@ -380,24 +431,3 @@ MIT see [LICENSE][] for the full license text.
 This project exists thanks to all the people who contribute.
 
 [![contributors](https://opencollective.com/git-quick-stats/contributors.svg?width=890&button=false)](https://github.com/git-quick-stats/git-quick-stats/graphs/contributors)
-
-### Backers
-
-Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/git-quick-stats#backer)]
-
-[![backers](https://opencollective.com/git-quick-stats/backers.svg?width=890)](https://opencollective.com/git-quick-stats#backers)
-
-### Sponsors
-
-Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/git-quick-stats#sponsor)]
-
-[![sponsor0](https://opencollective.com/git-quick-stats/sponsor/0/avatar.svg?v=1)](https://opencollective.com/git-quick-stats/sponsor/0/website)
-[![sponsor1](https://opencollective.com/git-quick-stats/sponsor/1/avatar.svg)](https://opencollective.com/git-quick-stats/sponsor/1/website)
-[![sponsor2](https://opencollective.com/git-quick-stats/sponsor/2/avatar.svg)](https://opencollective.com/git-quick-stats/sponsor/2/website)
-[![sponsor3](https://opencollective.com/git-quick-stats/sponsor/3/avatar.svg)](https://opencollective.com/git-quick-stats/sponsor/3/website)
-[![sponsor4](https://opencollective.com/git-quick-stats/sponsor/4/avatar.svg)](https://opencollective.com/git-quick-stats/sponsor/4/website)
-[![sponsor5](https://opencollective.com/git-quick-stats/sponsor/5/avatar.svg)](https://opencollective.com/git-quick-stats/sponsor/5/website)
-[![sponsor6](https://opencollective.com/git-quick-stats/sponsor/6/avatar.svg)](https://opencollective.com/git-quick-stats/sponsor/6/website)
-[![sponsor7](https://opencollective.com/git-quick-stats/sponsor/7/avatar.svg)](https://opencollective.com/git-quick-stats/sponsor/7/website)
-[![sponsor8](https://opencollective.com/git-quick-stats/sponsor/8/avatar.svg)](https://opencollective.com/git-quick-stats/sponsor/8/website)
-[![sponsor9](https://opencollective.com/git-quick-stats/sponsor/9/avatar.svg)](https://opencollective.com/git-quick-stats/sponsor/9/website)

git-quick-stats.1

@@ -17,8 +17,30 @@ and files. Extracting this information is not always trivial, mostly because
 of a gadzillion options to a gadzillion git commands.
 This program allows you to see detailed information about a git repository.
 .PP
+.SH PLATFORM NOTES
+.PP
+git-quick-stats requires GNU date support for date parsing options.
+.PP
+On macOS, install GNU coreutils with:
+.PP
+.B brew install coreutils
+.PP
+On FreeBSD, install GNU coreutils with:
+.PP
+.B pkg install coreutils
+.PP
+GNU date may be available as either
+.B date
+or
+.B gdate
+and git-quick-stats auto-detects both.
+.PP
 .SH GENERATE OPTIONS
 .PP
+\fB\-h\fR, \-?, \fB\-\-help\fR
+.IP
+display this help text in the terminal
+.PP
 \fB\-T\fR, \fB\-\-detailed\-git\-stats\fR
 .IP
 give a detailed list of git stats
@@ -75,6 +97,11 @@ see a list of everyone who contributed to the repo
 list everyone who made their first contribution since a specified date
 .HP
 .PP
+\fB\-N\fR, \fB\-\-new\-contributors\-since\-tag\fR
+.IP
+list everyone who made their first contribution since a specified git tag
+.HP
+.PP
 \fB\-a\fR, \fB\-\-commits\-per\-author\fR
 .IP
 displays a list of commits per author
@@ -136,9 +163,12 @@ displays a calendar-style grid of commit activity per day-of-week and month for
 show the best people to contact to review code
 .HP
 .PP
-\fB\-h\fR, \-?, \fB\-\-help\fR
-.IP
-display this help text in the terminal
+.SH CALENDAR OPTIONS
+.PP
+\fB\-k\fR, \fB\-\-commits\-calendar\-by\-author\fR outputs a visual grid of commit activity for a selected author, grouped by day-of-week (rows: Mon..Sun) and month (columns: Jan..Dec). Each cell is 3 characters wide, separated by one space.
+.PP
+.PP
+\fB\-H\fR, \fB\-\-commits\-heatmap\fR shows a heatmap of commits per day per hour for the last 30 days
 .PP
 .SH ADDITIONAL USAGE
 You can set _GIT_SINCE and _GIT_UNTIL to limit the git time log, example:
@@ -149,6 +179,10 @@ You can set _GIT_LIMIT for limited output log, example:
 .PP
 .B  export _GIT_LIMIT=20
 .PP
+You can set _GIT_TAG to define the default tag used by the "new contributors since tag" option, example:
+.PP
+.B  export _GIT_TAG="foo"
+.PP
 You can set _GIT_LOG_OPTIONS for git log options, example:
 .PP
 .B  export _GIT_LOG_OPTIONS="--ignore-all-space --ignore-blank-lines"
@@ -165,35 +199,28 @@ You can also set _GIT_MERGE_VIEW to only show merge commits, example:
 .PP
 .B  export _GIT_MERGE_VIEW="exclusive"
 .PP
-You can switch to the legacy color scheme, example:
+You can sort contribution stats by field "name", "commits", "insertions", "deletions", or "lines" (total lines changed) and order ("asc", "desc"). e.g.: "commits-desc"
+.PP
+.B  export _GIT_SORT_BY="name-asc"
+.PP
+You can change to the legacy color scheme by toggling the variable "_MENU_THEME" between "default" and "legacy". You can completely disable the color theme by setting the "_MENU_THEME" variable to "none", example:
 .PP
 .B export _MENU_THEME=legacy
 .PP
+or
+.B export _MENU_THEME=none
+.PP
 You can set _GIT_BRANCH to set the branch of the stats, example:
 .PP
 .B  export _GIT_BRANCH="master"
 .PP
-.SH Calendar activity output
-.PP
-\fBactivity-calendar\fR outputs a visual grid of commit activity for a selected author, grouped by day-of-week (rows: Mon..Sun) and month (columns: Jan..Dec). Each cell is 3 characters wide, separated by one space.
-.PP
-Sample output:
-.PP
-.nf
-      Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
-Mon   ▓▓▓ ░░░ ▒▒▒ ░░░ ░░░ ▒▒▒ ▓▓▓ ░░░ ░░░ ▓▓▓ ▒▒▒ ▒▒▒
-Tue   ▒▒▒ ░░░ ▒▒▒ ░░░ ▒▒▒ ░░░ ▒▒▒ ▓▓▓ ▒▒▒ ░░░ ░░░ ░░░
-Wed   ░░░ ▓▓▓ ░░░ ▓▓▓ ▒▒▒ ░░░ ░░░ ▒▒▒ ░░░ ░░░ ▓▓▓ ░░░
-Thu   ░░░ ▒▒▒ ░░░ ░░░ ▒▒▒ ░░░ ▓▓▓ ▒▒▒ ▒▒▒ ░░░ ░░░ ▒▒▒
-Fri   ▒▒▒ ░░░ ▒▒▒ ▓▓▓ ░░░ ▓▓▓ ▒▒▒ ░░░ ▒▒▒ ░░░ ▒▒▒ ░░░
-Sat   ░░░ ░░░ ▒▒▒ ░░░ ░░░ ░░░ ▒▒▒ ░░░ ▒▒▒ ▓▓▓ ▒▒▒ ░░░
-Sun   ▓▓▓ ░░░ ▓▓▓ ░░░ ░░░ ▓▓▓ ░░░ ▒▒▒ ░░░ ░░░ ▓▓▓ ░░░
-
-Legend: ... = 0   ░░░ = 1–2   ▒▒▒ = 3–5   ▓▓▓ = 6+ commits
-.PP
 You can set _GIT_IGNORE_AUTHORS to filter out specific authors, example:
 .PP
 .B  export _GIT_IGNORE_AUTHORS="(author@examle.com|username)"
+.PP
+You can set _GIT_DAYS to set the number of days for the heatmap, example:
+.PP
+.B  export _GIT_DAYS=30"
 .
 .fi
 

tests/commands_test.sh

@@ -11,7 +11,7 @@
 . tests/assert.sh -v
 
 src="./git-quick-stats"
-assert "$src fail" "Invalid argument
+assert "$src fail" "Invalid argument: fail
 
 NAME
     git-quick-stats - Simple and efficient way to access various stats in a git repo
@@ -52,6 +52,8 @@ LIST OPTIONS
         see a list of everyone who contributed to the repo
     -n, --new-contributors
         list everyone who made their first contribution since a specified date
+    -N, --new-contributors-since-tag
+        list everyone who made their first contribution since a specified tag
     -a, --commits-per-author
         displays a list of commits per author
     -d, --commits-per-day
@@ -73,6 +75,12 @@ LIST OPTIONS
     -Z, --commits-by-author-by-timezone
         displays a list of commits per timezone by author
 
+CALENDAR OPTIONS
+    -k, --commits-calendar-by-author
+        shows a calendar heatmap of commits per day-of-week per month for a given author
+    -H, --commits-heatmap
+        shows a heatmap of commits per day-of-week per month for the last 30 days
+
 SUGGEST OPTIONS
     -r, --suggest-reviewers
         show the best people to contact to review code
@@ -92,22 +100,34 @@ ADDITIONAL USAGE
         ex: export _GIT_MERGE_VIEW=enable
     You can also set _GIT_MERGE_VIEW to only show merge commits
         ex: export _GIT_MERGE_VIEW=exclusive
-    You can set _MENU_THEME to display the legacy color scheme
+    You can change to the legacy color scheme by toggling the variable \"_MENU_THEME\" between \"default\" and \"legacy\".
+    You can completely disable the color theme by setting the \"_MENU_THEME\" variable to \"none\".
         ex: export _MENU_THEME=legacy
     You can set _GIT_BRANCH to set the branch of the stats
-        ex: export _GIT_BRANCH=master"
+        ex: export _GIT_BRANCH=master
+    You can set _GIT_IGNORE_AUTHORS to filter out specific authors
+        ex: export _GIT_IGNORE_AUTHORS=\"(author1|author2)\"
+    You can sort contribution stats by field \"name\", \"commits\", \"insertions\", \"deletions\", or \"lines\" - total lines changed and order - \"asc\", \"desc\"
+        ex: export _GIT_SORT_BY=\"name-asc\"
+    You can set _GIT_DAYS to set the number of days for the heatmap
+        ex: export _GIT_DAYS=30"
 
 assert_raises "$src fail" 1
 
 assert_contains "$src --suggest-reviewers" "Suggested code reviewers (based on git history)"
 assert_success "$src --suggest-reviewers"
 
-assert_contains "$src --detailed-git-stats" "Contribution stats"
+assert_contains "$src --detailed-git-stats" "Contribution stats (by author) on the current branch"
 assert_success "$src --detailed-git-stats"
 
 assert_contains "$src --commits-per-day" "Git commits per date"
 assert_success "$src --commits-per-day"
 
+assert_contains "$src --my-daily-stats" "My daily status"
+assert_contains "$src --my-daily-stats" "most changed files today"
+assert_contains "$src --my-daily-stats" "most active users today (excluding you)"
+assert_success "$src --my-daily-stats"
+
 assert_startswith "$src --commits-by-year" "Git commits by year"
 assert_success "$src --commits-by-year"