Metadata-Version: 2.5
Name: usg-pygitversion
Version: 1.0.0
Summary: Semantic versioning from git history: a Python port of GitVersion, no .NET required.
Project-URL: Homepage, https://github.com/192d-Wing/usg-pygitversion
Project-URL: Documentation, https://github.com/192d-Wing/usg-pygitversion#readme
Project-URL: Changelog, https://github.com/192d-Wing/usg-pygitversion/releases
Project-URL: Issues, https://github.com/192d-Wing/usg-pygitversion/issues
Project-URL: Upstream (GitVersion), https://gitversion.net/docs/
Author: John Edward Willman V
License-Expression: MIT
License-File: LICENSE
Keywords: ci,git,gitversion,semver,versioning
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0.2
Description-Content-Type: text/markdown

<!-- SPDX-License-Identifier: MIT -->
# usg-pygitversion

Semantic versioning from git history, without .NET. A pure-Python port of
[GitVersion](https://gitversion.net) 6.8.2.

> **Status:** Phases 0-5 complete: the calculation engine for the GitFlow,
> GitHubFlow and TrunkBased (Mainline) workflows, the CLI, all outputs,
> the cache, the GitHub Actions and GitLab CI agents and the generic
> environment export are ported and verified against the reference 6.8.2
> binary on 500+ upstream scenarios. Phase 6 (hardening and the first
> release) is next; see `PLAN.md` for the roadmap and every design decision.

## Why

GitVersion is the standard tool for deriving SemVer from branches, tags and
merge history, but it needs the .NET runtime. This port runs anywhere Python
3.11+ and a `git` binary exist, and produces byte-compatible JSON so existing
scripts keep working.

## Install

```sh
uv tool install usg-pygitversion   # or: pipx install usg-pygitversion
```

Requires Python 3.11+ and a `git` binary on `PATH`; nothing else. In a
project that already uses `uv`, `uv add --dev usg-pygitversion` and then
`uv run gitversion` also works. Until the first PyPI release, install from
a checkout with `uv tool install /path/to/usg-pygitversion`.
The import package is `usg_pygitversion`; both `gitversion` (drop-in for the
.NET tool) and `usg-pygitversion` commands are installed.

## Use

```sh
gitversion                              # JSON, same as upstream
gitversion /showvariable SemVer         # upstream /flag syntax works
gitversion --showvariable SemVer        # so does --flag syntax
gitversion /format "{Major}.{Minor}"    # custom formatting
gitversion /output dotenv               # GitVersion_<Name>='value' lines
gitversion /output file /outputfile v.json
gitversion /showconfig                  # effective configuration as YAML
gitversion /overrideconfig tag-prefix=v /nocache
gitversion /output buildserver          # GitHub Actions / GitLab CI integration
```

For build servers without a dedicated agent, export the variables into
the environment of a shell or a file:

```sh
eval "$(python -m usg_pygitversion --output env)"                   # sh/bash/zsh
python -m usg_pygitversion --output env --shell powershell | Invoke-Expression
python -m usg_pygitversion --output env --shell cmd > gv.bat && call gv.bat
python -m usg_pygitversion --env-file "$SOME_CI_ENV_FILE"           # append KEY=value
```

Values are quoted for the chosen shell, so branch names cannot inject
commands. `--prefix` changes the `GitVersion_` prefix. Run
`gitversion /?` for the full argument list.

From Python, in a build script:

```python
import os, usg_pygitversion

v = usg_pygitversion.calculate(".")
usg_pygitversion.export_env(v, os.environ)   # GitVersion_* now visible to subprocesses
print(v.full_sem_ver)
```

## What is and is not ported

Ported: the full calculation pipeline, all three built-in workflows
(GitFlow/v1, GitHubFlow/v1, TrunkBased/preview1), `GitVersion.yml`
configuration, JSON / dotenv / file output, GitHub Actions and GitLab CI
build-agent integration, and a generic environment export for every other
CI system.

Not ported: AssemblyInfo / `.csproj` / WiX updaters, the MSBuild task, and
dynamic remote clone (`/url`). See `PLAN.md` section 1.

## Performance

A 50,000-commit linear history is versioned in about one second with under
30 MB of additional memory (`tests/perf`). On a real 17,000-commit repository
the port produces the same output as the .NET tool and runs faster.

## Security

See `SECURITY.md` for reporting and `docs/security/nist-800-53-mapping.md`
for how the tool maps to NIST SP 800-53 Rev 5 controls.

## License

MIT. GitVersion itself is MIT licensed; this project is an independent
reimplementation and is not affiliated with the GitTools organisation.
