gitlogstats 1.5.0__tar.gz → 1.5.2__tar.gz

{gitlogstats-1.5.0 → gitlogstats-1.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gitlogstats
-Version: 1.5.0
+Version: 1.5.2
 Summary: Track developers' contributions to one or more git repositories within a particular time range.
 Project-URL: Homepage, https://github.com/bloombar/gitlogstats
 Project-URL: Repository, https://github.com/bloombar/gitlogstats.git

gitlogstats-1.5.2/docs/examples/README.md

@@ -0,0 +1,70 @@
+# Examples
+
+## `assignment-stats.sh`: statistics for one assignment
+
+Reports every student's contributions to one assignment: all the repositories in a GitHub organization whose names start with the same prefix (e.g. `web-app-exercise-`), over a date range. It works in bash on macOS, Linux, WSL and Git Bash on Windows.
+
+### Requirements
+
+- Python 3
+- git
+- The [GitHub CLI](https://cli.github.com) (`gh`), signed in with `gh auth login`
+
+You don't need to install `gitlogstats` yourself: the script installs or upgrades it each time it runs (see [What the script does](#what-the-script-does)).
+
+### Usage
+
+```bash
+./assignment-stats.sh ORGANIZATION_NAME REPO_PREFIX START_DATE END_DATE [gitlogstats options...]
+```
+
+| Argument            | Meaning                                                                | Example                      |
+| ------------------- | ---------------------------------------------------------------------- | ---------------------------- |
+| `ORGANIZATION_NAME` | The GitHub organization that holds the students' repositories          | `software-students-fall2029` |
+| `REPO_PREFIX`       | The start of the repository names for this assignment                  | `web-app-exercise-`          |
+| `START_DATE`        | First day of the period, `mm/dd/yyyy`                                  | `09/01/2029`                 |
+| `END_DATE`          | Last day of the period, `mm/dd/yyyy` (included)                        | `10/16/2029`                 |
+| options             | Anything after the four arguments is passed to `gitlogstats` unchanged | `-f markdown`                |
+
+Run it from any directory. The results are printed to standard output, so redirect them to save them; progress messages go to standard error and stay on screen.
+
+### Examples
+
+Save a CSV of one assignment's statistics:
+
+```bash
+./assignment-stats.sh software-students-fall2029 web-app-exercise- 09/01/2029 10/16/2029 > web-app-exercise.csv
+```
+
+Print a Markdown table instead:
+
+```bash
+./assignment-stats.sh software-students-fall2029 web-app-exercise- 09/01/2029 10/16/2029 -f markdown
+```
+
+Leave out students with no activity in the period, as JSON:
+
+```bash
+./assignment-stats.sh software-students-fall2029 web-app-exercise- 09/01/2029 10/16/2029 -c -f json > web-app-exercise.json
+```
+
+To run it from elsewhere, give its path, e.g. `bash docs/examples/assignment-stats.sh ...`. On Windows, run it from Git Bash or WSL, not from Command Prompt or PowerShell.
+
+See the main [README](../../README.md) for every `gitlogstats` option and what each column means.
+
+### What the script does
+
+1. Checks the arguments and that Python, git and `gh` are installed and `gh` is signed in. If anything is missing it stops with a message saying what.
+2. Installs or upgrades `gitlogstats` in a Python environment of its own, `~/.gitlogstats-venv`, reused by later runs. Set `GITLOGSTATS_VENV` to keep it elsewhere. A separate environment is needed because Homebrew Python and recent Debian and Ubuntu releases refuse a system-wide `pip install`.
+3. Lists the organization's repositories whose names start with `REPO_PREFIX`, into a temporary file that is deleted when the script ends, even after an error. An existing `repos.txt` in your directory is never touched. If no repository matches, it stops with an error.
+4. Runs `gitlogstats` on those repositories with `--github` and `--clobber`. `--github` adds the GitHub columns (pull requests, pushes, website commits and emails) and combines each student's git names into one row; `--clobber` deletes the clones it makes in `./repos/` once the results are printed.
+
+### Troubleshooting
+
+| Message                                                  | What to do                                                                                            |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `'...' is not a date in mm/dd/yyyy format`               | Write dates with two-digit month and day and a four-digit year, e.g. `09/01/2029`                     |
+| `the GitHub CLI is not signed in`                        | Run `gh auth login`                                                                                   |
+| `no repositories in '...' start with '...'`              | Check the organization name and prefix; the prefix is case-sensitive                                  |
+| `could not create a virtual environment`                 | On Debian or Ubuntu, install the venv module: `sudo apt install python3-venv`                         |
+| `Permission denied` when running `./assignment-stats.sh` | Make it executable with `chmod +x assignment-stats.sh`, or run it with `bash assignment-stats.sh ...` |

gitlogstats-1.5.2/docs/examples/assignment-stats.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# Report every student's contributions to one assignment: all repositories in
+# a GitHub organization whose names start with a given prefix, over a date
+# range. Works in bash on macOS, Linux, other Unix systems, WSL and Git Bash.
+#
+# Usage:
+#   ./assignment-stats.sh ORGANIZATION_NAME REPO_PREFIX START_DATE END_DATE [gitlogstats options...]
+#
+# Example:
+#   ./assignment-stats.sh software-students-fall2029 web-app-exercise- 09/01/2029 10/16/2029 > stats.csv
+#   ./assignment-stats.sh software-students-fall2029 web-app-exercise- 09/01/2029 10/16/2029 -f markdown
+#
+# Dates are mm/dd/yyyy and both days are included. gitlogstats always runs
+# with --github, so the GitHub columns are included. Any options after the four
+# arguments are passed to gitlogstats unchanged (e.g. -f json, -c).
+# The results go to standard output; progress messages go to standard error.
+#
+# Requires: Python 3, git, and the GitHub CLI (gh), signed in with
+# `gh auth login` (gh is used to list the organization's repositories).
+# gitlogstats is installed or upgraded automatically in its own Python
+# environment (~/.gitlogstats-venv, or $GITLOGSTATS_VENV).
+
+set -euo pipefail
+
+usage() {
+  echo "usage: $(basename "$0") ORGANIZATION_NAME REPO_PREFIX START_DATE END_DATE [gitlogstats options...]" >&2
+  echo "example: $(basename "$0") software-students-fall2029 web-app-exercise- 09/01/2029 10/16/2029" >&2
+}
+
+if [ "$#" -lt 4 ]; then
+  usage
+  exit 2
+fi
+
+# retrieve command-line arguments
+ORGANIZATION_NAME=$1
+REPO_PREFIX=$2
+START_DATE=$3
+END_DATE=$4
+shift 4 # anything left is passed to gitlogstats
+
+# check the dates before doing any work
+for date in "$START_DATE" "$END_DATE"; do
+  if ! [[ "$date" =~ ^[0-9]{2}/[0-9]{2}/[0-9]{4}$ ]]; then
+    echo "error: '$date' is not a date in mm/dd/yyyy format" >&2
+    usage
+    exit 2
+  fi
+done
+
+# find a Python 3 interpreter: python3 on macOS and Linux, often python on Git Bash
+if command -v python3 >/dev/null 2>&1; then
+  PYTHON=python3
+elif command -v python >/dev/null 2>&1; then
+  PYTHON=python
+else
+  echo "error: Python 3 is not installed" >&2
+  exit 1
+fi
+
+for tool in git gh; do
+  if ! command -v "$tool" >/dev/null 2>&1; then
+    echo "error: '$tool' is not installed" >&2
+    exit 1
+  fi
+done
+
+if ! gh auth status >/dev/null 2>&1; then
+  echo "error: the GitHub CLI is not signed in; run 'gh auth login' first" >&2
+  exit 1
+fi
+
+# install or upgrade gitlogstats in a virtual environment of its own: many
+# systems (Homebrew Python, recent Debian and Ubuntu) refuse a system-wide
+# pip install. The environment is kept and reused by later runs; set
+# GITLOGSTATS_VENV to put it somewhere else.
+VENV=${GITLOGSTATS_VENV:-"$HOME/.gitlogstats-venv"}
+if [ ! -d "$VENV" ]; then
+  echo "Creating a Python environment for gitlogstats in $VENV..." >&2
+  if ! "$PYTHON" -m venv "$VENV"; then
+    echo "error: could not create a virtual environment (on Debian or Ubuntu, install python3-venv)" >&2
+    exit 1
+  fi
+fi
+# the environment's Python is in bin/ on macOS, Linux and WSL, Scripts/ on Windows
+if [ -x "$VENV/bin/python" ]; then
+  VENV_PYTHON="$VENV/bin/python"
+else
+  VENV_PYTHON="$VENV/Scripts/python.exe"
+fi
+echo "Installing the latest gitlogstats..." >&2
+"$VENV_PYTHON" -m pip install --quiet --disable-pip-version-check --upgrade gitlogstats >&2
+
+# list the assignment's repositories in a temporary file, so an existing
+# repos.txt in this directory is never overwritten
+REPOS_FILE=$(mktemp "${TMPDIR:-/tmp}/gitlogstats-repos.XXXXXX")
+trap 'rm -f "$REPOS_FILE"' EXIT
+
+# the prefix is read by gh's built-in jq from an environment variable, so it
+# needs no quoting and jq does not have to be installed
+REPO_PREFIX="$REPO_PREFIX" gh repo list "$ORGANIZATION_NAME" --limit 1000 \
+  --json name,url \
+  --jq '.[] | select(.name | startswith(env.REPO_PREFIX)) | .url' >"$REPOS_FILE"
+
+count=$(grep -c . "$REPOS_FILE" || true)
+if [ "$count" -eq 0 ]; then
+  echo "error: no repositories in '$ORGANIZATION_NAME' start with '$REPO_PREFIX'" >&2
+  exit 1
+fi
+echo "Analyzing $count repositories from $START_DATE to $END_DATE..." >&2
+
+# --github adds the GitHub columns (pull requests, pushes, website commits,
+# emails) and combines each student's git names into one row; --clobber
+# deletes the clones once the results are printed
+"$VENV_PYTHON" -m gitlogstats -rf "$REPOS_FILE" -s "$START_DATE" -e "$END_DATE" \
+  --github --clobber "$@"

{gitlogstats-1.5.0 → gitlogstats-1.5.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "gitlogstats"
 description = "Track developers' contributions to one or more git repositories within a particular time range."
-version = "1.5.0"
+version = "1.5.2"
 authors = [
   { name="Tobody Tothing", email="nobody.nothing@nowhere.com" },
 ]