Merge pull request #190 from git-quick-stats/task/commits-heatmap

commits heatmap

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

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
 
@@ -122,10 +124,10 @@ LIST OPTIONS
         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 +141,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
@@ -220,6 +228,14 @@ You can sort contribution stats by field `name`, `commits`, `insertions`, `delet
 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`.
@@ -393,24 +409,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

@@ -10,6 +10,24 @@
 set -o nounset
 set -o errexit
 
+# Global color variables using tput setaf
+COLOR_NORMAL=$(tput sgr0)
+COLOR_CYANL=$(tput setaf 6)
+COLOR_BOLD=$(tput bold)
+COLOR_RED=$(tput setaf 1)
+COLOR_YELLOW=$(tput setaf 3)
+COLOR_WHITE=$(tput setaf 7)
+COLOR_BRIGHT_YELLOW=$(tput setaf 226)
+COLOR_GOLD=$(tput setaf 220)
+COLOR_ORANGE=$(tput setaf 214)
+COLOR_DARK_ORANGE=$(tput setaf 208)
+COLOR_RED_ORANGE=$(tput setaf 202)
+COLOR_DARK_RED=$(tput setaf 160)
+COLOR_DEEP_RED=$(tput setaf 88)
+COLOR_DARKEST_RED=$(tput setaf 52)
+COLOR_GRAY=$(tput setaf 240)
+COLOR_RESET=$(tput sgr0)
+
 # Beginning git log date. Respects all git datetime formats
 # If $_GIT_SINCE is never set, look at the repository to find the first date.
 # NOTE: previously this put the date at the fixed GIT epoch (May 2005)
