{"id":26093158,"url":"https://github.com/gavv/md-authors","last_synced_at":"2025-07-24T02:38:32.311Z","repository":{"id":281457137,"uuid":"943298464","full_name":"gavv/md-authors","owner":"gavv","description":"Command-line tool for generating contributors list in markdown file.","archived":false,"fork":false,"pushed_at":"2025-05-20T05:52:22.000Z","size":31,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-20T06:33:37.291Z","etag":null,"topics":["command-line-tool","documentation","markdown","readme"],"latest_commit_sha":null,"homepage":"","language":"Go","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/gavv.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"buy_me_a_coffee":"gavv","liberapay":"gavv"}},"created_at":"2025-03-05T13:38:19.000Z","updated_at":"2025-05-20T05:52:16.000Z","dependencies_parsed_at":"2025-05-20T06:38:39.822Z","dependency_job_id":null,"html_url":"https://github.com/gavv/md-authors","commit_stats":null,"previous_names":["gavv/md-authors"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/gavv/md-authors","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gavv%2Fmd-authors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gavv%2Fmd-authors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gavv%2Fmd-authors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gavv%2Fmd-authors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gavv","download_url":"https://codeload.github.com/gavv/md-authors/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gavv%2Fmd-authors/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266785556,"owners_count":23983830,"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","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["command-line-tool","documentation","markdown","readme"],"created_at":"2025-03-09T11:55:42.250Z","updated_at":"2025-07-24T02:38:32.295Z","avatar_url":"https://github.com/gavv.png","language":"Go","funding_links":["https://buymeacoffee.com/gavv","https://liberapay.com/gavv"],"categories":[],"sub_categories":[],"readme":"# md-authors [![Build](https://github.com/gavv/md-authors/workflows/build/badge.svg)](https://github.com/gavv/md-authors/actions)\n\n\u003c!-- toc --\u003e\n\n- [About](#about)\n- [Installation](#installation)\n  - [Install Go](#install-go)\n  - [Install md-authors](#install-md-authors)\n  - [Install gh](#install-gh)\n- [Command-line options](#command-line-options)\n- [Usage](#usage)\n  - [Basic usage](#basic-usage)\n  - [Append mode](#append-mode)\n  - [Pipe mode](#pipe-mode)\n  - [Format spec](#format-spec)\n  - [Sort order](#sort-order)\n  - [Git and GitHub](#git-and-github)\n  - [Troubleshooting](#troubleshooting)\n- [Caveats](#caveats)\n- [History](#history)\n- [Authors](#authors)\n- [License](#license)\n\n\u003c!-- tocstop --\u003e\n\n## About\n\n`md-authors` is a command-line tool that prints list of contributors from git and/or github to markdown file or stdout.\n\nFeatures:\n\n- Collect author list from git and optionally populate with additional information from github (like login, display name, contact email, etc.).\n\n- Insert/update authors list in markdown file surrounded by `\u003c!-- authors --\u003e` / `\u003c!-- endauthors --\u003e` magic comments.\n\n- Alternatively, print authors list to stdout in arbitrary format.\n\n- Specify custom format string to define which fields to print and how.\n\n- Append mode, when only new authors are printed. Useful when you want to edit previously generated list by hand and keep your edits intact.\n\n## Installation\n\n### Install Go\n\nFirst, install Go \u003e= 1.21.\n\nOn Ubuntu:\n\n```\nsudo apt install golang-go\n```\n\nOn macOS:\n\n```\nbrew install go\n```\n\n### Install md-authors\n\nThen run this command, which will download, build, and install `md-authors` executable into `$GOPATH/bin` (it's `~/go/bin` if `GOPATH` environment variable is not set):\n\n```\ngo install -v github.com/gavv/md-authors@latest\n```\n\nAlternatively, you can install from sources:\n\n```\ngit clone https://github.com/gavv/md-authors.git\ncd md-authors\ngo build\n./md-authors --help\n```\n\n### Install gh\n\nIt is also recommended to install official [`gh` tool](https://cli.github.com/), add it to your PATH, and run `gh auth login` to authenticate on GitHub.\n\nWhen available, `gh` is automatically used to make authenticated requests to GitHub, which have significantly higher rate limits compared to unauthenticated.\n\n## Command-line options\n\n```\nUsage: md-authors [OPTIONS] [FILES]...\n\nOPTIONS:\n  -f, --format string    format spec (default \"modern\")\n  -s, --sort string      sort order: date, name (default \"date\")\n  -a, --append           append to list instead of replacing\n  -P, --pipe             read from stdin (if --append) and write to stdout\n  -x, --ignore string    comma-separated list of emails, names, and logins to ignore\n  -p, --project string   github project\n  -N, --no-project       don't query github project\n  -r, --refresh          refresh cached data\n  -d, --debug            enable debug logging\n  -h, --help             print this message and exit\n```\n\n## Usage\n\n### Basic usage\n\nExample `AUTHORS.md` file:\n\n```\n$ cat AUTHORS.md\n\n# MyProject\n\nList of MyProject authors, ordered by first contribution:\n\n\u003c!-- authors --\u003e\n\n\u003c!-- endauthors --\u003e\n```\n\nFile name doesn't matter, but \"AUTHORS\" is a widely used one. All text besides `\u003c!-- authors --\u003e` / `\u003c!-- endauthors --\u003e` block is arbitrary.\n\nRun tool:\n\n```\n$ md-authors AUTHORS.md\nmd-authors: new: Arthur Philip Dent \u003cdent@yahoo.com\u003e sandwich-maker\nmd-authors: new: Ford Prefect \u003cford@betelgeuse7.sid\u003e Ix\nmd-authors: added 2 author(s)\n```\n\nUpdated `AUTHORS.md` file:\n\n```\n$ cat AUTHORS.md\n\n# MyProject\n\nList of MyProject authors, ordered by first contribution:\n\n\u003c!-- authors --\u003e\n\n1. Arthur Philip Dent `sandwich-maker`\n2. Ford Prefect `Ix`\n\n\u003c!-- endauthors --\u003e\n```\n\n### Append mode\n\nBy default, contents of the authors block is replaced.\n\nIf `--append` is specified, the old contents of markdown block is kept unaffected, and only new authors missing in old contents are appended to the end of the block. It allows you to edit generated author list and keep your edits intact.\n\nWhen used with `--pipe` (see below), old contents is read from stdin, and only new authors are printed to stdout.\n\nIn both cases old content of the block is used to detect new authors by matching names, emails, and github logins and profile urls in the content text.\n\nThe matching tries to be smart (a bit): if some unique field like email or profile url or two-word name is present in old content, it is considered a hit, but if only less unique fields are present like one-word name or nickname, then it requires at least two matches to consider it a hit.\n\nMatching is case-insensitive. Unicode letters are converted to ASCII before comparison, so that letters like \"é\" and \"e\" will be treated as equal.\n\n### Pipe mode\n\nIf `--pipe` is specified, the author list is written to stdout.\n\nExample:\n\n```\n$ md-authors --pipe --format \"{email};{login};{name}\"\ndent@yahoo.com;sandwich-maker;Arthur Philip Dent\nford@betelgeuse7.sid;Ix;Ford Prefect\n```\n\nThis example uses `--format` option, described in the next section.\n\nWhen `--pipe` is used together with `--append`, the tool reads old content from stdin and uses it to detect and print only new authors.\n\n### Format spec\n\n`--format` option defines output format of author entries.\n\nIt can be one of the predefined specs:\n\n- `--format=modern` (default)\n\n    Produces lines like:\n\n    ```\n    1. Arthur Philip Dent `sandwich-maker`\n    2. Ford Prefect `Ix`\n    ```\n\n- `--format=classic`\n\n    Produces lines like:\n\n    ```\n    - Arthur Philip Dent `sandwich-maker` (\u003cdent@yahoo.com\u003e)\n    - Ford Prefect `Ix` (\u003cford@betelgeuse7.sid\u003e)\n    ```\n\nAlternatively, `--format` can define custom spec. It should be a string that can mix literal characters, *escape sequences*, and *format fields*.\n\nFor example, `--format=modern` spec is equivalent to:\n\n```\n--format=\"{index}. {name} `{login?}`\\n\"\n```\n\nand `--format=classic` spec is equivalent to:\n\n```\n--format=\"- {name} `{login?}` (\u003c{email|profile?}\u003e)\\n\"\n```\n\nHere, `{...}` and `\\n` have special meaning (they're format fields and and escape sequences, accordingly) and are substituted with something. Everything else is interpreted as a literal character, and is added as-is, including `-`, backtick, `()`, and `\u003c\u003e`.\n\n**Escape sequence** is a backslash followed by any character, like `\\n` or `\\{`. It supports common special characters (`\\n` for newline, `\\t` for tab, etc). You can also use it to escape `{` or `\\`.\n\n**Format fields** have the following syntax:\n\n- `{foo}` - replaced with value of field \"foo\"\n- `{foo?}` - same, but if \"foo\" is empty, removes adjustent non-whitespace literal characters\n- `{foo|bar}` - same, but if \"foo\" field is empty, uses field \"bar\"\n- `{foo|bar?}` - same, but if \"foo\" and \"bar\" fields are both empty, removes adjustent non-whitespace literal characters\n\nList of available fields:\n\n| field       | description                                           |\n|-------------|-------------------------------------------------------|\n| `{index}`   | entry number, starts from 1 and increments each entry |\n| `{date}`    | date of first contribution (`YYYY-MM-DD`)             |\n| `{name}`    | full name                                             |\n| `{email}`   | email address                                         |\n| `{login}`   | github login                                          |\n| `{profile}` | github profile url                                    |\n\nSome fields may be empty/missing if this information is not available on GitHub or if GitHub support is disabled via `--no-project` option.\n\nExample of `|` syntax usage is to print email if it's available or profile link otherwise:\n\n```\n{email|profile}\n```\n\nThe `?` syntax can be used to remove formatting adjustent to the field, e.g. in:\n\n```\n`{login?}`\n```\n\nwhen `login` field is empty, it is removed together with surrounding backticks, and in:\n\n```\n(\u003c{email|profile?}\u003e)\n```\n\nwhen both `email` and `profile` are empty, they are removed together with surrounding `\u003c\u003e` and `()`.\n\n### Sort order\n\n`--sort` option define in which order authors appear:\n\n- `--sort=date` (default) - by first contribution date, oldest first\n- `--sort=name` - by name, alphabetically\n\nNote that in `--append` mode, sort order affects only newly added entries, so using `--append` together with `--sort=name` is probably not what you want.\n\n### GitHub project\n\n`--project` option may be used to explicitly specify github repository name in form `\u003cowner\u003e/\u003crepo\u003e`. If not specified, it is automatically detected from `git remote -v`.\n\n`--no-project` option disable github support. When specified, only local git history is used.\n\nBackends other than git and github are not supported so far, but pull requests are welcome!\n\n### Troubleshooting\n\nBackend queries are cached in `~/.cache/mdauthors.json`, to make subsequent invocations fast. You can force re-fetching of queried fields using `--refresh` option. Or you can delete this file to clean the cache entirely.\n\nUse `--debug` option to enable verbose logging to stderr. It may be handy to use it together with `--pipe` option.\n\n## Caveats\n\nMatching of authors is not 100% reliable. For example, if two entries have the same full name with 2+ space-separated words, they are considered as the same author. Both false positives and false negatives are possible occasionally, though they're rare in practice. With `--append` mode, it is safe to edit output by hand to fix inconsistencies.\n\nWhen using `--sort=name` together with `--append`, only newly added authors are sorted, because in append mode the tool doesn't touch existing content of the block.\n\nWhen using `{index}` field together with `--append` mode, it is assumed that one entry corresponds to one non-whitespace line. It will work incorrectly if that's not true (i.e. if you use custom `--format` option with multiple newlines).\n\nIf you have slow Internet, be patient. You can specify `--debug` if you're bored.\n\n## History\n\nChangelog file can be found here: [changelog](CHANGES.md).\n\n## Authors\n\nSee [here](AUTHORS.md).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgavv%2Fmd-authors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgavv%2Fmd-authors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgavv%2Fmd-authors/lists"}