Project:
Package:
Development:
Contents
Overview
AutoGitSemVer uses commits in a git repository to calculate a semantic version. A commit's title and/or description can be used to increment a specific part of the semantic version and configuration files can be applied to control how the semantic version is generated. Finally, multiple, distinct semantic versions can be generated from different directories within the source tree.
How to use AutoGitSemVer
Running the Executable
From a terminal window, run:
| Scenario | Command Line | Output |
|---|---|---|
| Standard | autogitsemver |
Loading AutoGitSemVer configuration...DONE! (0, 0:00:00.001464, default configuration info will be used) Enumerating changes...DONE! (0, 0:00:00.193258, 1 change processed, no changes applied [0.00%]) Calculating semantic version... 0.6.1+20240318122529.BROWNELL08 DONE! (0, 0:00:00.054236) Results: DONE! (0, 0:00:00.267488) |
| Without Metadata | autogitsemver --no-metadata |
Loading AutoGitSemVer configuration...DONE! (0, 0:00:00.001468, default configuration info will be used) Enumerating changes...DONE! (0, 0:00:00.201744, 1 change processed, no changes applied [0.00%]) Calculating semantic version... 0.6.1 DONE! (0, 0:00:00.060190) Results: DONE! (0, 0:00:00.281524) |
| Quiet | autogitsemver --quiet |
0.6.1+20240318122751.BROWNELL08 |
| Verbose | autogitsemver --verbose |
Loading AutoGitSemVer configuration...DONE! (0, 0:00:00.001416, default configuration info will be used) Enumerating changes... VERBOSE: Processing '11c41919cb2ed8ef26542665fc9caa6544081457' (2024-03-09 11:53:11-05:00)...DONE! (0, 0:00:00.000049, 0.6.1) DONE! (0, 0:00:00.192439, 1 change processed, no changes applied [0.00%]) Calculating semantic version... 0.6.1+20240318122836.BROWNELL08 DONE! (0, 0:00:00.053696) Results: DONE! (0, 0:00:00.265691) |
| Display Help | autogitsemver --help |
Usage: autogitsemver [OPTIONS] [PATH] Automatically generates semantic versions based on changes in a git repository. ┌─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ path [PATH] Generate a semantic version based on changes that impact the specified path. [default: C:\Code\AutoGitSemVer] │ └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ┌─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ --style [Standard|AllPrerelease|AllMetadata] Specifies the way in which the semantic version is generated; this is useful when targets using the generated │ │ semantic version do not fully support the semantic version specification. │ │ [default: GenerateStyle.Standard] │ │ --prerelease-name TEXT Create a semantic version string with this prerelease name. [default: None] │ │ --no-prefix Do not include the prefix in the generated semantic version. │ │ --no-branch-name Do not include the branch name in the prerelease section of the generated semantic version. │ │ --no-metadata Do not include the build metadata section of the generated semantic version. │ │ --verbose Write verbose information to the terminal. │ │ --debug Write debug information to the terminal. │ │ --quiet Do not display any information other than the generated semantic version. │ │ --version Display the version of this tool and exit. │ │ --install-completion [bash|zsh|fish|powershell|pwsh] Install completion for the specified shell. [default: None] │ │ --show-completion [bash|zsh|fish|powershell|pwsh] Show completion for the specified shell, to copy it or customize the installation. [default: None] │ │ --help Show this message and exit. │ └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ |
| Version | autogitsemver --version |
autogitsemver v0.7.0 |
Running with Python
from io import StringIO
from pathlib import Path
from AutoGitSemVer import GetSemanticVersion
from dbrownell_Common.Streams.DoneManager import DoneManager
with DoneManager.Create(StringIO(), "") as dm:
path = Path.cwd()
result = GetSemanticVersion(dm, path)
print(result.semantic_version_string)
Updating the Version
A simplified semantic version is defined by a major number, a minor number, and a patch number in the form:
<major>.<minor>.<patch>
Changes to each of these numbers convey different meanings to those who have taken a dependency on the solution decorated by a semantic version:
- Changes to a
majornumber indicate that backwards-incompatible functionality was introduced. - Changes to a
minornumber indicate that backwards-compatible functionality was introduced. - Changes to a
patchnumber indicate that changes were introduced (but those changes did not introduce new functionality).
By default, AutoGitSemVer will increment the patch number for each git commit encountered.
Customizing the Update
The following tokens can be added anywhere in a git commit's title or description to increment the major, minor, or patch numbers:
| Semantic Version Number | Git Comment Token(s) | Example |
|---|---|---|
major |
+major |
1.2.3 -> 2.0.0 |
minor |
+minor, +feature |
1.2.3 -> 1.3.0 |
patch |
+patch |
1.2.3 -> 1.2.4 |
Examples
Modifier in the Description
| Git Commit Title: | Added feature Foo |
| Git Commit Description: | Foo lets a user... +minor |
Modifier in the Title
| Git Commit Title: | Added feature Foo (+minor) |
| Git Commit Description: | Foo lets a user... |
Advanced Configuration
Configuration Files
The way in which semantic versions are generated can be customized through configuration files named:
AutoGitSemVer.jsonAutoGitSemVer.yamlAutoGitSemVer.yml
These configuration files will impact the semantic versions generated for any changes in files or directories in the directory or its children. For example, given the directory structure:
<root>
|- File1.txt
|- DirectoryA
|- AutoGitSemVer.json
|- FileA.txt
|- DirectoryA.1
|- FileA1.txt
|- DirectoryB
|- AutoGitSemVer.yaml
|- FileB.txt
| File with Changes | Configuration Filename |
|---|---|
File1.txt |
None |
FileA.txt |
DirectoryA/AutoGitSemVer.json |
FileA1.txt |
DirectoryA/AutoGitSemVer.json |
FileB.txt |
DirectoryB/AutoGitSemVer.yaml |
The configuration file used when generating the semantic version is displayed when running AutoGitSemVer.
Information about the contents of these configuration files can be found in AutoGitSemVerSchema.SimpleSchema.
A simple example of a configuration file can be found here.
Installation
| Installation Method | Command |
|---|---|
| Via uv | uv add AutoGitSemVer |
| Via pip | pip install AutoGitSemVer |
Verifying Signed Artifacts
Artifacts are signed and verified using py-minisign and the public key in the file ./minisign_key.pub.
To verify that an artifact is valid, visit the latest release and download the .minisign signature file that corresponds to the artifact, then run the following command, replacing <filename> with the name of the artifact to be verified:
uv run --with py-minisign python -c "import minisign; minisign.PublicKey.from_file('minisign_key.pub').verify_file('<filename>'); print('The file has been verified.')"
Development
Please visit Contributing and Development for information on contributing to this project.
Additional Information
Additional information can be found at these locations.
| Title | Document | Description |
|---|---|---|
| Code of Conduct | CODE_OF_CONDUCT.md | Information about the norms, rules, and responsibilities we adhere to when participating in this open source community. |
| Contributing | CONTRIBUTING.md | Information about contributing to this project. |
| Development | DEVELOPMENT.md | Information about development activities involved in making changes to this project. |
| Governance | GOVERNANCE.md | Information about how this project is governed. |
| Maintainers | MAINTAINERS.md | Information about individuals who maintain this project. |
| Security | SECURITY.md | Information about how to privately report security issues associated with this project. |
License
AutoGitSemVer is licensed under the MIT license.
1 maintainer
Metadata
1 maintainer
Release files for AutoGitSemVer 0.9.20
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| autogitsemver-0.9.20.tar.gz | 14.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| autogitsemver-0.9.20-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 31.1 kB
Release files / autogitsemver-0.9.20.tar.gz
| Download URL | autogitsemver-0.9.20.tar.gz |
|---|---|
| Size | 14.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dea4f7e0a114c79417df36742e55754b52d46f15b7c8bf4cf3abfb41eed64bc1
|
|
BLAKE2b-256 checksum How to use checksums |
3676f754e72d823181e31302ed936e81a07bc5947608ab86a13d2f6d9569cebb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / autogitsemver-0.9.20-py3-none-any.whl
| Download URL | autogitsemver-0.9.20-py3-none-any.whl |
|---|---|
| Size | 16.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0cc96e6b445486dc6ff09370990bf54e0fe9782bb354ed34ad0871dd0f8022a0
|
|
BLAKE2b-256 checksum How to use checksums |
eaa1085d0f3e6325637fd20e6d8da78dfe527f95f9eaf2cd9b5493c2d2114b66
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
