| Name | hatch-vcs JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | |
| Summary | Hatch plugin for versioning with your preferred VCS |
| upload_time | 2023-11-06 06:24:57 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
git
hatch
mercurial
plugin
scm
vcs
version
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# hatch-vcs
| | |
| --- | --- |
| CI/CD | [](https://github.com/ofek/hatch-vcs/actions/workflows/test.yml) [](https://github.com/ofek/hatch-vcs/actions/workflows/build.yml) |
| Package | [](https://pypi.org/project/hatch-vcs/) [](https://pypi.org/project/hatch-vcs/) |
| Meta | [](https://github.com/pypa/hatch) [](https://github.com/psf/black) [](https://github.com/ambv/black) [](https://spdx.org/licenses/) [](https://github.com/sponsors/ofek) |
-----
This provides a plugin for [Hatch](https://github.com/pypa/hatch) that uses your preferred version control system (like Git) to determine project versions.
**Table of Contents**
- [Global dependency](#global-dependency)
- [Version source](#version-source)
- [Version source options](#version-source-options)
- [Version source environment variables](#version-source-environment-variables)
- [Build hook](#build-hook)
- [Build hook options](#build-hook-options)
- [Editable installs](#editable-installs)
- [Metadata hook](#metadata-hook)
- [Metadata hook options](#metadata-hook-options)
- [URLs](#urls)
- [Example](#example)
- [License](#license)
## Global dependency
Ensure `hatch-vcs` is defined within the `build-system.requires` field in your `pyproject.toml` file.
```toml
[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"
```
## Version source
The [version source plugin](https://hatch.pypa.io/latest/plugins/version-source/reference/) name is `vcs`.
- ***pyproject.toml***
```toml
[tool.hatch.version]
source = "vcs"
```
- ***hatch.toml***
```toml
[version]
source = "vcs"
```
### Version source options
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `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. |
| `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. |
| `raw-options` | `dict` | | A table of [`setuptools-scm` parameters](https://github.com/pypa/setuptools_scm#configuration-parameters) that will override any of the options listed above. The `write_to` and `write_to_template` parameters are ignored. |
### Version source environment variables
- `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.
## Build hook
The [build hook plugin](https://hatch.pypa.io/latest/plugins/build-hook/reference/) name is `vcs`.
- ***pyproject.toml***
```toml
[tool.hatch.build.hooks.vcs]
version-file = "_version.py"
```
- ***hatch.toml***
```toml
[build.hooks.vcs]
version-file = "_version.py"
```
Building or installing when the latest tag is ``v1.2.3`` will generate the file
- ***_version.py***
```python
# coding: utf-8
# file generated by setuptools_scm
# don't change, don't track in version control
__version__ = version = '1.2.3'
__version_tuple__ = version_tuple = (1, 2, 3)
```
### Build hook options
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `version-file` | `str` | ***REQUIRED*** | The relative path to the file that gets updated with the current version. |
| `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. |
### Editable installs
The 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).
## Metadata hook
**Note:** only Git is supported
The [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`.
- ***pyproject.toml***
```toml
[tool.hatch.metadata.hooks.vcs]
```
- ***hatch.toml***
```toml
[metadata.hooks.vcs]
```
### Metadata hook options
#### URLs
The `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:
- `commit_hash` - the latest commit hash
Be sure to add `urls` to [`project.dynamic`](https://hatch.pypa.io/latest/config/metadata/#dynamic):
- ***pyproject.toml***
```toml
[project]
dynamic = [
"urls",
]
```
### Example
- ***pyproject.toml***
```toml
[tool.hatch.metadata.hooks.vcs.urls]
Homepage = "https://www.example.com"
source_archive = "https://github.com/org/repo/archive/{commit_hash}.zip"
```
- ***hatch.toml***
```toml
[metadata.hooks.vcs.urls]
Homepage = "https://www.example.com"
source_archive = "https://github.com/org/repo/archive/{commit_hash}.zip"
```
## Migration tips
If you are migrating from [setuptools](https://setuptools.pypa.io), you may want access to
the version without performing a full build.
By default, `python -m setuptools_scm` will display the version and perform any side-effects
like writing to a file. `hatch` separates these functions.
### Display version
`hatch version` will print the version to the terminal without modifying the source directory.
```console
$ hatch version
23.0.0.dev17+g462372ba
```
### Write version to file
If `version-file` is defined, you can write it to the source directory with the `build` command,
using the `--hooks-only` flag to modify the source tree but skip creation of sdists or wheels.
```console
$ hatch build --hooks-only
$ cat package/_version.py
# file generated by setuptools_scm
# don't change, don't track in version control
__version__ = version = '23.0.0.dev17+g462372ba'
__version_tuple__ = version_tuple = (23, 0, 0, 'dev17', 'g462372ba')
```
## License
`hatch-vcs` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
Raw data
{
"_id": null,
"home_page": "",
"name": "hatch-vcs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "git,hatch,mercurial,plugin,scm,vcs,version",
"author": "",
"author_email": "Ofek Lev <oss@ofek.dev>",
"download_url": "https://files.pythonhosted.org/packages/f5/c9/54bb4fa27b4e4a014ef3bb17710cdf692b3aa2cbc7953da885f1bf7e06ea/hatch_vcs-0.4.0.tar.gz",
"platform": null,
"description": "# hatch-vcs\n\n| | |\n| --- | --- |\n| CI/CD | [](https://github.com/ofek/hatch-vcs/actions/workflows/test.yml) [](https://github.com/ofek/hatch-vcs/actions/workflows/build.yml) |\n| Package | [](https://pypi.org/project/hatch-vcs/) [](https://pypi.org/project/hatch-vcs/) |\n| Meta | [](https://github.com/pypa/hatch) [](https://github.com/psf/black) [](https://github.com/ambv/black) [](https://spdx.org/licenses/) [](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://github.com/pypa/setuptools_scm#configuration-parameters) that will override any of the options listed above. The `write_to` and `write_to_template` parameters are ignored. |\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",
"bugtrack_url": null,
"license": "MIT",
"summary": "Hatch plugin for versioning with your preferred VCS",
"version": "0.4.0",
"project_urls": {
"Funding": "https://github.com/sponsors/ofek",
"History": "https://github.com/ofek/hatch-vcs/blob/master/HISTORY.md",
"Issues": "https://github.com/ofek/hatch-vcs/issues",
"Source": "https://github.com/ofek/hatch-vcs"
},
"split_keywords": [
"git",
"hatch",
"mercurial",
"plugin",
"scm",
"vcs",
"version"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "820f6cbd9976160bc334add63bc2e7a58b1433a31b34b7cda6c5de6dd983d9a7",
"md5": "82bee9889b95170e550c98f8dd11bc61",
"sha256": "b8a2b6bee54cf6f9fc93762db73890017ae59c9081d1038a41f16235ceaf8b2c"
},
"downloads": -1,
"filename": "hatch_vcs-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "82bee9889b95170e550c98f8dd11bc61",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8412,
"upload_time": "2023-11-06T06:24:55",
"upload_time_iso_8601": "2023-11-06T06:24:55.389793Z",
"url": "https://files.pythonhosted.org/packages/82/0f/6cbd9976160bc334add63bc2e7a58b1433a31b34b7cda6c5de6dd983d9a7/hatch_vcs-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f5c954bb4fa27b4e4a014ef3bb17710cdf692b3aa2cbc7953da885f1bf7e06ea",
"md5": "d801fe7c3e5955307748f2790bbb3488",
"sha256": "093810748fe01db0d451fabcf2c1ac2688caefd232d4ede967090b1c1b07d9f7"
},
"downloads": -1,
"filename": "hatch_vcs-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "d801fe7c3e5955307748f2790bbb3488",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10917,
"upload_time": "2023-11-06T06:24:57",
"upload_time_iso_8601": "2023-11-06T06:24:57.228892Z",
"url": "https://files.pythonhosted.org/packages/f5/c9/54bb4fa27b4e4a014ef3bb17710cdf692b3aa2cbc7953da885f1bf7e06ea/hatch_vcs-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-06 06:24:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sponsors",
"github_project": "ofek",
"github_not_found": true,
"lcname": "hatch-vcs"
}
