Metadata-Version: 2.1
Name: hgtools
Version: 9.2.0
Summary: Classes for Mercurial and Git repositories
Home-page: https://github.com/jaraco/hgtools
Author: Jason R. Coombs
Author-email: jaraco@jaraco.com
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Version Control
Classifier: Framework :: Setuptools Plugin
Requires-Python: >=3.7
License-File: LICENSE
Requires-Dist: packaging
Requires-Dist: jaraco.classes
Requires-Dist: more-itertools
Provides-Extra: docs
Requires-Dist: sphinx (>=3.5) ; extra == 'docs'
Requires-Dist: jaraco.packaging (>=9) ; extra == 'docs'
Requires-Dist: rst.linker (>=1.9) ; extra == 'docs'
Requires-Dist: furo ; extra == 'docs'
Requires-Dist: sphinx-lint ; extra == 'docs'
Provides-Extra: testing
Requires-Dist: pytest (>=6) ; extra == 'testing'
Requires-Dist: pytest-checkdocs (>=2.4) ; extra == 'testing'
Requires-Dist: pytest-cov ; extra == 'testing'
Requires-Dist: pytest-enabler (>=1.3) ; extra == 'testing'
Requires-Dist: pytest-ruff ; extra == 'testing'
Requires-Dist: pygments ; extra == 'testing'
Requires-Dist: pytest-black (>=0.3.7) ; (platform_python_implementation != "PyPy") and extra == 'testing'
Requires-Dist: pytest-mypy (>=0.9.1) ; (platform_python_implementation != "PyPy") and extra == 'testing'

.. image:: https://img.shields.io/pypi/v/hgtools.svg
   :target: https://pypi.org/project/hgtools

.. image:: https://img.shields.io/pypi/pyversions/hgtools.svg

.. image:: https://github.com/jaraco/hgtools/workflows/tests/badge.svg
   :target: https://github.com/jaraco/hgtools/actions?query=workflow%3A%22tests%22
   :alt: tests

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json
    :target: https://github.com/astral-sh/ruff
    :alt: Ruff

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black
   :alt: Code style: Black

.. .. image:: https://readthedocs.org/projects/PROJECT_RTD/badge/?version=latest
..    :target: https://PROJECT_RTD.readthedocs.io/en/latest/?badge=latest

.. image:: https://img.shields.io/badge/skeleton-2023-informational
   :target: https://blog.jaraco.com/skeleton

Usage
=====

hgtools
provides classes for inspecting and working with repositories in the
Mercurial and Git version control systems (VCS).

The classes provided by hgtools are designed to use subprocess invocation to
leverage the command-line interfaces of the VCS tools ``hg`` and ``git``. An
in-process RepoManager for Mercurial exists but has been disabled due to
issues that arise when run in certain environments (namely setuptools
sandboxing).

Auto Version Numbering
**********************

With the 0.4 release, hgtools adds support for automatically generating
project version numbers from the repository in which the
project is developed.

To use this feature, your project must follow the following assumptions:

	 - Repo tags are used to indicate released versions.
	 - Tag names are specified as the version only (i.e. 0.1 and not
	   v0.1 or release-0.1)
	 - Released versions currently must conform to the Version in
	   `packaging <https://pypi.org/project/packaging>`_. Any tags
	   that don't match this scheme will be ignored.

Thereafter, use the RepoManager.get_current_version to
determine the version of the local code. If the current revision is tagged
with a valid version, that version will be used. Otherwise, the tags in
the repo will be searched, the latest release will be found, and hgtools
will infer the upcoming release version.

For example, if the repo contains the tags 0.1, 0.2, and 0.3 and the
repo is not on any of those tags, get_current_version will return
'0.3.1dev' and get_current_version(increment='0.1') will return
'0.4dev'.

Example::

    >>> from hgtools.managers import RepoManager
    >>> RepoManager().get_first_valid_manager().get_current_version()
    '9.0.1.dev0'

