{"id":17762099,"url":"https://github.com/thepushkarp/nalcos","last_synced_at":"2025-07-29T05:03:56.484Z","repository":{"id":46716871,"uuid":"405401022","full_name":"thepushkarp/nalcos","owner":"thepushkarp","description":"Search Git commits in natural language","archived":false,"fork":false,"pushed_at":"2025-07-08T19:02:16.000Z","size":422,"stargazers_count":55,"open_issues_count":6,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-15T00:37:04.160Z","etag":null,"topics":["commit-search","commits","hacktoberfest","huggingface","information-retrieval","natural-language","nlp","python","sentence-transformers"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/nalcos/","language":"Python","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/thepushkarp.png","metadata":{"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"thepushkarp","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":"https://www.buymeacoffee.com/thepushkarp"},"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2021-09-11T14:30:58.000Z","updated_at":"2025-07-08T19:02:14.000Z","dependencies_parsed_at":"2024-03-20T16:58:07.023Z","dependency_job_id":"55070af9-9097-4a15-abac-ca28214b8ddb","html_url":"https://github.com/thepushkarp/nalcos","commit_stats":{"total_commits":40,"total_committers":2,"mean_commits":20.0,"dds":"0.050000000000000044","last_synced_commit":"2e410f45bad8a33cffa6b9ea0bf145006c580894"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/thepushkarp/nalcos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thepushkarp%2Fnalcos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thepushkarp%2Fnalcos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thepushkarp%2Fnalcos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thepushkarp%2Fnalcos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thepushkarp","download_url":"https://codeload.github.com/thepushkarp/nalcos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thepushkarp%2Fnalcos/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267632858,"owners_count":24118748,"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-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","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":["commit-search","commits","hacktoberfest","huggingface","information-retrieval","natural-language","nlp","python","sentence-transformers"],"created_at":"2024-10-26T19:52:01.469Z","updated_at":"2025-07-29T05:03:56.452Z","avatar_url":"https://github.com/thepushkarp.png","language":"Python","funding_links":["https://ko-fi.com/thepushkarp","https://www.buymeacoffee.com/thepushkarp"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eNaLCoS - NAtural Language COmmit Search\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eSearch commit messages in your repository in \u003cem\u003enatural language\u003c/em\u003e.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/thepushkarp/nalcos/issues\"\u003e\u003cimg alt=\"GitHub Issues\" src=\"https://img.shields.io/github/issues/thepushkarp/nalcos?style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/thepushkarp/nalcos/stargazers\"\u003e\u003cimg alt=\"Stargazers\" src=\"https://img.shields.io/github/stars/thepushkarp/nalcos?style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/thepushkarp/nalcos/blob/main/LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/thepushkarp/nalcos?style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003cbr\u003e\n   \u003ca href=\"https://github.com/thepushkarp/nalcos/releases\"\u003e\u003cimg alt=\"GitHub release (latest by date)\" src=\"https://img.shields.io/github/v/release/thepushkarp/nalcos?style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/nalcos/\"\u003e\u003cimg alt=\"PyPi\" src=\"https://img.shields.io/pypi/v/nalcos?style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003cbr\u003e\n  \u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n  \u003ca href=\"#contributors\"\u003e\u003cimg alt=\"All contributors\" src=\"https://img.shields.io/badge/all_contributors-1-orange.svg?style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\u003c/p\u003e\n\n---\n\nNaLCoS (NAtural Language COmmit Search) is a command-line tool for searching commit messages in your repository in \u003cem\u003enatural language\u003c/em\u003e.\n\nThe key features are:\n\n- Search commit messages in both local and remote GitHub repositories.\n- Search for commits in a specific branch.\n- Look back any number of commits in history.\n- Open the commit link directly in your browser if retrieved from GitHub.\n\n![image](https://user-images.githubusercontent.com/42088801/133908654-9cec1f5c-6e9f-4eba-9254-8383e05c3824.png)\n\nInternally, NaLCoS uses [Sentence Transformers](https://github.com/UKPLab/sentence-transformers) with pre-trained weights from [`multi-qa-MiniLM-L6-cos-v1`](https://huggingface.co/sentence-transformers/multi-qa-MiniLM-L6-cos-v1). I chose this particular model because it has a good [Performance vs Speed tradeoff](https://www.sbert.net/docs/pretrained_models.html). Since this model was designed for semantic search and has been pre-trained on 215M (question, answer) pairs from diverse sources, it is a good choice for tasks such as finding similarity between two sentences.\n\nNaLCoS encodes the query string and all the commits into their corresponding vector embeddings and computes the cosine similarity between the query and all the commits. This is then used to rank the commits.\n\n## Why did I build this?\n\nMost of the times when I've used Machine Learning till now, has been in dedicated environments such as Google Colab or Kaggle. I had been learning Natural Language Processing for a while and wanted to use transformers to build something different that is not very resource (read GPU) intensive and can be used like an everyday tool.\n\nThough many Transformer models are far from fitting this description, I found that distilled models are not as hungry as their older siblings are infamous for. Searching for Git commits using natural language was something on which I could not find any pre-existing tool and thus decided to give this a shot.\n\nThough there are various improvements left, I'm happy with what this initially turned out to be. I'm eager to see what further enhancements can be made to this to make it more efficient and useful.\n\n## Requirements\n\nNaLCoS uses the following packages:\n\n- [Sentence Transformers](https://github.com/UKPLab/sentence-transformers) for the Transformer model.\n- [Git Python](https://github.com/gitpython-developers/GitPython) for local Git operations.\n- [GitHub API](https://docs.github.com/en/rest) for interacting with GitHub repos.\n- [Rich](https://github.com/willmcgugan/rich) for well-formatted CLI output.\n\n## Installation\n\n### Installing with `pip` (Recommended)\n\nInstall with `pip` or your favourite PyPi manager:\n\n```console\n$ pip install nalcos\n```\n\nRun NaLCoS on a repository of your choice. For example:\n\n```console\n$ nalcos \"handle nan issues\" \"numpy/numpy\" --github\n```\n\nTo see all available options, run with the `--help` flag:\n\n```console\n$ nalcos --help\n```\n\n**Note**: When you run the `nalcos` command for the first time, it will, download the model which would be cached and used the next time you run NaLCoS.\n\n### Installing bleeding edge from the GitHub repository\n\n- Clone the repository:\n\n```console\n$ git clone https://github.com/thepushkarp/nalcos.git\n```\n\nThis also downloads the model weights stored in the `nalcos/models` directory so you don't have to download them while running the model for the first time.\n\n- cd into the `nalcos` directory:\n\n```console\n$ cd nalcos\n```\n\n- Create a virtual environment ([click here](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) to read about activating virtualenv):\n\n```\n$ virtualenv venv\n```\n\n- Activate virtualenv (for Linux and MacOS):\n\n```console\n$ source ./venv/bin/activate\n```\n\n- Activate virtualenv (for Windows):\n\n```console\n$ cd venv/Scripts/\n$ activate\n```\n\n- Install the requirements and the module:\n\n```console\n$ pip install -r requirements.txt\n$ pip install -e .\n```\n\nRun NaLCoS on a repository of your choice. For example:\n\n```console\n$ nalcos \"handle nan issues\" \"numpy/numpy\" --github\n```\n\nTo see all available options, run with the `--help` flag:\n\n```console\n$ nalcos --help\n```\n\n## Usage\n\nA detailed information about the usage of NaLCoS can be found below:\n\n```\nusage: nalcos [-h] [-g] [-n N_MATCHES] [-b BRANCH] [-l LOOK_PAST] [-s] [-v] [--version] query location\n\nSearch a commit in your git repository using natural language.\n\npositional arguments:\n  query                 The query to search for similar commit messages.\n  location              The repository path to search in. If '-g' or '--github' flag is not passed, searches\n                        locally in the path specified, else takes in a remote GitHub repository name in the\n                        format '{owner}/{repo_name}'\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -g, --github          Search on GitHub instead of searching in a local repository. Due to API limits\n                        currently this allows for around 15 lookups per hour from your IP.\n  -n N_MATCHES, --n-matches N_MATCHES\n                        The number of matching results to return. Default 10.\n  -b BRANCH, --branch BRANCH\n                        The branch to search in. If not specified, the current branch will be used by default.\n  -l LOOK_PAST, --look-past LOOK_PAST\n                        Look back this many commits. Default 100.\n  -s, --show-score      Shows the Cosine similarity score between the query and the retrieved commit messages.\n                        1 is the best match and -1 is the worst.\n  -v, --verbose         Show the entire commit message and not just the commit title.\n  --version             show program's version number and exit\n```\n\n### Examples\n\n- Input:\n\n```console\n$ nalcos \"handle nan issues\" \"numpy/numpy\" --github\n```\n\n- Output:\n\n```\nFound 100 commits.\n\n                                                  Commits related to \"handle nan issues\" in \"numpy/numpy\"\n┏━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓\n┃ No. ┃ Commit ID ┃ Commit Message                                                                            ┃ Commit Author       ┃ Commit Date          ┃\n┡━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩\n│  1. │ b6d7c4680 │ BUG: Fixed an issue wherein certain `nan\u003cx\u003e` functions could fail for object arrays       │ Bas van Beek        │ 2021-09-03T13:41:54Z │\n│  2. │ e4f85b08c │ Merge pull request #19863 from BvB93/nanquantile                                          │ Charles Harris      │ 2021-09-13T23:21:51Z │\n│  3. │ ecba7133f │ MAINT: Let `_remove_nan_1d` attempt to identify nan-containing object arrays              │ Bas van Beek        │ 2021-09-05T21:46:34Z │\n│  4. │ 95e5d5abb │ BUG: Fixed an issue wherein `nanpercentile` and `nanquantile` would ignore the dtype for  │ Bas van Beek        │ 2021-09-11T11:54:56Z │\n│     │           │ all-nan arrays                                                                            │                     │                      │\n│  5. │ b3a66e88b │ Merge pull request #19821 from BvB93/nanfunctions                                         │ Charles Harris      │ 2021-09-05T23:32:30Z │\n│  6. │ dc7dafe70 │ Merge pull request #19869 from mhvk/median_scalar_nan                                     │ Charles Harris      │ 2021-09-14T21:09:26Z │\n│  7. │ 9ef778330 │ TST: Add more tests for `nanmedian`, `nanquantile` and `nanpercentile`                    │ Bas van Beek        │ 2021-09-03T15:01:57Z │\n│  8. │ 6ba48721e │ BUG: ensure np.median does not drop subclass for NaN result.                              │ Marten van Kerkwijk │ 2021-09-13T19:50:54Z │\n│  9. │ e62aa4968 │ Merge pull request #19854 from BvB93/nanfunctions                                         │ Charles Harris      │ 2021-09-09T15:14:09Z │\n│ 10. │ 268e8e885 │ TST: Make nanfunc test ignore overflow instead of xfailing test                           │ Sebastian Berg      │ 2021-09-07T22:55:41Z │\n└─────┴───────────┴───────────────────────────────────────────────────────────────────────────────────────────┴─────────────────────┴──────────────────────┘\n```\n\n## Future plans\n\nPlease visit the [NaLCoS To Do Project Board](https://github.com/thepushkarp/nalcos/projects/1) to see current status and future plans.\n\n## Known issues\n\nNot all retrieved results are always relevant. I could think of two primary reasons for this:\n\n- The data the model was pre-trained on is not representative of how people write commit messages. Since commit messages usually contain technical jargon, merge commit messages, abbreviations and other non-common terms, the model (which has a limited vocabulary) is not able to generalize well to this data.\n- Two commits may be related even when their commit messages may not be similar and similarly two commit messages maybe unrelated even when their commit messages are similar. We often need more metadata (such as lines changes, files changed) etc. to make the predictions more accurate.\n\n## Contributing\n\nAny suggestions, improvements or bug reports are welcome.\n\n- If you want to discuss any aspect of the project, please use the [Discussions Tab](https://github.com/thepushkarp/nalcos/discussions).\n- You can submit your idea by [opening an issue](https://github.com/thepushkarp/nalcos/issues/new/choose) or [creating a Pull Request](https://github.com/thepushkarp/nalcos/pulls).\n- If you'd like to improve the code, make sure you stick to the existing code style and naming conventions.\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://thepushkarp.com/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/42088801?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ePushkar Patel\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/thepushkarp/nalcos/commits?author=thepushkarp\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/thepushkarp/nalcos/commits?author=thepushkarp\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#maintenance-thepushkarp\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthepushkarp%2Fnalcos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthepushkarp%2Fnalcos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthepushkarp%2Fnalcos/lists"}