gitlogstats 1.0.9__tar.gz → 1.1.0__tar.gz

{gitlogstats-1.0.9 → gitlogstats-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gitlogstats
-Version: 1.0.9
+Version: 1.1.0
 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
@@ -709,6 +709,8 @@ This script calculates the following, for each developer in each repository:
 - number of **files changed**
 - number of **merges** into the analyzed branch
 
+With `--github`, it also reports each developer's GitHub **pull requests** opened, merged and closed without merging (see [GitHub pull requests](#github-pull-requests)).
+
 The results can be formatted as `csv`, `json`, or `markdown`.
 
 ## Install
@@ -722,26 +724,36 @@ e.g. `pip install gitlogstats`, `pip3 install gitlogstats`, depending on your en
 The command `gitlogstats --help` shows the usage instructions:
 
 ```
-usage: gitlogstats [-h] (-r REPOSITORY | -rf REPOFILE) [-u USER] [-s START] [-e END] [-x EXCLUSIONS] [-f {csv,json,markdown}] [-b BRANCH] [-v] [-c]
+usage: gitlogstats [-h] (-r REPOSITORY | -rf REPOFILE) [-u USER] [-s START]
+                   [-e END] [-x EXCLUSIONS] [-f {csv,json,markdown}]
+                   [-b BRANCH] [-v] [-c] [--github]
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   -r REPOSITORY, --repository REPOSITORY
                         the public URL of the repository whose logs to parse
   -rf REPOFILE, --repofile REPOFILE
-                        the path to simple text file with a list of repository URLs to parse
-  -u USER, --user USER  The git username (or email address) to report. Default is all contributing users
+                        the path to simple text file with a list of repository
+                        URLs to parse
+  -u USER, --user USER  The git username (or email address) to report. Default
+                        is all contributing users
   -s START, --start START
                         Start date in mm/dd/yyyy format
   -e END, --end END     End date in mm/dd/yyyy format
   -x EXCLUSIONS, --exclusions EXCLUSIONS
-                        A comma-separated list of files, patterns or directories to exclude, e.g. --exclusions "foo.zip, *.jpg, vendor". Replaces the default list; use "" to exclude nothing
+                        A comma-separated list of files, patterns or
+                        directories to exclude, e.g. --exclusions "foo.zip,
+                        *.jpg, vendor". Replaces the default list; use "" to
+                        exclude nothing
   -f {csv,json,markdown}, --format {csv,json,markdown}
                         The format in which to output the results
   -b BRANCH, --branch BRANCH
-                        The branch to checkout before compiling statistics. Defaults to the repository's default branch.
+                        The branch to parse, if not the default branch
   -v, --verbose         Whether to output debugging info
   -c, --clean           Remove contributors without any contribuition
+  --github              Also report GitHub pull requests opened, merged and
+                        closed per contributor, and match GitHub users to git
+                        authors. Needs the GitHub CLI (gh), signed in
 ```
 
 In case `gitlogstats` is not found as a command, even after installing, try `python -m gitlogstats` or `python3 -m gitlogstats` instead.
@@ -822,6 +834,46 @@ By default, every contributor in a repository's history is listed, with zeros fo
 gitlogstats -rf repos.txt -c
 ```
 
+### GitHub pull requests
+
+Add `--github` to also count each contributor's pull requests. Four columns are appended to every output format:
+
+| Column                | Meaning                                                                                               |
+| --------------------- | ----------------------------------------------------------------------------------------------------- |
+| `github_username`     | the GitHub account matched to the contributor (never the display name), so you can check the matching |
+| `prs_opened`          | pull requests they opened in the date range, whatever their state now (drafts included)               |
+| `prs_merged`          | pull requests they authored that were merged in the date range, by anyone and in any way (squash too) |
+| `prs_closed_unmerged` | pull requests they authored that were closed without merging in the date range                        |
+
+```
+gitlogstats -r https://github.com/bloombar/gitlogstats.git --github
+```
+
+**Requirements.** Only `--github` needs the [GitHub CLI](https://cli.github.com) (`gh`); without the flag nothing changes and GitHub is never contacted. Install `gh`, then run `gh auth login`. The tool checks this before cloning anything. If it fails, nothing is printed to standard output, the exit status is 1 and one of these messages is printed to standard error:
+
+```
+gitlogstats: --github needs the GitHub CLI (gh), which is not installed. Install it from https://cli.github.com and run 'gh auth login', or run without --github.
+gitlogstats: --github needs the GitHub CLI (gh) to be signed in. Run 'gh auth login', or run without --github.
+```
+
+**Empty versus zero.** A zero means GitHub was asked and the person has none. An empty value (`null` in JSON) means GitHub could not be asked for that repository: it is not on github.com, or the request failed (no network, rate limit, a private repository you cannot see). The git statistics are still reported, the reason is printed to standard error, and the other repositories carry on. A contributor with no GitHub account matched has an empty `github_username` and zero pull requests. A GitHub user who opened pull requests but has no commits is listed in a row of their own with an empty `username` and zero git statistics.
+
+**Matching GitHub users to git authors.** Each git author name is compared with the GitHub users active in the repository, trying these in order and stopping at the first that finds exactly one user:
+
+1. **Email.** The email is a GitHub `noreply` address containing the username, GitHub itself links one of the author's commits to an account, or the email is the public email of a GitHub profile.
+2. **Username.** The author name, or the part of the email before the `@`, is the GitHub username (ignoring case, and treating spaces, hyphens, underscores and dots as alike). The part before the `@` is skipped when it names a role rather than a person (such as `noreply`, `admin` or `info`), or when several author names in the repository share it (`alex@gmail…` and `alex@school…`), since it could belong to either.
+3. **Display name.** The author name is the GitHub profile name (ignoring case, accents, punctuation and word order, so `Grace Hopper` matches `Hopper, Grace`).
+
+If a step finds several users it is skipped as ambiguous and the next is tried. All git names matched to one GitHub user become one row: the `username` is the name with the most commits and the git statistics are added up. Use `-v` to see which step matched each name, the ambiguous and unmatched names, and how many `gh` calls were made. A wrong match can be fixed with a `.mailmap` file.
+
+**How the other options apply.**
+
+- `-s` / `-e`: each pull request count uses its own timestamp (opened, merged or closed) against the same inclusive local-time range as commits.
+- `-b`: only pull requests whose base branch is that branch are counted; without `-b`, all pull requests count.
+- `-u`: selects the combined row whose author names or emails equal the value exactly, or whose GitHub username equals it ignoring case. The whole combined row is reported, so `-u` with one email address also includes the person's commits under their other names and emails, and a value that matches nobody prints no row.
+- `-c`: removes only rows with no git activity and no pull requests.
+- `-x`: has no effect on pull requests.
+
 ### Formatting the results
 
 The results can be formatted as `csv`, `json`, or a `markdown` table. The default is `csv`. Use the `-f` flag to control the output format.

{gitlogstats-1.0.9 → gitlogstats-1.1.0}/README.md

@@ -12,6 +12,8 @@ This script calculates the following, for each developer in each repository:
 - number of **files changed**
 - number of **merges** into the analyzed branch
 
+With `--github`, it also reports each developer's GitHub **pull requests** opened, merged and closed without merging (see [GitHub pull requests](#github-pull-requests)).
+
 The results can be formatted as `csv`, `json`, or `markdown`.
 
 ## Install
@@ -25,26 +27,36 @@ e.g. `pip install gitlogstats`, `pip3 install gitlogstats`, depending on your en
 The command `gitlogstats --help` shows the usage instructions:
 
 ```
-usage: gitlogstats [-h] (-r REPOSITORY | -rf REPOFILE) [-u USER] [-s START] [-e END] [-x EXCLUSIONS] [-f {csv,json,markdown}] [-b BRANCH] [-v] [-c]
+usage: gitlogstats [-h] (-r REPOSITORY | -rf REPOFILE) [-u USER] [-s START]
+                   [-e END] [-x EXCLUSIONS] [-f {csv,json,markdown}]
+                   [-b BRANCH] [-v] [-c] [--github]
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   -r REPOSITORY, --repository REPOSITORY
                         the public URL of the repository whose logs to parse
   -rf REPOFILE, --repofile REPOFILE
-                        the path to simple text file with a list of repository URLs to parse
-  -u USER, --user USER  The git username (or email address) to report. Default is all contributing users
+                        the path to simple text file with a list of repository
+                        URLs to parse
+  -u USER, --user USER  The git username (or email address) to report. Default
+                        is all contributing users
   -s START, --start START
                         Start date in mm/dd/yyyy format
   -e END, --end END     End date in mm/dd/yyyy format
   -x EXCLUSIONS, --exclusions EXCLUSIONS
-                        A comma-separated list of files, patterns or directories to exclude, e.g. --exclusions "foo.zip, *.jpg, vendor". Replaces the default list; use "" to exclude nothing
+                        A comma-separated list of files, patterns or
+                        directories to exclude, e.g. --exclusions "foo.zip,
+                        *.jpg, vendor". Replaces the default list; use "" to
+                        exclude nothing
   -f {csv,json,markdown}, --format {csv,json,markdown}
                         The format in which to output the results
   -b BRANCH, --branch BRANCH
-                        The branch to checkout before compiling statistics. Defaults to the repository's default branch.
+                        The branch to parse, if not the default branch
   -v, --verbose         Whether to output debugging info
   -c, --clean           Remove contributors without any contribuition
+  --github              Also report GitHub pull requests opened, merged and
+                        closed per contributor, and match GitHub users to git
+                        authors. Needs the GitHub CLI (gh), signed in
 ```
 
 In case `gitlogstats` is not found as a command, even after installing, try `python -m gitlogstats` or `python3 -m gitlogstats` instead.
@@ -125,6 +137,46 @@ By default, every contributor in a repository's history is listed, with zeros fo
 gitlogstats -rf repos.txt -c
 ```
 
+### GitHub pull requests
+
+Add `--github` to also count each contributor's pull requests. Four columns are appended to every output format:
+
+| Column                | Meaning                                                                                               |
+| --------------------- | ----------------------------------------------------------------------------------------------------- |
+| `github_username`     | the GitHub account matched to the contributor (never the display name), so you can check the matching |
+| `prs_opened`          | pull requests they opened in the date range, whatever their state now (drafts included)               |
+| `prs_merged`          | pull requests they authored that were merged in the date range, by anyone and in any way (squash too) |
+| `prs_closed_unmerged` | pull requests they authored that were closed without merging in the date range                        |
+
+```
+gitlogstats -r https://github.com/bloombar/gitlogstats.git --github
+```
+
+**Requirements.** Only `--github` needs the [GitHub CLI](https://cli.github.com) (`gh`); without the flag nothing changes and GitHub is never contacted. Install `gh`, then run `gh auth login`. The tool checks this before cloning anything. If it fails, nothing is printed to standard output, the exit status is 1 and one of these messages is printed to standard error:
+
+```
+gitlogstats: --github needs the GitHub CLI (gh), which is not installed. Install it from https://cli.github.com and run 'gh auth login', or run without --github.
+gitlogstats: --github needs the GitHub CLI (gh) to be signed in. Run 'gh auth login', or run without --github.
+```
+
+**Empty versus zero.** A zero means GitHub was asked and the person has none. An empty value (`null` in JSON) means GitHub could not be asked for that repository: it is not on github.com, or the request failed (no network, rate limit, a private repository you cannot see). The git statistics are still reported, the reason is printed to standard error, and the other repositories carry on. A contributor with no GitHub account matched has an empty `github_username` and zero pull requests. A GitHub user who opened pull requests but has no commits is listed in a row of their own with an empty `username` and zero git statistics.
+
+**Matching GitHub users to git authors.** Each git author name is compared with the GitHub users active in the repository, trying these in order and stopping at the first that finds exactly one user:
+
+1. **Email.** The email is a GitHub `noreply` address containing the username, GitHub itself links one of the author's commits to an account, or the email is the public email of a GitHub profile.
+2. **Username.** The author name, or the part of the email before the `@`, is the GitHub username (ignoring case, and treating spaces, hyphens, underscores and dots as alike). The part before the `@` is skipped when it names a role rather than a person (such as `noreply`, `admin` or `info`), or when several author names in the repository share it (`alex@gmail…` and `alex@school…`), since it could belong to either.
+3. **Display name.** The author name is the GitHub profile name (ignoring case, accents, punctuation and word order, so `Grace Hopper` matches `Hopper, Grace`).
+
+If a step finds several users it is skipped as ambiguous and the next is tried. All git names matched to one GitHub user become one row: the `username` is the name with the most commits and the git statistics are added up. Use `-v` to see which step matched each name, the ambiguous and unmatched names, and how many `gh` calls were made. A wrong match can be fixed with a `.mailmap` file.
+
+**How the other options apply.**
+
+- `-s` / `-e`: each pull request count uses its own timestamp (opened, merged or closed) against the same inclusive local-time range as commits.
+- `-b`: only pull requests whose base branch is that branch are counted; without `-b`, all pull requests count.
+- `-u`: selects the combined row whose author names or emails equal the value exactly, or whose GitHub username equals it ignoring case. The whole combined row is reported, so `-u` with one email address also includes the person's commits under their other names and emails, and a value that matches nobody prints no row.
+- `-c`: removes only rows with no git activity and no pull requests.
+- `-x`: has no effect on pull requests.
+
 ### Formatting the results
 
 The results can be formatted as `csv`, `json`, or a `markdown` table. The default is `csv`. Use the `-f` flag to control the output format.

{gitlogstats-1.0.9 → gitlogstats-1.1.0}/docs/SPEC.md

@@ -35,7 +35,7 @@ Repositories are cloned into a `repos/` directory under the current working dire
 
 #### REPO-4 Branch selection
 
-`-b/--branch <name>` checks out the given branch before statistics are computed. Without `-b`, the repository's default branch is used — including when an earlier run left the cached clone on another branch.
+`-b/--branch <name>` checks out the given branch before statistics are computed. Without `-b`, the repository's default branch is used — including when an earlier run left the cached clone on another branch. With `--github`, it also limits which pull requests are counted to those whose base branch is that branch (CLI-3).
 
 **Status:** Done
 
@@ -83,17 +83,48 @@ For each contributor, the number of merge commits they authored directly on the
 
 **Status:** Done
 
+#### STAT-8 Pull requests opened
+
+With `--github` (CLI-3), for each contributor, the number of pull requests they authored on GitHub whose creation time (`created_at`) falls in the date range, whatever their state now (open, merged or closed; drafts included). Reported in a `prs_opened` column.
+
+**Status:** Done
+
+#### STAT-9 Pull requests merged
+
+With `--github`, for each contributor, the number of pull requests they authored that were merged (`merged_at` set) in the date range, whoever merged them. Reported in a `prs_merged` column. Unlike merges (STAT-7), this counts squash and rebase merges too, since GitHub records them as merged pull requests.
+
+**Status:** Done
+
+#### STAT-10 Pull requests closed without merging
+
+With `--github`, for each contributor, the number of pull requests they authored that were closed without being merged (`state` closed and `merged_at` not set), with a closing time (`closed_at`) in the date range. Reported in a `prs_closed_unmerged` column.
+
+**Status:** Done
+
+#### STAT-11 Matching GitHub users to git authors
+
+With `--github`, each pull-request author (a GitHub username) is matched to the git identities (author name and email) in the repository's history. Each git identity is tried against the GitHub users active in that repository (pull-request authors and the accounts GitHub links to its commits), tier by tier, stopping at the first tier that finds exactly one GitHub user:
+
+1. **Email.** The email is a GitHub `noreply` address (`12345+login@users.noreply.github.com` or `login@users.noreply.github.com`); or GitHub links one of the identity's commits to an account (the commit's `author.login`, which covers private emails GitHub knows but does not publish); or the email equals a candidate's public profile email (case-insensitive).
+2. **Username.** The author name, or the email's local part (before `@`), equals a candidate's GitHub username, ignoring case and treating spaces, hyphens, underscores and dots as the same (`Ada Lovelace` matches `Ada-Lovelace`). An email local part is not used when it names a role rather than a person (such as `noreply`, `admin` or `info`), or when it is shared by several author names in the repository (`alex@gmail…` and `alex@school…`), since it could belong to either.
+3. **Display name.** The author name equals a candidate's GitHub display name, ignoring case, accents, repeated spaces and punctuation, and word order (`Grace Hopper` matches `Hopper, Grace`).
+4. **No match.** A GitHub user matched by no git identity is reported in a row of its own, with an empty `username`, its pull-request statistics and zero git statistics.
+
+If a tier finds several GitHub users for one identity, that tier is skipped as ambiguous and the next is tried; ambiguous and unmatched identities are listed with `-v`. All git identities matched to the same GitHub user are combined into one row: the `username` is the matched author name with the most commits (ties broken alphabetically), and the git statistics are summed. A git identity matched to no GitHub user keeps its own row with an empty `github_username` and zero pull-request statistics. Every row carries the matched GitHub username (never the display name) in a `github_username` column, so matches can be checked and corrected by hand, e.g. with a `.mailmap` (STAT-6).
+
+**Status:** Done
+
 ### 3. Filtering
 
 #### FILT-1 Date range
 
-`-s/--start` and `-e/--end` (format `mm/dd/yyyy`) limit the analysis to commits whose commit date falls between the start of the start date and the end of the end date, inclusive, in local time. Defaults: one year ago until today. The output records the requested start and end dates on every row.
+`-s/--start` and `-e/--end` (format `mm/dd/yyyy`) limit the analysis to commits whose commit date falls between the start of the start date and the end of the end date, inclusive, in local time. Defaults: one year ago until today. The output records the requested start and end dates on every row. With `--github`, each pull request count is filtered by its own timestamp in the same range (CLI-3).
 
 **Status:** Done
 
 #### FILT-2 Single contributor
 
-`-u/--user <name>` reports only the contributor whose author name or email address matches exactly. Without `-u`, every contributor in the repository's history is reported.
+`-u/--user <name>` reports only the contributor whose author name or email address matches exactly. Without `-u`, every contributor in the repository's history is reported. With `--github`, it selects the combined row, and a value may also be the GitHub username (ignoring case); see CLI-3.
 
 **Status:** Done
 
@@ -105,7 +136,7 @@ For each contributor, the number of merge commits they authored directly on the
 
 #### FILT-4 Remove inactive contributors
 
-By default, contributors with no activity in the date range are listed with zeros. `-c/--clean` removes them.
+By default, contributors with no activity in the date range are listed with zeros. `-c/--clean` removes them. With `--github`, only rows with neither git nor pull-request activity are removed (CLI-3).
 
 **Status:** Done
 
@@ -113,7 +144,7 @@ By default, contributors with no activity in the date range are listed with zero
 
 #### OUT-1 CSV output
 
-`-f csv` (the default) prints a header row followed by one row per contributor per repository, with fields `username, repository, start_date, end_date, commits, insertions, deletions, files, merges`. New fields are added at the end so existing column positions do not change. Values containing commas, quotes or line breaks are quoted. The header is printed even when there are no rows, and the output ends with a single newline.
+`-f csv` (the default) prints a header row followed by one row per contributor per repository, with fields `username, repository, start_date, end_date, commits, insertions, deletions, files, merges`. New fields are added at the end so existing column positions do not change. Values containing commas, quotes or line breaks are quoted. The header is printed even when there are no rows, and the output ends with a single newline. With `--github`, the columns `github_username, prs_opened, prs_merged, prs_closed_unmerged` are appended, and are in the header even when there are no rows (CLI-3).
 
 **Status:** Done
 
@@ -137,7 +168,7 @@ When several repositories are analyzed, the results are printed once, after all
 
 #### OUT-5 Verbose diagnostics
 
-`-v/--verbose` prints debugging information (directories, the git commands run, contributors found) to standard error, so standard output stays machine-readable.
+`-v/--verbose` prints debugging information (directories, the git commands run, contributors found) to standard error, so standard output stays machine-readable. With `--github`, it also prints how each author name was matched to a GitHub user, the ambiguous and unmatched names, and the number of `gh` API calls made for each repository (CLI-3).
 
 **Status:** Done
 
@@ -155,6 +186,17 @@ Invalid dates, and a start date after the end date, are rejected with a usage er
 
 **Status:** Done
 
+#### CLI-3 GitHub pull-request statistics
+
+`--github` adds GitHub pull-request statistics (STAT-8 to STAT-11) for repositories hosted on github.com, appending the columns `github_username, prs_opened, prs_merged, prs_closed_unmerged` to every output format. Without `--github`, the output and behaviour are unchanged, GitHub is never contacted and the GitHub CLI (`gh`) is not needed. With `--github`, the GitHub API is called through `gh api`, so `gh` must be installed and signed in. This is checked before any repository is cloned; if it fails, nothing is printed to standard output, the tool exits with status 1, and one plain message on standard error says why and what to do — no stack trace:
+
+- `gh` not found: `gitlogstats: --github needs the GitHub CLI (gh), which is not installed. Install it from https://cli.github.com and run 'gh auth login', or run without --github.`
+- `gh` not signed in (`gh auth status` fails): `gitlogstats: --github needs the GitHub CLI (gh) to be signed in. Run 'gh auth login', or run without --github.`
+
+The other options apply to pull requests as follows: `-s/-e` filter each count by its own timestamp, using the same inclusive local-time range as FILT-1; `-u` selects the combined row whose author names, emails or GitHub username match exactly (the username ignoring case); `-b` counts only pull requests whose base branch is that branch, and without `-b` every pull request counts; `-c` removes only rows with neither git nor pull-request activity; `-x` does not apply. For a repository not on github.com, or when GitHub cannot be reached for one repository (no network, rate limit, private repository without access), the git statistics are still reported, the four GitHub columns are empty (`null` in JSON) rather than zero, and the reason is printed to standard error.
+
+**Status:** Done
+
 ### 6. Packaging & Quality
 
 #### PKG-1 Installable package
@@ -189,3 +231,7 @@ The CI workflow runs the test suite on every push and stops the release if any t
 - **Parallel processing** — clone and analyze many repositories concurrently to speed up large batches.
 - **Per-file breakdown** — optionally report each contributor's changes per file or directory.
 - **Output to file** — write results to a file (e.g. `-o report.csv`) instead of only standard output.
+- **GitHub without the gh CLI** — let `--github` call the GitHub API directly with a `GITHUB_TOKEN`, for users who cannot install `gh`.
+- **GitHub Enterprise hosts** — extend `--github` to repositories on GitHub Enterprise Server, via `gh api --hostname` or a configurable API URL.
+- **Pull-request reviews and mergers** — report who reviewed and who merged each pull request, in addition to who opened it.
+- **GitHub-only mode** — report pull-request statistics without computing git statistics, for faster runs over large batches.

{gitlogstats-1.0.9 → gitlogstats-1.1.0}/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.0.9"
+version = "1.1.0"
 authors = [
   { name="Tobody Tothing", email="nobody.nothing@nowhere.com" },
 ]

{gitlogstats-1.0.9 → gitlogstats-1.1.0}/scripts/board/manifest.yaml

@@ -17,12 +17,30 @@
   family: CLI
   phase: 1
   status: Done
+- id: CLI-3
+  title: GitHub pull-request statistics
+  full: "--github adds GitHub pull-request statistics (STAT-8 to STAT-11) for
+    repositories hosted on github.com, appending the columns github_username,
+    prs_opened, prs_merged, prs_closed_unmerged to every output format. Without
+    --github, the output and behaviour are unchanged, GitHub is never contacted
+    and the GitHub CLI (gh) is not needed. With --github, the GitHub API is
+    called through gh api, so gh must be installed and signed in. This is
+    checked before any repository is cloned; if it fails, nothing is printed to
+    standard output, the tool exits with status 1, and one plain message on
+    standard error says why and what to do — no stack trace: gh not found:
+    gitlogstats: --github needs the GitHub CLI…"
+  section: §5 Command-Line Interface
+  family: CLI
+  phase: 1
+  status: Done
 - id: FILT-1
   title: Date range
   full: "-s/--start and -e/--end (format mm/dd/yyyy) limit the analysis to commits
     whose commit date falls between the start of the start date and the end of
     the end date, inclusive, in local time. Defaults: one year ago until today.
-    The output records the requested start and end dates on every row."
+    The output records the requested start and end dates on every row. With
+    --github, each pull request count is filtered by its own timestamp in the
+    same range (CLI-3)."
   section: §3 Filtering
   family: FILT
   phase: 1
@@ -31,7 +49,8 @@
   title: Single contributor
   full: -u/--user <name> reports only the contributor whose author name or email
     address matches exactly. Without -u, every contributor in the repository's
-    history is reported.
+    history is reported. With --github, it selects the combined row, and a value
+    may also be the GitHub username (ignoring case); see CLI-3.
   section: §3 Filtering
   family: FILT
   phase: 1
@@ -55,7 +74,8 @@
 - id: FILT-4
   title: Remove inactive contributors
   full: By default, contributors with no activity in the date range are listed
-    with zeros. -c/--clean removes them.
+    with zeros. -c/--clean removes them. With --github, only rows with neither
+    git nor pull-request activity are removed (CLI-3).
   section: §3 Filtering
   family: FILT
   phase: 1
@@ -67,7 +87,10 @@
     end_date, commits, insertions, deletions, files, merges. New fields are
     added at the end so existing column positions do not change. Values
     containing commas, quotes or line breaks are quoted. The header is printed
-    even when there are no rows, and the output ends with a single newline.
+    even when there are no rows, and the output ends with a single newline. With
+    --github, the columns github_username, prs_opened, prs_merged,
+    prs_closed_unmerged are appended, and are in the header even when there are
+    no rows (CLI-3).
   section: §4 Output
   family: OUT
   phase: 1
@@ -101,7 +124,9 @@
   title: Verbose diagnostics
   full: -v/--verbose prints debugging information (directories, the git commands
     run, contributors found) to standard error, so standard output stays
-    machine-readable.
+    machine-readable. With --github, it also prints how each author name was
+    matched to a GitHub user, the ambiguous and unmatched names, and the number
+    of gh API calls made for each repository (CLI-3).
   section: §4 Output
   family: OUT
   phase: 1
@@ -172,7 +197,9 @@
   title: Branch selection
   full: -b/--branch <name> checks out the given branch before statistics are
     computed. Without -b, the repository's default branch is used — including
-    when an earlier run left the cached clone on another branch.
+    when an earlier run left the cached clone on another branch. With --github,
+    it also limits which pull requests are counted to those whose base branch is
+    that branch (CLI-3).
   section: §1 Repository Selection
   family: REPO
   phase: 1
@@ -255,6 +282,53 @@
   family: STAT
   phase: 1
   status: Done
+- id: STAT-8
+  title: Pull requests opened
+  full: With --github (CLI-3), for each contributor, the number of pull requests
+    they authored on GitHub whose creation time (created_at) falls in the date
+    range, whatever their state now (open, merged or closed; drafts included).
+    Reported in a prs_opened column.
+  section: §2 Contribution Statistics
+  family: STAT
+  phase: 1
+  status: Done
+- id: STAT-9
+  title: Pull requests merged
+  full: With --github, for each contributor, the number of pull requests they
+    authored that were merged (merged_at set) in the date range, whoever merged
+    them. Reported in a prs_merged column. Unlike merges (STAT-7), this counts
+    squash and rebase merges too, since GitHub records them as merged pull
+    requests.
+  section: §2 Contribution Statistics
+  family: STAT
+  phase: 1
+  status: Done
+- id: STAT-10
+  title: Pull requests closed without merging
+  full: With --github, for each contributor, the number of pull requests they
+    authored that were closed without being merged (state closed and merged_at
+    not set), with a closing time (closed_at) in the date range. Reported in a
+    prs_closed_unmerged column.
+  section: §2 Contribution Statistics
+  family: STAT
+  phase: 1
+  status: Done
+- id: STAT-11
+  title: Matching GitHub users to git authors
+  full: "With --github, each pull-request author (a GitHub username) is matched to
+    the git identities (author name and email) in the repository's history. Each
+    git identity is tried against the GitHub users active in that repository
+    (pull-request authors and the accounts GitHub links to its commits), tier by
+    tier, stopping at the first tier that finds exactly one GitHub user: 1.
+    Email. The email is a GitHub noreply address
+    (12345+login@users.noreply.github.com or login@users.noreply.github.com); or
+    GitHub links one of the identity's commits to an account (the commit's
+    author.login, which covers private emails GitHub knows but does not
+    publish); or the email equals a candidate's public profile email…"
+  section: §2 Contribution Statistics
+  family: STAT
+  phase: 1
+  status: Done
 - id: FUTURE-author-date-filtering
   title: Author-date filtering
   full: Author-date filtering — offer filtering by author date, so rebased or
