{"id":13554029,"url":"https://github.com/mntnr/name-your-contributors","last_synced_at":"2026-04-10T22:01:53.081Z","repository":{"id":48945851,"uuid":"49676927","full_name":"mntnr/name-your-contributors","owner":"mntnr","description":"Name your GitHub contributors; get commits, issues, and comments","archived":false,"fork":false,"pushed_at":"2023-07-15T15:02:37.000Z","size":827,"stargazers_count":74,"open_issues_count":5,"forks_count":19,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-10T09:13:09.556Z","etag":null,"topics":["community","contribute","contributing","contributors","github","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mntnr.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"license","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-01-14T21:39:15.000Z","updated_at":"2025-01-09T21:15:58.000Z","dependencies_parsed_at":"2022-09-26T20:21:47.143Z","dependency_job_id":null,"html_url":"https://github.com/mntnr/name-your-contributors","commit_stats":{"total_commits":227,"total_committers":8,"mean_commits":28.375,"dds":0.5594713656387665,"last_synced_commit":"793d889d4948f951c3dc90f2e54edd4d6b749e14"},"previous_names":["richardlitt/name-your-contributors"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mntnr%2Fname-your-contributors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mntnr%2Fname-your-contributors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mntnr%2Fname-your-contributors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mntnr%2Fname-your-contributors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mntnr","download_url":"https://codeload.github.com/mntnr/name-your-contributors/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246947860,"owners_count":20859331,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["community","contribute","contributing","contributors","github","nodejs"],"created_at":"2024-08-01T12:02:38.259Z","updated_at":"2026-04-10T22:01:48.044Z","avatar_url":"https://github.com/mntnr.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","github"],"sub_categories":[],"readme":"# name-your-contributors\n\n[![npm version](https://badge.fury.io/js/name-your-contributors.svg)](https://badge.fury.io/js/name-your-contributors)\n[![Build and Deploy](https://github.com/mntnr/name-your-contributors/actions/workflows/nodejs.yml/badge.svg)](https://github.com/mntnr/name-your-contributors/actions/workflows/nodejs.yml)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\n\u003e Name your GitHub contributors; get commits, issues, and comments\n\n`name-your-contributors` gets all of the code reviewers, commenters, issue and PR creators from your organization or repo.\n\n## Table of Contents\n\n- [Background](#background)\n\t- [Contributors](#contributors)\n- [Install](#install)\n\t- [API Limits and setting up a GitHub Token](#api-limits-and-setting-up-a-github-token)\n\t\t- [Caveats](#caveats)\n- [Usage](#usage)\n\t- [From Code](#from-code)\n\t- [From the Command Line](#from-the-command-line)\n\t- [Config File](#config-file)\n\t- [Result formats](#result-formats)\n\t\t- [Default](#default)\n\t\t- [CSV](#csv)\n\t\t- [Full Contribution Tree](#full-contribution-tree)\n\t\t- [Condensed](#condensed)\n- [API](#api)\n\t- [orgContributors({orgName, token, before, after})](#orgcontributorsorgname-token-before-after)\n\t\t- [token](#token)\n\t\t- [org](#org)\n\t\t- [opts.after](#optsafter)\n\t\t- [opts.before](#optsbefore)\n\t- [repoContributors({user, repo, token, before, after})](#repocontributorsuser-repo-token-before-after)\n\t\t- [opts.user](#optsuser)\n\t\t- [opts.repo](#optsrepo)\n- [Development](#development)\n- [Contribute](#contribute)\n- [License](#license)\n\n## Background\n\nNYC started as a means of showing who has been active in a repository or an org over a certain period of time. Originally it was used to populate people for the [IPFS](https://github.com/ipfs/ipfs) newsletter - every week, I would run it again to show new contributions. GitHub doesn't count a lot of contributions as contributions, instead looking at commits alone. NYC looks at _all_ of your community, and logs who did what.\n\nIt spits out to a JSON object, because that's the most portable system for using it elsewhere with the formatting you need. It also uses GraphQL to cut down on the amount of queries, as it is pretty intensive otherwise.\n\n### Contributors\n\nThese people have helped make Name Your Contributors:\n\n - [@Berkmann18](https://github.com/Berkmann18)\n - [@RichardLitt](https://github.com/RichardLitt)\n - [@daviddias](https://github.com/daviddias)\n - [@dignifiedquire](https://github.com/dignifiedquire)\n - [@gr2m](https://github.com/gr2m)\n - [@greenkeeper](https://github.com/greenkeeper)\n - [@jbenet](https://github.com/jbenet)\n - [@jozefizso](https://github.com/jozefizso)\n - [@jywarren](https://github.com/jywarren)\n - [@kentcdodds](https://github.com/kentcdodds)\n - [@tgetgood](https://github.com/tgetgood)\n - [@waldyrious](https://github.com/waldyrious)\n\n\nUsing the [`jq`](https://github.com/stedolan/jq) JSON parsing library (you can use your own), this list was autogenerated like this:\n\n```sh\nnode src/cli.js -u mntnr -r name-your-contributors | jq '[ .[][].login | \" - [@ \\(.)](https://github.com/\\(.))\"]' | jq unique | jq -r .[]\n```\n\nWhich is a whole lot more useful than manually looking for contributors!\n\n## Install\n\n```sh\n$ npm install --save name-your-contributors\n```\n\n### API Limits and setting up a GitHub Token\n\nYou also need to get a GitHub Personal Access token, you can\n[create one here](https://github.com/settings/tokens/new?description=name-your-contributors\u0026scopes=read:org,user:email).\nIt needs to have the `read:org` and the `user:email` scopes in order to function\nproperly. Name the token something informative: `name-your-contributors` is a\ngood name.\n\nSet the token with the variable name `$GITHUB_TOKEN` before running the script:\n\n```sh\n$ export GITHUB_TOKEN=ab34e...\n```\n\nYou can also set the var automatically in every session by adding the above line\nto your `.bashrc` file in your home directory.\n\nThe cost of querying a repo is approximately the number of PRs + the number of\nissues + the number of comments with reactions (if querying reactions) + the\nnumber of commits / 100 (if querying commit log).\n\nSo in the simplest case it's simply the total number of issues and PRs in the\nrepos being queried.\n\n\n#### Caveats\n\nGitHub regulates API traffic by a credit system. The limits are quite high; it's\npermitted to query hundreds of repos per hour using the `repoContributors`\nfunction, but some organisations have many hundreds of repos, and a single call\nto `orgContributors` could potentially exhaust your entire hourly quota. The\nWikiMedia Foundation is a good example of an org with way too many repos for\nthis app to handle.\n\nUnfortunately filtering by contributions before or after a given date has no\neffect on quota use, since the data still needs to be queried before it can be\nfiltered.\n\nFor more details on rate limits, see\nhttps://developer.github.com/v4/guides/resource-limitations/.\n\n## Usage\n\n### From Code\n\n```js\nconst nyc = require('name-your-contributors')\n\nnyc.repoContributors({\n\ttoken: process.env.GITHUB_TOKEN,\n\tuser: 'mntnr',\n\trepo: 'name-your-contributors',\n\tbefore: new Date(),\n\tafter: new Date(0)\n}).then(\n\t//do something with the results\n)\n\nnyc.orgContributors({\n\ttoken: process.env.GITHUB_TOKEN,\n\torgName: 'ipfs',\n\tbefore: '2017-01-01',\n\tafter: '2016-01-01'\n}).then(...)\n```\n\n### From the Command Line\n\n```sh\n# Install the program\n$ npm install -g name-your-contributors\n\n# Make sure that a token is enabled - you can also save this in your .env\n$ export GITHUB_TOKEN={your-token}\n\n# Get all contributors to mntnr/name-your-contributors. Log to stdout.\n$ name-your-contributors -u mntnr -r name-your-contributors\n\n# Or, get all contributors to an org after a certain date, in a file\n$ name-your-contributors -o ipfs -a 2017-01-01 \u003e ipfs-contrib.json\n\n# Use a config instead of specifying using CLI arguments - easier for repetitive use\n$ name-your-contributors --config config.json \u003e combined-out.json\n\n# Print the help docs!\n$ name-your-contributors --help\n\n  Name your GitHub contributors; get commits, issues, and comments\n\n  Usage\n    $ name-your-contributors \u003cinput\u003e [opts]\n\n  Options\n    -t, --token   - GitHub auth token to use\n    -a, --after   - Get contributions after date\n    -b, --before  - Get contributions before data\n\n    -o, --org     - Search all repos within this organisation\n    -r, --repo    - Repository to search\n    -u, --user    - User to which repository belongs\n    -c, --config  - Operate from config file. In this mode only token, verbose, and\n                    debug flags apply.\n\n    --full        - Returns the full tree of contributions rather than the default\n                    synopsis.\n    --csv         - Output data in CSV format\n\n    --commits     - Get commit authors and comments from GitHub\n    --local-dir   - If specified, this script will look for repos being queried in\n                    the provided dir and read the commit log from them directly.\n    --reactions   - Query reactions of comments as well.\n\n    --wipe-cache  - Wipe local cache before starting query.\n\n    -v, --verbose - Enable verbose logging\n    --debug       - Enable extremely verbose logging\n    --dry-run     - Check the cost of the query without executing it.\n\n  Authentication\n\t\tThis script looks for an auth token in the env var GITHUB_TOKEN. It needs\n\t\tto have the read:org and the user:email scopes in order to function\n\t\tproperly. Make sure this var is set to a valid GitHub oauth token. To\n\t\tcreate one see:\n\t\thttps://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/\n  Examples\n    $ name-your-contributors -r ipfs -u ipfs --after=2016-01-15T00:20:24Z --before=2016-01-20T00:20:24Z\n\n    $ name-your-contributors -o ipfs -a 2017-01-01 \u003e ipfs-contrib-2017.json\n\n    $ name-your-contributors --config config.json \u003e combined-out.json\n```\n\n### Config File\n\nFor batching convenience, Name Your Contributors takes a config file which\nspecifies a token, a list of repos, and a list of orgs to grab. The\n`config.json.example` is an outline of this file format:\n\n```json\n{\n  \"token\": \"123435abcdf\",\n  \"repos\": [{\n\t\"login\": \"mntnr\",\n\t\"repo\": \"name-your-contributors\",\n\t\"before\": \"2017-11-30\",\n\t\"after\": \"2017-06-01\"\n  }, {\n\t\"login\": \"mntnr\",\n\t\"repo\": \"whodidwhat\"\n  }],\n  \"orgs\": [{\n\t\"login\": \"adventure-js\",\n\t\"after\": \"2017-07-01\"\n  }]\n}\n```\n\nA token passed in the config file will override any token present in the\nenvironment.\n\nThe output when passed a config file is a mirror of the config file with the\ntoken removed and a `contributions` key added to each object, like so:\n\n```json\n{\n  \"repos\": [{\n\t\"login\": \"mntnr\",\n\t\"repo\": \"name-your-contributors\",\n\t\"before\": \"2017-11-30\",\n\t\"after\": \"2017-06-01\",\n\t\"contributions\" : {\n\t  \"commitAuthors\": [...],\n\t  \"commitCommentators\": [...],\n\t  ,,,\n\t},\n\t...\n  }],\n  \"orgs\": [...]\n}\n```\n\nThe output will be in the format:\n\n```sh\n$ name-your-contributors -u mntnr -r name-your-contributors --after 2017-11-10\n\n{\n  \"commitAuthors\": [],\n  \"commitCommentators\": [],\n  \"prCreators\": [],\n  \"prCommentators\": [\n\t{\n\t  \"login\": \"RichardLitt\",\n\t  \"name\": \"Richard Littauer\",\n\t  \"url\": \"https://github.com/RichardLitt\",\n\t  \"count\": 3\n\t},\n\t{\n\t  \"login\": \"tgetgood\",\n\t  \"name\": \"Thomas Getgood\",\n\t  \"url\": \"https://github.com/tgetgood\",\n\t  \"count\": 2\n\t}\n  ],\n  \"issueCreators\": [\n\t{\n\t  \"login\": \"RichardLitt\",\n\t  \"name\": \"Richard Littauer\",\n\t  \"url\": \"https://github.com/RichardLitt\",\n\t  \"count\": 1,\n\t\t\"titles\": [\n\t\t\t\"Add example output to the README\",\n\t\t\t\"Get email for users\"\n\t\t]\n\t}\n  ],\n  \"issueCommentators\": [\n\t{\n\t  \"login\": \"tgetgood\",\n\t  \"name\": \"Thomas Getgood\",\n\t  \"url\": \"https://github.com/tgetgood\",\n\t  \"count\": 1\n\t},\n\t{\n\t  \"login\": \"RichardLitt\",\n\t  \"name\": \"Richard Littauer\",\n\t  \"url\": \"https://github.com/RichardLitt\",\n\t  \"count\": 1\n\t}\n  ],\n  \"reactors\": [\n\t{\n\t  \"login\": \"patcon\",\n\t  \"name\": \"Patrick Connolly\",\n\t  \"url\": \"https://github.com/patcon\",\n\t  \"count\": 1\n\t}\n  ],\n  \"reviewers\": []\n}\n```\n\n### Result formats\n\nName Your Contributors offers 4 distinct result formats intended for different\nconsumers.\n\n#### Default\n\nThe default result format is an aggregate synopsis of all contributions in the\ngiven time window. This is the format in the examples above.\n\n#### CSV\n\nWith the `--csv` flag provided at the command line, nyc will return the default\ninfo in CSV format rather than JSON.\n\n#### Full Contribution Tree\n\nIf the `--full` flag is passed at the command line, then nyc will return the\nfull tree of org-\u003erepo-\u003epr-\u003ecomment-\u003ereaction-\u003eauthor for all interactions in\nthe given time window. This format is quite verbose, but invaluable if you want\nto know not only who contributed, but the details of every contribution made.\n\nFor example,\n```sh\n$ name-your-contributors -r name-your-contributors -u mntnr -b 2017-12-10 -a 2017-11-10 --full\n```\nwill return (abbreviated):\n```sh\n{\n  \"repository\": {\n\t\"homepageUrl\": \"\",\n\t\"name\": \"name-your-contributors\",\n\t\"owner\": {\n\t  \"login\": \"mntnr\"\n\t},\n\t\"pullRequests\": [\n\t  {\n\t\t\"title\": \"Cli updates\",\n\t\t\"number\": 43,\n\t\t\"state\": \"MERGED\",\n\t\t\"author\": {\n\t\t  \"login\": \"tgetgood\",\n\t\t  \"name\": \"Thomas Getgood\",\n\t\t  \"url\": \"https://github.com/tgetgood\"\n\t\t},\n\t\t\"createdAt\": \"2017-10-26T19:48:39Z\",\n\t\t\"comments\": [\n\t\t  {\n\t\t\t\"author\": {\n\t\t\t  \"login\": \"RichardLitt\",\n\t\t\t  \"name\": \"Richard Littauer\",\n\t\t\t  \"url\": \"https://github.com/RichardLitt\"\n\t\t\t},\n\t\t\t\"createdAt\": \"2017-11-20T16:35:31Z\"\n\t\t  },\n\t\t  {\n\t\t\t\"author\": {\n\t\t\t  \"login\": \"tgetgood\",\n\t\t\t  \"name\": \"Thomas Getgood\",\n\t\t\t  \"url\": \"https://github.com/tgetgood\"\n\t\t\t},\n\t\t\t\"createdAt\": \"2017-11-21T21:05:15Z\"\n\t\t  },\n\t\t  ...\n\t\t],\n\t\t\"reviews\": []\n\t  },\n\t  ...\n\t]\n  }\n}\n```\n\nNotice that the pull request above was created before the date passed to\nbefore. It is still included because comments made within it were created in the\ndesired timeframe. If there had been no such comments, the PR would not be\nincluded.\n\n#### Condensed\n\nFor an even more condensed output format which also allows filtering on given\nusers, see the postprocessing script\n[Who Did What](https://github.com/mntnr/whodidwhat).\n\n## API\n\n### orgContributors({orgName, token, before, after})\n\n#### token\n\nType: `string`\n\nGithub auth token\n\n#### org\n\nType: `string`\n\nThe organization to traverse. If no organization is provided, the script\nwill find the username and repo for the local git repository and use that.\n\n#### opts.after\n\nType: `string`\nDefault value: `new Date(0)`\n\nThe ISO timestamp to get contributors after.\n\nAny string that will be accepted by `new Date(\"...\")` will work here as\nexpected.\n\n#### opts.before\n\nType: `string`\nDefault value: `new Date()`\n\nGet contributors from before this ISO timestamp.\n\n### repoContributors({user, repo, token, before, after})\n\n#### opts.user\n\nType: `string`\n\nGithub user name to whom the repo belongs.\n\n#### opts.repo\n\nType: `string`\n\nOnly traverse the given repository.\n\n## Development\n\nThere are several extra flags that are useful for development and diagnosing\nissues:\n\n`-v, --verbose` prints out each query that is sent to the api along with its\ncost and the quota remaining after it is run.\n\n`--debug` prints out each query sent to the server and the raw response. This is\nextremely verbose.\n\n`--dry-run` prints the cost of the first query that would have been run *without\nrunning it*. Note that since the query isn't executed, follow up queries aren't\npossible. when used with the `-c, --config` option, dry runs the first query for\neach entry of the config file.\n\n## Contribute\n\nName Your Contributors is an open source project - we'd love you to contribute! Check out the [Contributing document](CONTRIBUTING.md), and abide by the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## License\n\n[MIT](license) © 2018 [Richard Littauer](http://burntfen.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmntnr%2Fname-your-contributors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmntnr%2Fname-your-contributors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmntnr%2Fname-your-contributors/lists"}