GitHub Contributors List

Builds a contributor list based on information available on GitHub. It reads the information of pull requests including the Co-authored-by: notes in commit messages.

GitHub's API does NOT include users listed as "Co-authored-by:". Thefore, the commit messages need to parsed "manually".

It is a rewrite of github-contributors-list to support Co-authored-by:.

Example

See https://blog.jabref.org/2024/04/03/JabRef5-13/#special-thanks for real-world usage.

How to use

1. Install jbang. E.g.,
   • Linux/macOS: curl -Ls https://sh.jbang.dev | bash -s - app setup or
   • Windows (Powershell): iex "& { $(iwr -useb https://ps.jbang.dev) } app setup"
2. Add oauth=... to ~/.github with ... being your GitHub personal access token. See GitHub API for Java for details.
3. cd to the repository you want to analyze.
4. jbang gcl@koppor/github-contributors-list

Usage: jbang gcl@koppor/github-contributors-list [-lhV] [--startrevision=<startCommitRevStr>]
           [--endrevision=<endCommitRevStr>] [--repository=<ownerRepository>]
           [--cols=<cols>] [--filter=<ignoredUsers>]...
           [--filter-emails=<ignoredEmails>]... [-m=<String=String>]...
           [<repositoryPath>]
      [<repositoryPath>]     The path to the git repository to analyse.
      --cols=<cols>          Number of columns
      --endrevision=<endCommitRevStr>
                             The last revision to check (tag or commit id).
                               Included.
      --filter=<ignoredUsers>

      --filter-emails=<ignoredEmails>

  -h, --help                 Show this help message and exit.
  -l, --[no-]github-lookup   Should calls be made to GitHub's API for user
                               information
  -m, --login-mapping=<String=String>
                             Mapping of GitHub logins to names. Format:
                               name=login
      --repository=<ownerRepository>
                             The GitHub repository in the form
                               owner/repostiory. E.g., JabRef/jabref
      --startrevision=<startCommitRevStr>
                             The first revision to check (tag or commit id).
                               Excluded.
  -V, --version              Print version information and exit.

Example:

Usage: jbang gcl@koppor/github-contributors-list --repository JabRef/jabref c:\git-repositories\jabref --startrevision=v5.13 --endrevision=v5.15

At the end, non-found committers are listed. The format is <used name> <PR link> <commit link>. Example:

Anish.Pal https://github.com/JabRef/jabref/pull/10829 https://github.com/JabRef/jabref/pull/10829/commits/d2d84923df2c6c7d59559da8d583ae17dc803c3d

With that information, one can create a mapping from the committer name to the GitHub username. In this case: Anish.Pal=pal-anish

The tool is implemented as single pass over the commits of the repository. It uses a cache to store the information of contributors. Thus, repeated runs could update contributor information. For instance, if a user first appears as "Co-authored-by:" and later as a pull request author, the username could be determined better.

In case of issues, try to delete gcl.mv to start with a fresh cache.

FAQ

⚠ In case contributors are not ignored, please delete gcl.mv and try again. ⚠

Implementation details

• gcl.mv is an MVStore caching contributor information returned by GitHub's API.
• Dependencies of gcl.java cannot be updated automatically. dependabot-core#9406.
• Use writer.level = TRACE in tinylog.properties for debugging.

Alternatives

• Manually curate all contributors using All Contributors
• Use github-contributors-list and accept that Co-authored-by: is ignored.