{"id":43223296,"url":"https://github.com/gnames/gndiff","last_synced_at":"2026-02-01T09:16:01.405Z","repository":{"id":44530930,"uuid":"436396987","full_name":"gnames/gndiff","owner":"gnames","description":"GNdiff compares scientific names from two files","archived":false,"fork":false,"pushed_at":"2023-11-06T23:22:26.000Z","size":16044,"stargazers_count":4,"open_issues_count":8,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-06-20T07:57:59.199Z","etag":null,"topics":[],"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/gnames.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-08T21:28:32.000Z","updated_at":"2023-05-16T13:17:32.000Z","dependencies_parsed_at":"2023-10-12T00:20:12.571Z","dependency_job_id":"753939f0-7be9-4ef4-bab6-9d81fc268349","html_url":"https://github.com/gnames/gndiff","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/gnames/gndiff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnames%2Fgndiff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnames%2Fgndiff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnames%2Fgndiff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnames%2Fgndiff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gnames","download_url":"https://codeload.github.com/gnames/gndiff/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnames%2Fgndiff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28974540,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T08:16:14.655Z","status":"ssl_error","status_checked_at":"2026-02-01T08:06:51.373Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-02-01T09:16:00.269Z","updated_at":"2026-02-01T09:16:01.400Z","avatar_url":"https://github.com/gnames.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `GNdiff` app takes two files with scientific names and compares them\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [Introduction](#introduction)\n* [GNdiff Installation](#gndiff-installation)\n  * [Using Homebrew on Mac OS X, Linux, and Linux on Windows (WSL2)](#using-homebrew-on-mac-os-x-linux-and-linux-on-windows-wsl2)\n  * [Linux and Mac without Homebrew](#linux-and-mac-without-homebrew)\n  * [MS Windows](#ms-windows)\n  * [Compile from source](#compile-from-source)\n* [Usage](#usage)\n  * [Compare Files](#compare-files)\n  * [Compare using test files](#compare-using-test-files)\n  * [Options and flags](#options-and-flags)\n    * [help](#help)\n    * [version](#version)\n    * [format](#format)\n    * [quiet](#quiet)\n* [Family names as a disambiguation tool](#family-names-as-a-disambiguation-tool)\n  * [The same nomenclatural code homonyms (senior, junior homonyms)](#the-same-nomenclatural-code-homonyms-senior-junior-homonyms)\n  * [Homonyms from different nomenclatural codes (hemihomonyms)](#homonyms-from-different-nomenclatural-codes-hemihomonyms)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## Introduction\n\nIt is often useful to compare one checklist to another. This project uses\npretty much the same algorithms as [GNverifier], but does not require an\nexternal database and can be used offline.\n\n[GNdiff] is a complementary tool to [GNverifier]. It is made to compare a\nchecklist with checklists that are not in [GNverifier database][GNverifier\ndata-sources]. If you need to compare a list of names that are [already in\nGNverifier][GNverifier data-sources], either use [GNverifier web app] or\n[install][GNverifier Install] it locally and run:\n\n```bash\ngnvrifier names.txt -o -s 12,1\n```\n\nwhere `-s` option provides `id`/`ids` of selected [GNverifier data-sources],\nand `-o` flag (`--only-preferred`) limits results to data-sources set by `-s`\noption.\n\nIf both checklists of scientific names are local, use [GNdiff].\n\n## `GNdiff` Installation\n\n### Using Homebrew on Mac OS X, Linux, and Linux on Windows ([WSL2][WSL install])\n\n[Homebrew] is a popular package manager for Open Source software originally\ndeveloped for Mac OS X. Now it is also available on Linux, and can easily\nbe used on MS Windows 10 or 11, if Windows Subsystem for Linux (WSL) is\n[installed][WSL install].\n\nNote that [Homebrew] requires some other programs to be installed, like Curl,\nGit, a compiler (GCC compiler on Linux, Xcode on Mac). If it is too much,\ngo to the `Linux and Mac without Homebrew` section.\n\nTo use `GNdiff` with Homebrew:\n\n1. Install [Homebrew]\n\n2. Open terminal and run the following commands:\n\n```bash\nbrew tap gnames/gn\nbrew install gndiff\n```\n\n### Linux and Mac without Homebrew\n\nDownload the latest [GNdiff release], untar, and install binary somewhere\nin your path.\n\n```bash\ntar xvf gndiff-linux-0.1.1.tar.gz\n# or tar xvf gndiff-mac-0.1.1.tar.gz\nsudo mv gndiff /usr/local/bin\n```\n\n### MS Windows\n\nDownload the latest [GNdiff release], unzip.\n\nOne possible way would be to create a default folder for executables and place\n``GNdiff`` there.\n\nUse ``Windows+R`` keys\ncombination and type \"``cmd``\". In the appeared terminal window type:\n\n```cmd\nmkdir C:\\Users\\your_username\\bin\ncopy path_to\\gndiff.exe C:\\Users\\your_username\\bin\n```\n\n[Add ``C:\\Users\\your_username\\bin`` directory to your ``PATH``][winpath]\nenvironment variable.\n\nAnother, simpler way, would be to use ``cd C:\\Users\\your_username\\bin`` command\nin ``cmd`` terminal window. The ``GNdiff`` program then will be automatically\nfound by Windows operating system when you run its commands from that\ndirectory.\n\n### Compile from source\n\nInstall Go according to [installation instructions][go-install] and run:\n\n```bash\ngo install github.com/gnames/gndiff/gndiff@latest\n```\n\n## Usage\n\n### Compare Files\n\nPrepare two files with names. There are 3 possible file formats:\n\n* A simple list of scientific names, one name per line.\n* Comma-separated or Tab-separated (CSV) file with a `ScientificName`\n  field.\n* Tab-separated (TCV) file with a `ScientificName` field.\n\nFor both CSV and TSV files the fields `TaxonID` and `Family` are also ingested\nif given, any capitalization of either of the fields names is accepted.\n\nThe `Family` field indicates a family a particular species are assigned to\naccording to the dataset. Normally this field is not needed, but in case of\ntricky homonyms it helps to resolve taxa from each other.\n\nRun command:\n\n```bash\ngndiff query.csv reference.csv\n```\n\nThe first of the two files should contain names that need to be matched.\nThe second file should contain reference names.\n\nAny combination of these 3 formats would work:\n\n```bash\ngndiff file.csv names.txt\ngndiff file.tsv file.csv\ngndiff name.txt file.tsv\n# etc.\n```\n\n### Compare using test files\n\nTo see how it works you can use tests files from the GNdiff project for example\n[ebird.csv] and [ioc-bird.csv]. These files contain avian names from [eBird]\nand [eBird] and [IOC Bird] checklists correspondingly.\nOpen each link and use `Ctrl-S` on Windows/Linux or `⌘-S` on Mac to save\nthese files on your computer. You can then run:\n\n```bash\ngndiff path/to/ebird.csv path/to/ioc-bird.csv\n# or\ngndiff path/to/ioc-bird.csv path/to/ebird.csv\n```\n\n### Options and flags\n\nAccording to POSIX standard flags and options can be given either before or\nafter file-paths arguments.\n\n#### help\n\n```bash\ngndiff -h\n# or\ngndiff --help\n# or\ngndiff\n```\n\n#### version\n\n```bash\ngndiff -V\n# or\ngndiff --version\n```\n\n#### format\n\nSets the format of the comparison result and can take the following values:\n\n* `csv`: Comma-separated format\n* `tsv`: Tab-separated format\n* `compact`: JSON as one line\n* `pretty`: JSON in a human-readable format with indentations and lines separation.\n\nThe default format is CSV.\n\n```bash\ngndiff query.txt ref.txt -f pretty\n# or\ngndiff query.txt ref.txt --format=pretty\n```\n\n#### port (integer)\n\nWhen `port` is set, `GNdiff` works as a web server with its RESTful API\nexposed at the given port.\n\n```bash\ngndiff -p 8080\n# or\ngndiff --port 8080\n```\n\n#### quiet\n\nThis flag supresses warnings log, showing only the matching results.\n\n```bash\ngndiff query.txt ref.txt -q\n# or\ngndiff query.txt ref.txt --quiet\n```\n\nPlease note, that matching result uses `STDOUT`, while log uses `STDERR`,\nso a similar result can be achieved by redirecting `STDERR` to `/dev/null`\n\n```bash\ngndiff query.txt ref.txt 2\u003e /dev/null\n```\n\n## Family names as a disambiguation tool\n\nFamily sometimes help to distinquish homonyms in names lists. For example,\nthere are homonyms within one nomenclatural code, and homonyms in between\ntwo nomenclatural codes.\n\n### The same nomenclatural code homonyms (senior, junior homonyms)\n\nFor example, in zoology a genus name `Echidna` has 3 homonyms:\n\n1. Moray eel\n\n    Family `Muraenidae` -\u003e Genus `Echidna J. R. Forster`\n\n2. Egg-laying mammal Echidna\n\n    Family `Tachyglossidae` -\u003e `Echidna Cuvier, 1797` (junior homonym)\n\n    Currently genus `Tachyglossus Illiger, 1811`\n\n3. Snake\n\n    Family `Viperidae` -\u003e `Echidna Merrem, 1820` (junior homonym)\n\n    Currently genus `Bitis Gray, 1842`\n\nSuch homonyms are not allowed within the same code and eventually they\nget corrected. However historical records still contain them and\nhave to be disambiguated.\n\n### Homonyms from different nomenclatural codes (hemihomonyms)\n\nThere are no rules how to deal with homonyms that are treated by different (for\nexample Botanical and Zoological) nomenclatural codes.\n\n1. Sea Snail (Zoological Nomenclatural Code)\n\n    Family `Ficidae` -\u003e `Ficus variegata Röding, 1798`\n\n2. Red fig (Botanical Nomenclatural Code)\n\n    Family `Moraceae` -\u003e `Ficus variegata Blume`\n\n[GNdiff release]: https://github.com/gnames/gndiff/releases/latest\n[GNdiff]: https://github.com/gnames/gndiff\n[GNverifier data-sources]: https://verifier.globalnames.org/data_sources\n[GNverifier install]: https://github.com/gnames/gnverifier#installation\n[GNverifier]: https://github.com/gnames/gnverifier\n[GNverifier web app]: https://verifier.globalnames.org\n[Homebrew]: https://brew.sh/\n[WSL install]: https://docs.microsoft.com/en-us/windows/wsl/install-win10\n[go-install]: https://golang.org/doc/install\n[winpath]: https://www.computerhope.com/issues/ch000549.htm\n[ebird.csv]: https://raw.githubusercontent.com/gnames/gndiff/master/testdata/ebird.csv\n[ioc-bird.csv]: https://raw.githubusercontent.com/gnames/gndiff/master/testdata/ioc-bird.csv\n[eBird]: https://www.worldbirdnames.org/\n[IOC Bird]: https://www.worldbirdnames.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgnames%2Fgndiff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgnames%2Fgndiff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgnames%2Fgndiff/lists"}