@@ -272,6 +346,30 @@
   family: FUTURE
   phase: 2
   status: Todo
+- id: FUTURE-github-enterprise-hosts
+  title: GitHub Enterprise hosts
+  full: GitHub Enterprise hosts — extend --github to repositories on GitHub
+    Enterprise Server, via gh api --hostname or a configurable API URL.
+  section: §7 Future Work
+  family: FUTURE
+  phase: 2
+  status: Todo
+- id: FUTURE-github-only-mode
+  title: GitHub-only mode
+  full: GitHub-only mode — report pull-request statistics without computing git
+    statistics, for faster runs over large batches.
+  section: §7 Future Work
+  family: FUTURE
+  phase: 2
+  status: Todo
+- id: FUTURE-github-without-the-gh-cli
+  title: GitHub without the gh CLI
+  full: GitHub without the gh CLI — let --github call the GitHub API directly with
+    a GITHUB_TOKEN, for users who cannot install gh.
+  section: §7 Future Work
+  family: FUTURE
+  phase: 2
+  status: Todo
 - id: FUTURE-output-to-file
   title: Output to file
   full: Output to file — write results to a file (e.g. -o report.csv) instead of
@@ -304,3 +402,11 @@
   family: FUTURE
   phase: 2
   status: Todo
+- id: FUTURE-pull-request-reviews-and-mergers
+  title: Pull-request reviews and mergers
+  full: Pull-request reviews and mergers — report who reviewed and who merged each
+    pull request, in addition to who opened it.
+  section: §7 Future Work
+  family: FUTURE
+  phase: 2
+  status: Todo