@@ -84,6 +102,14 @@ if [[ ! "$_GIT_SORT_BY" =~ ^(name|commits|insertions|deletions|lines)-(asc|desc)
     _GIT_SORT_BY="name-asc"
 fi
 
+# Number of days to display in the heatmap
+_commit_days=${_GIT_DAYS:-30}
+# If the user has not set a number of days, default to 30
+if ! [[ "$_commit_days" =~ ^[0-9]+$ ]] || (( _commit_days <= 0 )); then
+    echo "Invalid number of days: $_commit_days. Defaulting to 30."
+    _commit_days=30
+fi
+
 # Default menu theme
 # Set the legacy theme by typing "export _MENU_THEME=legacy"
 _theme="${_MENU_THEME:=default}"
@@ -141,6 +167,93 @@ function commitsCalendarByAuthor() {
     '
 }
 
+# DESC: Shows a heatmap of commits per hour of each day for the last 30 days
+function commitsHeatmap() {
+    optionPicked "Commit Heatmap for the last $_commit_days days"
+
+    color_for_count() {
+        local n=$1
+        if (( n == 1 )); then
+            echo -n "${COLOR_BRIGHT_YELLOW}"
+        elif (( n < 2 )); then
+            echo -n "${COLOR_GOLD}"
+        elif (( n < 3 )); then
+            echo -n "${COLOR_ORANGE}"
+        elif (( n < 4 )); then
+            echo -n "${COLOR_DARK_ORANGE}"
+        elif (( n < 5 )); then
+            echo -n "${COLOR_RED_ORANGE}"
+        elif (( n < 6 )); then
+            echo -n "${COLOR_RED}"
+        elif (( n < 8 )); then
+            echo -n "${COLOR_DARK_RED}"
+        elif (( n < 10 )); then
+            echo -n "${COLOR_DEEP_RED}"
+        else
+            echo -n "${COLOR_DARKEST_RED}"
+        fi
+    }
+
+    printf "Day | Date/Hours |"
+    local h
+    for h in {0..23}; do
+        printf " %2d" "$h"
+    done
+    echo
+    echo "------------------------------------------------------------------------------------------"
+
+    local i
+    for i in $(seq $((_commit_days-1)) -1 0); do
+        local day=$(date -d "-$i days" +"%Y-%m-%d")
+        if [[ $(date -d "$day" +%u) -gt 5 ]]; then
+            echo -en "${COLOR_GRAY}"
+        else
+            echo -en "${COLOR_RESET}"
+        fi
+
+        local dayName=$(date -d "$day" +%a)
+        printf "%s | %s |" "$dayName" "$day"
+
+        declare -a commits_per_hour
+        local h
+        for h in {0..23}; do
+            commits_per_hour[$h]=0
+        done
+
+        IFS=$'\n' commits_per_hour=($(
+            git log --since="$day 00:00" --until="$day 23:59" --pretty=format:"%ci" 2>/dev/null |
+            awk '{split($2, t, ":"); h = t[1]+0; c[h]++} END {for(i=0;i<24;i++) print c[i]+0}'
+        ))
+        unset IFS
+
+        local h
+        for h in {0..23}; do
+            local count=${commits_per_hour[$h]}
+            local color=$(color_for_count "$count")
+            if (( count == 0 )); then
+                echo -en " ${COLOR_GRAY}.${COLOR_RESET} "
+            else
+                echo -en "${color} █ ${COLOR_RESET}"
+            fi
+        done
+        echo 
+    done
+    echo "------------------------------------------------------------------------------------------"
+
+    echo -e "\nLegend:"
+    echo -e " ${COLOR_BRIGHT_YELLOW}█${COLOR_RESET} 1 commit"
+    echo -e " ${COLOR_GOLD}█${COLOR_RESET} 2 commits"
+    echo -e " ${COLOR_ORANGE}█${COLOR_RESET} 3 commits"
+    echo -e " ${COLOR_DARK_ORANGE}█${COLOR_RESET} 4 commits"
+    echo -e " ${COLOR_RED_ORANGE}█${COLOR_RESET} 5 commits"
+    echo -e " ${COLOR_RED}█${COLOR_RESET} 6 commits"
+    echo -e " ${COLOR_DARK_RED}█${COLOR_RESET} 7–8 commits"
+    echo -e " ${COLOR_DEEP_RED}█${COLOR_RESET} 9–10 commits"
+    echo -e " ${COLOR_DARKEST_RED}█${COLOR_RESET} 11+ commits"
+    echo -e " ${COLOR_GRAY}.${COLOR_RESET} = no commits"
+    echo
+}
+
 ################################################################################
 # HELPER AND MENU FUNCTIONS
 
@@ -256,6 +369,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
@@ -283,7 +402,9 @@ ADDITIONAL USAGE
     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\""
+        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"
 }
 
 ################################################################################
@@ -293,12 +414,6 @@ ADDITIONAL USAGE
 ################################################################################
 function showMenu() {
     # These are "global" and can be overriden from users if so desired
-    NORMAL=$(tput sgr0)
-    CYAN=$(tput setaf 6)
-    BOLD=$(tput bold)
-    RED=$(tput setaf 1)
-    YELLOW=$(tput setaf 3)
-    WHITE=$(tput setaf 7)
     TITLES=""
     TEXT=""
     NUMS=""
@@ -308,29 +423,29 @@ function showMenu() {
     # Adjustable color menu option
     case "${_theme}"  in
         "legacy" )
-            TITLES="${BOLD}${RED}"
-            TEXT="${NORMAL}${CYAN}"
-            NUMS="${BOLD}${YELLOW}"
-            HELP_TXT="${NORMAL}${YELLOW}"
-            EXIT_TXT="${BOLD}${RED}"
+            TITLES="${COLOR_BOLD}${COLOR_RED}"
+            TEXT="${COLOR_NORMAL}${COLOR_CYANL}"
+            NUMS="${COLOR_BOLD}${COLOR_YELLOW}"
+            HELP_TXT="${COLOR_NORMAL}${COLOR_YELLOW}"
+            EXIT_TXT="${COLOR_BOLD}${COLOR_RED}"
             ;;
         "none" )
-            TITLES="${BOLD}"
-            TEXT="${NORMAL}"
-            NUMS="${BOLD}"
-            HELP_TXT="${NORMAL}"
-            EXIT_TXT="${BOLD}"
+            TITLES="${COLOR_BOLD}"
+            TEXT="${COLOR_NORMAL}"
+            NUMS="${COLOR_BOLD}"
+            HELP_TXT="${COLOR_NORMAL}"
+            EXIT_TXT="${COLOR_BOLD}"
             ;;
         *)
