Calculates a semantic version based on git changes.
Project description
AutoGitSemVer
AutoGitSemVer
Generate a semantic version based on commits made to a git repository.
Quick Start
- Install via executable, pip, or local development
- Run the executable
- Advanced Configuration
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
major
number indicate that backwards-incompatible functionality was introduced. - Changes to a
minor
number indicate that backwards-compatible functionality was introduced. - Changes to a
patch
number 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
Description
Git Commit Title: | Added feature Foo |
Git Commit Description: | Foo lets a user... +minor |
Title
Git Commit Title: | Added feature Foo (+minor) |
Git Commit Description: | Foo lets a user... |
Installation via Executable
Download an executable for Linux, MacOS, or Windows to use the functionality provided by this repository without a dependency on Python.
- Download the archive for the latest release here; the files will begin with
exe.
and contain the name of your operating system. - Decompress the archive
Installation via pip
Install the AutoGitSemVer package via pip (Package Installer for Python) to use it with your python code.
pip install AutoGitSemVer
Local Development
Follow these steps to prepare the repository for local development activities.
-
Clone this repository
-
Bootstrap the local repository by running...
Operating System Command Linux / MacOS Standard:
Bootstrap.sh
Standard + packaging:
Bootstrap.sh --package
Windows Standard:
Bootstrap.cmd
Standard + packaging:
Bootstrap.cmd --package
-
Activate the development environment by running...
Operating System Command Linux / MacOS . ./Activate.sh
Windows Activate.cmd
-
Invoke
Build.py
Command Description Example Notes black
Validates that the source code is formatted by black. Validation:
python Build.py black
Perform formatting:
python Build.py black --format
pylint
Validates the source code using pylint. python Build.py pylint
pytest
Runs automated tests using pytest. Without Code Coverage:
python Build.py pytest
With Code Coverage:
python Build.py pytest --code-coverage
update_version
Updates the semantic version of the package based on git commits using AutoGitSemVer. python Build.py update_version
package
Creates a Python wheel package for distribution; outputs to the /dist
directory.python Build.py package
Requires --package
when bootstrapping in step #2.publish
Publishes a Python wheel package to PyPi. https://test.pypi.org:
python Build.py publish
https://pypi.org:
python Build.py publish --production
Requires --package
when bootstrapping in step #2.build_binary
Builds an executable for your package that can be run on machines without a python installation; outputs to the /build
directory.python Build.py build_binary
Requires --package
when bootstrapping in step #2. -
[Optional] Deactivate the development environment by running...
Operating System Command Linux / MacOS . ./Deactivate.sh
Windows Deactivate.cmd
Advanced Configuration
Configuration Files
The way in which semantic versions are generated can be customized through configuration files named:
AutoGitSemVer.json
AutoGitSemVer.yaml
AutoGitSemVer.yml
This 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.
License
AutoGitSemVer is licensed under the MIT license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for AutoGitSemVer-0.7.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a6e9be9ca60029f03dce60fbb033ce29b74940b2084bd0e53f5b5df0f48e337e |
|
MD5 | 37496690fbe93b0e9362509050d6fff6 |
|
BLAKE2b-256 | d97b82ea40e8235cd5ba44045b0192e29d0f4b22d70d4017518e46062cd55181 |