{gitlogstats-1.0.9 → gitlogstats-1.1.0}/src/gitlogstats/__main__.py

@@ -3,7 +3,11 @@ import subprocess
 import argparse
 import datetime
 import re
+import sys
 from . import GitLogsParser
+from .git_logs_parser import FIELDNAMES
+from .github import GITHUB_FIELDNAMES, GitHubUnavailable, check_gh
+from .github_stats import github_rows
 
 
 def valid_date(value):
@@ -135,6 +139,14 @@ def main():
         default=False,
         action="store_true",
     )
+    parser.add_argument(
+        "--github",
+        help="Also report GitHub pull requests opened, merged and closed per "
+        "contributor, and match GitHub users to git authors. Needs the GitHub CLI "
+        "(gh), signed in",
+        default=False,
+        action="store_true",
+    )
     args = parser.parse_args()
 
     if datetime.datetime.strptime(args.start, "%m/%d/%Y") > datetime.datetime.strptime(
@@ -145,6 +157,14 @@ def main():
     # split up comma-separated string into list, ignoring empty items
     args.exclusions = [x.strip() for x in re.split(r",", args.exclusions) if x.strip()]
 
+    # CLI-3: check the GitHub CLI before anything is created or cloned
+    if args.github:
+        try:
+            check_gh()
+        except GitHubUnavailable as exc:
+            print(exc, file=sys.stderr)
+            sys.exit(1)
+
     # deal with repofile, if specified
     repository_urls = [args.repository]
     if args.repofile:
@@ -193,20 +213,28 @@ def main():
                 ["git", "pull"], capture_output=True, check=True
             )  # get the latest code from github
 
