Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/devlooped/GitInfo
Git and SemVer Info from MSBuild, C# and VB
https://github.com/devlooped/GitInfo
Last synced: about 2 months ago
JSON representation
Git and SemVer Info from MSBuild, C# and VB
- Host: GitHub
- URL: https://github.com/devlooped/GitInfo
- Owner: devlooped
- License: mit
- Created: 2015-05-26T04:05:59.000Z (over 9 years ago)
- Default Branch: main
- Last Pushed: 2024-05-20T10:04:01.000Z (4 months ago)
- Last Synced: 2024-05-22T08:07:51.341Z (4 months ago)
- Language: C#
- Homepage: https://clarius.org/GitInfo
- Size: 484 KB
- Stars: 518
- Watchers: 12
- Forks: 70
- Open Issues: 7
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- Funding: .github/FUNDING.yml
- License: license.txt
Awesome Lists containing this project
- stars - devlooped/GitInfo
README
 GitInfo
============
Git Info from MSBuild, C# and VB
> A fresh and transparent approach to Git information retrieval from MSBuild and Code without
> using any custom tasks or compiled code and tools, obscure settings, format strings, etc.
[](https://www.nuget.org/packages/GitInfo)
[](https://www.nuget.org/packages/GitInfo)
[](https://opensource.org/licenses/mit-license.php)
[](https://ci.appveyor.com/project/MobileEssentials/gitinfo)
## Usage
After installing via [NuGet](https://www.nuget.org/packages/GitInfo):
```pwsh
PM> Install-Package GitInfo
```
By default, if the containing project is a C#, F# or VB project, a compile-time generated
source file will contain all the git information and can be accessed from anywhere within
the assembly, as constants in a `ThisAssembly` (partial) class and its nested `Git` static class:
```csharp
Console.WriteLine(ThisAssembly.Git.Commit);
```
> NOTE: you may need to close and reopen the solution in order
> for Visual Studio to refresh intellisense and show the
> ThisAssembly type the first time after installing the package.
By default, GitInfo will also set `$(Version)` and `$(PackageVersion)` which the .NET
SDK uses for deriving the AssemblyInfo, FileVersion and InformationalVersion values,
as well as for packing. This default version is formatted from the following populated
MSBuild properties: `$(GitSemVerMajor).$(GitSemVerMinor).$(GitSemVerPatch)$(GitSemVerDashLabel)+$(GitBranch).$(GitCommit)`.
So, straight after install and build/pack, you will get some versioning in place :).
Alternatively, you can opt-out of this default versioning by setting `GitVersion=false`
in your project file, if you want to just leverage the Git information and/or version
properties/constants yourself:
```xml
false
```
This allows you to use the provided constants to build any versioning attributes you want,
with whatever information you want, without resorting to settings, format strings or anything,
just plain code:
C#:
```csharp
[assembly: AssemblyVersion(ThisAssembly.Git.BaseVersion.Major + "." + ThisAssembly.Git.BaseVersion.Minor + "." + ThisAssembly.Git.BaseVersion.Patch)]
[assembly: AssemblyFileVersion(ThisAssembly.Git.SemVer.Major + "." + ThisAssembly.Git.SemVer.Minor + "." + ThisAssembly.Git.SemVer.Patch)]
[assembly: AssemblyInformationalVersion(
ThisAssembly.Git.SemVer.Major + "." +
ThisAssembly.Git.SemVer.Minor + "." +
ThisAssembly.Git.Commits + "-" +
ThisAssembly.Git.Branch + "+" +
ThisAssembly.Git.Commit)]
```
F#:
```fsharp
module AssemblyInfo
open System.Reflection
[]
[]
[]
do ()
```
VB:
```vbnet
```
> NOTE: when generating your own assembly version attributes, you will need to turn off
> the corresponding assembly version attribute generation from the .NET SDK, by setting
> the relevant properties to false: `GenerateAssemblyVersionAttribute`,
> `GenerateAssemblyFileVersionAttribute` and `GenerateAssemblyInformationalVersionAttribute`.
MSBuild:
```xml
false
$(GitSemVerMajor).$(GitSemVerMinor).$(GitSemVerPatch)$(GitSemVerDashLabel)+$(GitBranch).$(GitCommit)
$(Version)
$(GitBranch)
$(GitCommit)
$(GitBranch) $(GitCommit)
```
> NOTE: because the provided properties are populated via targets that need to run
> before they are available, you cannot use the GitInfo-provided properties in a
> PropertyGroup at the project level. You can only use them from within a target that
> in turn depends on the relevant target from GitInfo (typically, `GitVersion` as
> shown above, if you consume the SemVer properties).
Because this information is readily available whenever you build the project, you
never depend on CI build scripts that generate versions for you, and you can
always compile locally exactly the same version of an assembly that was built by
a CI server.
You can read more about this project at the
[GitInfo announcement blog post](http://www.cazzulino.com/git-info-from-msbuild-and-code.html).
## Details
Exposes the following information for use directly from any MSBuild
target that depends on the GitInfo target:
```
$(GitRepositoryUrl)
$(GitBranch)
$(GitCommit)
$(GitCommitDate)
$(GitCommits)
$(GitTag)
$(GitBaseTag)
$(GitBaseVersionMajor)
$(GitBaseVersionMinor)
$(GitBaseVersionPatch)
$(GitSemVerMajor)
$(GitSemVerMinor)
$(GitSemVerPatch)
$(GitSemVerLabel)
$(GitSemVerDashLabel)
$(GitSemVerSource)
$(GitIsDirty)
```
For C#, F# and VB, constants are generated too so that the same information can be
accessed from code:
```
ThisAssembly.Git.RepositoryUrl
ThisAssembly.Git.Branch
ThisAssembly.Git.Commit
ThisAssembly.Git.Commits
ThisAssembly.Git.Tag
ThisAssembly.Git.BaseTag
ThisAssembly.Git.BaseVersion.Major
ThisAssembly.Git.BaseVersion.Minor
ThisAssembly.Git.BaseVersion.Patch
ThisAssembly.Git.SemVer.Major
ThisAssembly.Git.SemVer.Minor
ThisAssembly.Git.SemVer.Patch
ThisAssembly.Git.SemVer.Label
ThisAssembly.Git.SemVer.DashLabel
ThisAssembly.Git.SemVer.Source
ThisAssembly.Git.IsDirty
```
Available [MSBuild properties](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-properties)
to customize the behavior:
```
$(GitVersion): set to 'false' to avoid setting Version and PackageVersion to a default version with format:
$(GitSemVerMajor).$(GitSemVerMinor).$(GitSemVerPatch)$(GitSemVerDashLabel)+$(GitBranch).$(GitCommit)
$(GitThisAssembly): set to 'false' to prevent assembly metadata and constants generation.
$(GitThisAssemblyMetadata): set to 'false' to prevent assembly metadata generation only. Defaults to 'false'.
If 'true', it will also provide assembly metadata attributes for each of the populated values.
$(ThisAssemblyNamespace): allows overriding the namespace for the ThisAssembly class. Defaults to the global namespace.
$(GitRemote): name of remote to get repository url for. Defaults to 'origin'.
$(GitDefaultBranch): determines the base branch used to calculate commits on top of current branch. Defaults to 'main'.
$(GitVersionFile): determines the name of a file in the Git repository root used to provide the base version info. Defaults to 'GitInfo.txt'.
$(GitCommitsRelativeTo): optionally specifies an alternative directory for counting commits on top of the base version. Defaults to the $(GitVersionFile) directory.
$(GitCommitsIgnoreMerges): set to 'true' to ignore merge commits when calculating the number of commits. Defaults to 'false'.
$(GitInfoReportImportance): allows rendering all the retrieved git information with the specified message importance ('high', 'normal' or 'low'). Defaults to 'low'.
$(GitIgnoreBranchVersion) and $(GitIgnoreTagVersion): determines whether the branch and tags (if any) will be used to find a base version. Defaults to empty value (no ignoring).
$(GitNameRevOptions): options passed to git name-rev when finding a branch name for a commit (Detached head). The default is '--refs=refs/heads/* --no-undefined --always'
meaning branch names only, falling back to commit hash. For the legacy behavior where $(GitBranch) for detached head can also be a tag name, use '--refs=refs/*'.
Refs can be included and excluded, see git name-rev docs.
$(GitSkipCache): whether to cache the Git information determined in a previous build in a GitInfo.cache for performance reasons. Defaults to empty value (no ignoring).
$(GitCachePath): where to cache the determined Git information. Gives the chance to use a shared location for different projects. This can improve the overall build time.
Has to end with a path seperator Defaults to empty value ('$(IntermediateOutputPath)').
$(GitTagRegex): regular expression used with git describe to filter the tags to consider for base version lookup. Defaults to * (all).
$(GitBaseVersionRegex): regular expression used to match and validate valid base versions in branch, tag or file sources. By default, matches any string that *ends* in a valid SemVer2 string.
Defaults to 'v?(?\d+)\.(?\d+)\.(?\d+)(?:\-(?[\dA-Za-z\-\.]+))?$|^(?[\dA-Za-z\-\.]+)\-v?(?\d+)\.(?\d+)\.(?\d+)$'
$(GitCommitDateFormat): value passed as the format option when trying to retrieve the git commit date. Defaults to %%cI (windows) or %cI (non windows).
```
## Goals
- No compiled code or tools -> 100% transparency
- Trivially added/installed via [a NuGet package](https://www.nuget.org/packages/GitInfo)
- No format strings or settings to learn
- Simple well-structured [.targets file](https://github.com/kzu/GitInfo/blob/main/src/GitInfo/build/GitInfo.targets)
with plain MSBuild and no custom tasks
- [Optional embedding](https://github.com/kzu/GitInfo/blob/main/src/GitInfo/build/GitInfo.AssemblyMetadata.targets)
of Git info in assembly metadata
- Optional use of Git info to build arbitrary assembly/file version information, both
[in C#](https://github.com/kzu/GitInfoDemo/blob/main/GitInfoDemo/Properties/AssemblyInfo.cs#L10) as well
[as VB](https://github.com/kzu/GitInfoDemo/blob/main/GitInfoDemoVB/My%20Project/AssemblyInfo.vb#L8).
- Trivially modified/improved generated code by just adjusting a
[C#](https://github.com/kzu/GitInfo/blob/main/src/GitInfo/build/GitInfo.cs.pp) or
[F#](https://github.com/kzu/GitInfo/blob/main/src/GitInfo/build/GitInfo.fs.pp) or
[VB](https://github.com/kzu/GitInfo/blob/main/src/GitInfo/build/GitInfo.vb.pp) template
included in the [NuGet package](https://www.nuget.org/packages/GitInfo)
- 100% incremental build-friendly and high-performing (all proper Inputs/Outputs in place, smart caching of Git info, etc.)
# Sponsors
[](https://github.com/clarius)
[](https://github.com/KirillOsenkov)
[](https://github.com/MFB-Technologies-Inc)
[](https://github.com/decriptor)
[](https://github.com/torutek-gh)
[](https://github.com/drivenet)
[](https://github.com/AshleyMedway)
[](https://github.com/Keflon)
[](https://github.com/tbolon)
[](https://github.com/kfrancis)
[](https://github.com/twenzel)
[](https://github.com/Giorgi)
[](https://github.com/MikeCodesDotNET)
[](https://github.com/unoplatform)
[](https://github.com/dansiegel)
[](https://github.com/rbnswartz)
[](https://github.com/jfoshee)
[](https://github.com/Mrxx99)
[](https://github.com/eajhnsn1)
[](https://github.com/IxTechnologies)
[](https://github.com/davidjenni)
[](https://github.com/Jonathan-Hickey)
[](https://github.com/okyrylchuk)
[](https://github.com/akunzai)
[](https://github.com/jakobt)
[](https://github.com/seanalexander)
[](https://github.com/tinohager)
[](https://github.com/ploeh)
[](https://github.com/angelobelchior)
[](https://github.com/KenBonny)
[](https://github.com/SimonCropp)
[](https://github.com/agileworks-eu)
[](https://github.com/sorahex)
[](https://github.com/arsdragonfly)
[](https://github.com/vezel-dev)
[](https://github.com/ChilliCream)
[](https://github.com/4OTC)
[](https://github.com/sponsors/devlooped)
[Learn more about GitHub Sponsors](https://github.com/sponsors)