{"id":13600075,"url":"https://github.com/ofek/hatch-vcs","last_synced_at":"2025-05-15T09:05:20.883Z","repository":{"id":41286679,"uuid":"449491149","full_name":"ofek/hatch-vcs","owner":"ofek","description":"Hatch plugin for versioning with your preferred VCS","archived":false,"fork":false,"pushed_at":"2025-03-13T04:02:19.000Z","size":60,"stargazers_count":135,"open_issues_count":28,"forks_count":19,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-15T09:05:06.575Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/ofek.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2022-01-19T00:20:23.000Z","updated_at":"2025-05-07T07:37:25.000Z","dependencies_parsed_at":"2023-02-08T08:46:41.884Z","dependency_job_id":"6958f5c2-724b-47e3-9605-7ada4193daa3","html_url":"https://github.com/ofek/hatch-vcs","commit_stats":{"total_commits":42,"total_committers":12,"mean_commits":3.5,"dds":0.5476190476190477,"last_synced_commit":"48e8aba0f11d27a5b37f9e301ff8f902199269ef"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofek%2Fhatch-vcs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofek%2Fhatch-vcs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofek%2Fhatch-vcs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofek%2Fhatch-vcs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ofek","download_url":"https://codeload.github.com/ofek/hatch-vcs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310513,"owners_count":22049468,"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":[],"created_at":"2024-08-01T18:00:22.420Z","updated_at":"2025-05-15T09:05:20.832Z","avatar_url":"https://github.com/ofek.png","language":"Python","funding_links":["https://github.com/sponsors/ofek"],"categories":["Plugins"],"sub_categories":[],"readme":"# hatch-vcs\n\n| | |\n| --- | --- |\n| CI/CD | [![CI - Test](https://github.com/ofek/hatch-vcs/actions/workflows/test.yml/badge.svg)](https://github.com/ofek/hatch-vcs/actions/workflows/test.yml) [![CD - Build](https://github.com/ofek/hatch-vcs/actions/workflows/build.yml/badge.svg)](https://github.com/ofek/hatch-vcs/actions/workflows/build.yml) |\n| Package | [![PyPI - Version](https://img.shields.io/pypi/v/hatch-vcs.svg?logo=pypi\u0026label=PyPI\u0026logoColor=gold)](https://pypi.org/project/hatch-vcs/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hatch-vcs.svg?logo=python\u0026label=Python\u0026logoColor=gold)](https://pypi.org/project/hatch-vcs/) |\n| Meta | [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) [![code style - black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/ambv/black) [![License - MIT](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/) [![GitHub Sponsors](https://img.shields.io/github/sponsors/ofek?logo=GitHub%20Sponsors\u0026style=social)](https://github.com/sponsors/ofek) |\n\n-----\n\nThis provides a plugin for [Hatch](https://github.com/pypa/hatch) that uses your preferred version control system (like Git) to determine project versions.\n\n**Table of Contents**\n\n- [Global dependency](#global-dependency)\n- [Version source](#version-source)\n  - [Version source options](#version-source-options)\n  - [Version source environment variables](#version-source-environment-variables)\n- [Build hook](#build-hook)\n  - [Build hook options](#build-hook-options)\n  - [Editable installs](#editable-installs)\n- [Metadata hook](#metadata-hook)\n  - [Metadata hook options](#metadata-hook-options)\n    - [URLs](#urls)\n  - [Example](#example)\n- [License](#license)\n\n## Global dependency\n\nEnsure `hatch-vcs` is defined within the `build-system.requires` field in your `pyproject.toml` file.\n\n```toml\n[build-system]\nrequires = [\"hatchling\", \"hatch-vcs\"]\nbuild-backend = \"hatchling.build\"\n```\n\n## Version source\n\nThe [version source plugin](https://hatch.pypa.io/latest/plugins/version-source/reference/) name is `vcs`.\n\n- ***pyproject.toml***\n\n    ```toml\n    [tool.hatch.version]\n    source = \"vcs\"\n    ```\n\n- ***hatch.toml***\n\n    ```toml\n    [version]\n    source = \"vcs\"\n    ```\n\n### Version source options\n\n| Option | Type | Default | Description |\n| --- | --- | --- | --- |\n| `tag-pattern` | `str` | see [code](https://github.com/pypa/setuptools_scm/blob/v6.4.0/src/setuptools_scm/config.py#L13) | A regular expression used to extract the version part from VCS tags. The pattern needs to contain either a single match group, or a group named `version`, that captures the actual version information. |\n| `fallback-version` | `str` | | The version that will be used if no other method for detecting the version is successful. If not specified, unsuccessful version detection will raise an error. |\n| `raw-options` | `dict` | | A table of [`setuptools-scm` parameters](https://setuptools-scm.readthedocs.io/en/latest/config/) that will override any of the options listed above. The `write_to` and `write_to_template` parameters are ignored. |\n\nFor example, to prevent incrementing version numbers on non-release commits, you can adjust the `version_scheme` parameter for `setuptools-scm` as follows:\n\n- ***pyproject.toml***\n\n    ```toml\n    [tool.hatch.version.raw-options]\n    version_scheme = \"no-guess-dev\"\n    ```\n\n- ***hatch.toml***\n\n    ```toml\n    [version.raw-options]\n    version_scheme = \"no-guess-dev\"\n    ```\n\n### Version source environment variables\n\n- `SETUPTOOLS_SCM_PRETEND_VERSION`: When defined and not empty, it's used as the primary source for the version, in which case it will be an unparsed string.\n\n## Build hook\n\nThe [build hook plugin](https://hatch.pypa.io/latest/plugins/build-hook/reference/) name is `vcs`.\n\n- ***pyproject.toml***\n\n    ```toml\n    [tool.hatch.build.hooks.vcs]\n    version-file = \"_version.py\"\n    ```\n\n- ***hatch.toml***\n\n    ```toml\n    [build.hooks.vcs]\n    version-file = \"_version.py\"\n    ```\n\nBuilding or installing when the latest tag is ``v1.2.3`` will generate the file\n\n- ***_version.py***\n\n    ```python\n    # coding: utf-8\n    # file generated by setuptools_scm\n    # don't change, don't track in version control\n    __version__ = version = '1.2.3'\n    __version_tuple__ = version_tuple = (1, 2, 3)\n    ```\n\n### Build hook options\n\n| Option | Type | Default | Description |\n| --- | --- | --- | --- |\n| `version-file` | `str` | ***REQUIRED*** | The relative path to the file that gets updated with the current version. |\n| `template` | `str` | | The template used to overwrite the `version-file`. See the [code](https://github.com/pypa/setuptools_scm/blob/v6.4.0/src/setuptools_scm/__init__.py#L30-L39) for the default template for each file extension. |\n\n### Editable installs\n\nThe version file is only updated upon install or build. Thus the version number in an [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs) (Hatch's [dev mode](https://hatch.pypa.io/latest/config/build/#dev-mode)) will be incorrect if the version changes and the project is not rebuilt. An unsupported workaround for keeping the version number up-to-date can be found at [hatch-vcs-footgun-example](https://github.com/maresb/hatch-vcs-footgun-example).\n\n## Metadata hook\n\n**Note:** only Git is supported\n\nThe [metadata hook plugin](https://hatch.pypa.io/latest/plugins/metadata-hook/reference/) is for inserting VCS data (currently the commit hash) into metadata fields other than `version`. Its name is `vcs`.\n\n- ***pyproject.toml***\n\n    ```toml\n    [tool.hatch.metadata.hooks.vcs]\n    ```\n\n- ***hatch.toml***\n\n    ```toml\n    [metadata.hooks.vcs]\n    ```\n\n### Metadata hook options\n\n#### URLs\n\nThe `urls` option is equivalent to [`project.urls`](https://hatch.pypa.io/latest/config/metadata/#urls) except that each URL supports [context formatting](https://hatch.pypa.io/latest/config/context/) with the following fields:\n\n- `commit_hash` - the latest commit hash\n\nBe sure to add `urls` to [`project.dynamic`](https://hatch.pypa.io/latest/config/metadata/#dynamic):\n\n- ***pyproject.toml***\n\n    ```toml\n    [project]\n    dynamic = [\n      \"urls\",\n    ]\n    ```\n\n### Example\n\n- ***pyproject.toml***\n\n    ```toml\n    [tool.hatch.metadata.hooks.vcs.urls]\n    Homepage = \"https://www.example.com\"\n    source_archive = \"https://github.com/org/repo/archive/{commit_hash}.zip\"\n    ```\n\n- ***hatch.toml***\n\n    ```toml\n    [metadata.hooks.vcs.urls]\n    Homepage = \"https://www.example.com\"\n    source_archive = \"https://github.com/org/repo/archive/{commit_hash}.zip\"\n    ```\n\n## Migration tips\n\nIf you are migrating from [setuptools](https://setuptools.pypa.io), you may want access to\nthe version without performing a full build.\n\nBy default, `python -m setuptools_scm` will display the version and perform any side-effects\nlike writing to a file. `hatch` separates these functions.\n\n### Display version\n\n`hatch version` will print the version to the terminal without modifying the source directory.\n\n```console\n$ hatch version\n23.0.0.dev17+g462372ba\n```\n\n### Write version to file\n\nIf `version-file` is defined, you can write it to the source directory with the `build` command,\nusing the `--hooks-only` flag to modify the source tree but skip creation of sdists or wheels.\n\n```console\n$ hatch build --hooks-only\n$ cat package/_version.py\n# file generated by setuptools_scm\n# don't change, don't track in version control\n__version__ = version = '23.0.0.dev17+g462372ba'\n__version_tuple__ = version_tuple = (23, 0, 0, 'dev17', 'g462372ba')\n```\n\n## License\n\n`hatch-vcs` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fofek%2Fhatch-vcs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fofek%2Fhatch-vcs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fofek%2Fhatch-vcs/lists"}