+        # with --github, -u and -c are applied after GitHub users are combined
         last_parser = GitLogsParser(
             repo=repo_dir,
             start=args.start,
             end=args.end,
-            username=args.user,
+            username=None if args.github else args.user,
             exclusions=args.exclusions,
             verbose=args.verbose,
-            clean=args.clean,
+            clean=False if args.github else args.clean,
         )
-        all_results.extend(last_parser.parse())  # collect across repos
+        rows = last_parser.parse()
+        if args.github:
+            rows = github_rows(
+                last_parser, rows, repo_url, last_parser.get_identities(), args
+            )
+        all_results.extend(rows)  # collect across repos
 
     # emit a single table (or JSON array) covering all repositories
     if last_parser is not None:
-        output = last_parser.format_results(all_results, args.format)
+        # an empty CSV table still gets the GitHub columns with --github
+        fieldnames = FIELDNAMES + GITHUB_FIELDNAMES if args.github else None
+        output = last_parser.format_results(all_results, args.format, fieldnames)
         # end with exactly one newline: CSV and Markdown output already has one
         print(output, end="" if output.endswith("\n") else "\n")
 

{gitlogstats-1.0.9 → gitlogstats-1.1.0}/src/gitlogstats/git_logs_parser.py

@@ -93,6 +93,25 @@ class GitLogsParser:
         self.verboseprint(f"Contributors: {', '.join(contributors)}...")
         return contributors
 
