Merge pull request #167 from tomice/master

Update documentation for clarity

README.md

@@ -1,13 +1,13 @@
+# GIT quick statistics [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Simple%20and%20efficient%20way%20to%20access%20various%20statistics%20in%20git%20repository&url=https://github.com/arzzen/git-quick-stat&via=arzzen&hashtags=git,stats,tool,statistics,developers)
 
-# GIT quick statistics [![Backers on Open Collective](https://opencollective.com/git-quick-stats/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/git-quick-stats/sponsors/badge.svg)](#sponsors) [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Simple%20and%20efficient%20way%20to%20access%20various%20statistics%20in%20git%20repository&url=https://github.com/arzzen/git-quick-stat&via=arzzen&hashtags=git,stats,tool,statistics,developers) [![Travis](https://api.travis-ci.org/arzzen/git-quick-stats.svg?branch=master)](https://travis-ci.org/arzzen/git-quick-stats) [![Homebrew package](https://repology.org/badge/version-for-repo/homebrew/git-quick-stats.svg)](https://formulae.brew.sh/formula/git-quick-stats#default) [![Linuxbrew package](https://repology.org/badge/version-for-repo/linuxbrew/git-quick-stats.svg)](https://repology.org/metapackage/git-quick-stats/packages)
+[![Backers on Open Collective](https://opencollective.com/git-quick-stats/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/git-quick-stats/sponsors/badge.svg)](#sponsors)  [![Homebrew package](https://repology.org/badge/version-for-repo/homebrew/git-quick-stats.svg)](https://formulae.brew.sh/formula/git-quick-stats#default)
 
 > `git-quick-stats` is a simple and efficient way to access various statistics in a git repository.
 >
-> 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 :).
+> 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://user-images.githubusercontent.com/8818630/154823670-f42a111b-45f4-47fc-aea7-80059827c8e6.png)
 
-
 ## Table of Contents
 
 [**Screenshots**](#screenshots)
@@ -157,7 +157,7 @@ Once set, run `git quick-stats` as normal. Note that this affects all stats that
 
 ### Git log limit
 
-You can set variable `_GIT_LIMIT` for limited output. It will affect the "changelogs" and "branch tree" options.
+You can set variable `_GIT_LIMIT` for limited output. It will affect the "changelogs" and "branch tree" options. The default limit is `10`.
 
 ```bash
 export _GIT_LIMIT=20
@@ -243,12 +243,28 @@ 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.
+
+```bash
+brew install coreutils
+export PATH="$HOMEBREW_PREFIX/opt/coreutils/libexec/gnubin:$PATH"
+```
+
+From there, you can install via Homebrew as follows:
+
 ```bash
 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.
+
 ### Windows
 
 If you are installing with Cygwin, use these scripts:
@@ -276,6 +292,7 @@ awk
 basename
 cat
 column
+date
 echo
 git
 grep
@@ -290,7 +307,11 @@ uniq
 
 ### Dependencies
 
-* [`bsdmainutils`](https://packages.debian.org/sid/bsdmainutils) `apt install bsdmainutils`
+* [`bsdextrautils`](https://packages.debian.org/sid/bsdextrautils) `apt install bsdextrautils`
+* [`coreutils`](https://packages.debian.org/sid/coreutils) `apt install coreutils`
+* [`gawk`](https://packages.debian.org/sid/gawk) `apt install gawk`
+* [`grep`](https://packages.debian.org/sid/grep) `apt install grep`
+* [`ncurses-bin`](https://packages.debian.org/sid/ncurses-bin) `apt install ncurses-bin`
 
 ## FAQ
 
@@ -372,6 +393,3 @@ Support this project by becoming a sponsor. Your logo will show up here with a l
 [![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)
-
-[![61999966](https://user-images.githubusercontent.com/6382002/130024560-65bb49a6-c7e9-48f9-8427-a29d8ff2a3db.png)](https://quaestor.com/?utm_source=github&utm_category=sponsor)
-

git-quick-stats

@@ -82,13 +82,29 @@ _theme="${_MENU_THEME:=default}"
 ################################################################################
 function checkUtils() {
     readonly MSG="not found. Please make sure this is installed and in PATH."
-    readonly UTILS="awk basename cat column echo git grep head printf seq sort \
-                    tput tr uniq"
+    readonly UTILS="awk basename cat column date echo git grep head printf seq \
+                    sort tput tr uniq"
 
     for u in $UTILS
     do
         command -v "$u" >/dev/null 2>&1 || { echo >&2 "$u ${MSG}"; exit 1; }
     done
+
+    # NOTE: The --version flag is only available in GNU date which is required
+    # for how the current date/time strings are used in this shell script.
+    # To fully support the legacy BSD date found in a default install within
+    # macOS and older distributions of Linux and Unix, a handful of helper
+    # functions can probably be created to handle every case of incompatibility
+    # between the two. Until that's implemented, it is probably best to warn
+    # the user that this will not work rather than having it silently bomb out
+    # during runtime.
+    if ! date --version >/dev/null 2>&1; then
+        echo "ERROR: GNU date is required."
+        echo "If you're on macOS, please install it using 'brew install coreutils'."
+        echo "Ensure that your PATH is configured to use GNU date as well."
+        echo "See the README.md for further details."
+        exit 1
+    fi
 }
 
 ################################################################################
@@ -102,6 +118,24 @@ function optionPicked() {
     echo -e "${msg}\n"
 }
 
+################################################################################
+# DESC: Format date string
+# ARGS: $* (required): String
+# OUTS: String
+################################################################################
+function format_date() {
+    # NOTE: While this works where it's implemented within the changelogs()
+    # function the first time, it then bombs out when it reaches the -d flag
+    # in the second half of that same code as BSD date cannot handle -d, nor
+    # can it handle a string such as DATE - 1 day.
+    local date="${1}"
+    local outf="${2}"
+    local datef="${3:-"%b %d %H:%M:%S %Y %Z"}"  # Tue Oct 24 13:34:22 2023 +0300
+    local resp="$(date -d "${date}" "+${outf}")"
+
+    printf "%s" "${resp}"
+}
+
 ################################################################################
 # DESC: Help information printed to stdout during non-interactive mode
 # ARGS: None
@@ -394,12 +428,12 @@ function changelogs() {
         --date=short "${_author}" "$_since" "$_until" $_log_options $_pathspec \
         | sort -u -r | head -n $_limit \
         | while read DATE; do
-              day=$(date -d "$DATE" "+%A")
+              day=$(format_date "$DATE" "%A" "%Y-%m-%d")
               echo -e "\n[$DATE - $day]"
               GIT_PAGER=cat git -c log.showSignature=false log \
                                 --use-mailmap $_merges \
                                 --format=" * %s (%aN)" "${_author}" \
-                                --since=$DATE --until=$next
+                                --since==$(date -d "$DATE - 1 day" +"%Y-%m-%d") --until=$next
               next=$DATE
           done
 }
@@ -888,9 +922,9 @@ function commitsByTimezone() {
     fi
 
     echo -e "Commits\tTimeZone"
-    git -c log.showSignature=false shortlog -n $_merges --format='%ad %s' \
+    git -c log.showSignature=false log $_merges --format='%ad %s' \
         "${_author}" "$_since" "$_until" --date=iso $_log_options $_pathspec \
-        | cut -d " " -f 12 | grep -v -e '^[[:space:]]*$' | sort | uniq -c
+        | cut -d " " -f 3 | grep -v -e '^[[:space:]]*$' | sort -n | uniq -c
 }
 
 ################################################################################

git-quick-stats.1

@@ -1,4 +1,4 @@
-.TH git-quick-stats "1" "June 2021" "git-quick-stats" "User Commands"
+.TH git-quick-stats "1" "April 2024" "git-quick-stats" "User Commands"
 .SH NAME
 .B git\-quick\-stats
 \- Simple and efficient way to access various stats in a git repository.
@@ -95,7 +95,7 @@ displays a list of commits per year
 displays a list of commits per weekday
 .HP
 .PP
-\fB\-W\fR, \fB\-\-commits\-by\author\-by\-weekday\fR
+\fB\-W\fR, \fB\-\-commits\-by\-author\-by\-weekday\fR
 .IP
 displays a list of commits per weekday by author
 .HP

tests/commands_test.sh

@@ -1,5 +1,13 @@
 #!/bin/bash
 
+# Verify we are in a git repo. Create one if not
+# FIXME: All the paths are hardcoded currently and will break if anything
+# in this chain moves or gets executed elsewhere. Adjust all of these so
+# pathing does not matter as much such as creating a TOP variable that
+# does something like TOP=$(cd "$(dirname "$0")" || exit ; pwd -P)
+# or maybe leverages Make to handle these as test targets
+./tests/test-git/resetgit
+
 . tests/assert.sh -v
 
 src="./git-quick-stats"

tests/test-git/resetgit

@@ -1,17 +1,16 @@
 #!/bin/sh
-# Initialises a new local Git repo for test purpose.
-if test -d ../test-git/.git; then rm -Rf ../test-git/.git; fi
-#mkdir test-git
-cd ../test-git
-git init
-git config user.name "$(printf %s 'Test Git,\nfor test purpose')"
-git config user.email "TestGit\o/@example.org"
+# Initialises a new local Git repo for test purpose if one does not exist already
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    {
+        git init
+        git config user.name "$(printf %s 'Test Git,\nfor test purpose')"
+        git config user.email "TestGit\o/@example.org"
 
-#printf '\n[user]\nname = test-git\nemail = test-git@example.org\n'> .git/config
-printf 'test-git\n========\n' > README.md
-git add README.md
-git commit -m 'added readme (o\w/o)' -m 'in markdown, no \r\n, only \n' -m 'a very "simple" readme'
-testChars="$(printf 'tab [%b] form feed [%b] line feed [%b] carriage return [%b]' '\x09' '\x0C' '\x0A' '\x0D')"
-#printf '# testChars [%s]\n' "$testChars">&2
-git notes add -m 'Some notes' -m 'out of ascii: été au cœur' -m "$testChars"
-git log
+        printf 'test-git\n========\n' > README.md
+        git add README.md
+        git commit -m 'added readme (o\w/o)' -m 'in markdown, no \r\n, only \n' -m 'a very "simple" readme'
+        testChars="$(printf 'tab [%b] form feed [%b] line feed [%b] carriage return [%b]' '\x09' '\x0C' '\x0A' '\x0D')"
+        git notes add -m 'Some notes' -m 'out of ascii: été au cœur' -m "$testChars"
+        git log
+    } >/dev/null 2>&1
+fi