-            TITLES="${BOLD}${CYAN}"
-            TEXT="${NORMAL}${WHITE}"
-            NUMS="${NORMAL}${BOLD}${WHITE}"
-            HELP_TXT="${NORMAL}${CYAN}"
-            EXIT_TXT="${BOLD}${CYAN}"
+            TITLES="${COLOR_BOLD}${COLOR_CYANL}"
+            TEXT="${COLOR_NORMAL}${COLOR_WHITE}"
+            NUMS="${COLOR_NORMAL}${COLOR_BOLD}${COLOR_WHITE}"
+            HELP_TXT="${COLOR_NORMAL}${COLOR_CYANL}"
+            EXIT_TXT="${COLOR_BOLD}${COLOR_CYANL}"
             ;;
     esac
 
-    printf %b "\\n${TITLES} Generate:${NORMAL}\\n"
+    printf %b "\\n${TITLES} Generate:${COLOR_NORMAL}\\n"
     printf %b "${NUMS}    1)${TEXT} Contribution stats (by author)\\n"
     printf %b "${NUMS}    2)${TEXT} Contribution stats (by author) on a specific branch\\n"
     printf %b "${NUMS}    3)${TEXT} Git changelogs (last $_limit days)\\n"
@@ -357,8 +472,9 @@ function showMenu() {
     printf %b "${NUMS}   22)${TEXT} Code reviewers (based on git history)\\n"
     printf %b "\\n${TITLES} Calendar:\\n"
     printf %b "${NUMS}   23)${TEXT} Activity calendar by author\\n"
+    printf %b "${NUMS}   24)${TEXT} Activity heatmap for the last $_commit_days days\\n"
     printf %b "\\n${HELP_TXT}Please enter a menu option or ${EXIT_TXT}press Enter to exit.\\n"
-    printf %b "${TEXT}> ${NORMAL}"
+    printf %b "${TEXT}> ${COLOR_NORMAL}"
     read -r opt
 }
 
@@ -1275,13 +1391,14 @@ if [[ "$#" -eq 1 ]]; then
                 read -r -p "Which author? " author
             done
             commitsByTimezone "${author}";;
-        # ACTIVITY OPTIONS
+        # CALENDAR OPTIONS
         -k|--commits-calendar-by-author)
             author="${_GIT_AUTHOR:-}"
             while [[ -z "${author}" ]]; do
                 read -r -p "Which author? " author
             done
             commitsCalendarByAuthor "${author}";;
+        -H|--commits-heatmap) commitsHeatmap;;
         # SUGGEST OPTIONS
         -r|--suggest-reviewers) suggestReviewers;;
         -h|-\?|--help) usage;;
@@ -1374,6 +1491,7 @@ if [[ "$#" -eq 0 ]]; then
                     read -r -p "Which author? " author
                 done
                 commitsCalendarByAuthor "${author}"; showMenu;;
+           24) commitsHeatmap; showMenu;;
            q|"\n") exit;;
            *) clear; optionPicked "Pick an option from the menu"; showMenu;;
         esac

git-quick-stats.1

@@ -19,6 +19,10 @@ This program allows you to see detailed information about a git repository.
 .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
@@ -136,9 +140,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:
@@ -180,27 +187,13 @@ 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

@@ -73,6 +73,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
@@ -100,7 +106,9 @@ ADDITIONAL USAGE
     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\""
+        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