+    def get_identities(self):
+        """
+        Return every identity (author name and email) in this repository's
+        history, the same population as get_contributors (STAT-11).
+        @returns: {author_name: {email: hash of one commit with that identity}}
+        """
+        cmd = ["git", "log", LOG_FORMAT]
+        self.verboseprint(f"Running command: {' '.join(cmd)}")
+        result = subprocess.run(cmd, capture_output=True, check=True)
+        identities = {}
+        for record in result.stdout.decode("utf-8", errors="replace").split(RECORD_SEP)[
+            1:
+        ]:
+            fields = record.strip("\n").split(FIELD_SEP)
+            name = fields[1].strip().strip("'")  # as get_contributors does
+            if name:
+                identities.setdefault(name, {}).setdefault(fields[2], fields[0])
+        return identities
+
     def date_range_args(self):
         """
         Build the git log options that limit commits to the date range.
@@ -275,11 +294,12 @@ class GitLogsParser:
             stats.append(entry)
         return stats
 
-    def format_results(self, results, output_format):
+    def format_results(self, results, output_format, fieldnames=None):
         """
         Format the parsed data in the selected format.
         @param results: A list of dictionaries, with each representing a contributor to the repository.
         @param output_format: The desired output format, e.g. 'csv', 'json', or 'markdown'
+        @param fieldnames: the columns of an empty CSV table; defaults to FIELDNAMES
         """
         self.verboseprint(f"Outputting results in {output_format.upper()} format:...")
         output = ""
@@ -288,7 +308,10 @@ class GitLogsParser:
             # always include the header, so even an empty result is a valid
             # CSV table; quote values that contain commas, quotes, or line breaks
             buffer = io.StringIO()
-            fieldnames = list(results[0].keys()) if results else FIELDNAMES
+            if results:
+                fieldnames = list(results[0].keys())
+            elif fieldnames is None:
+                fieldnames = FIELDNAMES
             writer = csv.DictWriter(buffer, fieldnames=fieldnames, lineterminator="\n")
             writer.writeheader()
             writer.writerows(results)
@@ -308,7 +331,11 @@ class GitLogsParser:
                 )  # heading separator lines
             for entry in results:
                 # each row of values, with any pipes escaped so they do not split cells
-                str_values = [str(val).replace("|", "\\|") for val in entry.values()]
+                # (an unavailable value, None, is left blank)
+                str_values = [
+                    ("" if val is None else str(val)).replace("|", "\\|")
+                    for val in entry.values()
+                ]
                 output += "| " + " | ".join(str_values) + " |\n"
 
         return output