diff --git a/readme.md b/readme.md index 711bd6e..a95895a 100644 --- a/readme.md +++ b/readme.md @@ -3,89 +3,95 @@ 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. +> 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. [![Latest version](https://img.shields.io/nuget/v/GitInfo.svg)](https://www.nuget.org/packages/GitInfo) [![Downloads](https://img.shields.io/nuget/dt/GitInfo.svg)](https://www.nuget.org/packages/GitInfo) [![License](https://img.shields.io/:license-MIT-blue.svg)](https://opensource.org/licenses/mit-license.php) -[![Build status](https://ci.appveyor.com/api/projects/status/p9e5xdd86vnfe0q8?svg=true)](https://ci.appveyor.com/project/MobileEssentials/gitinfo) +[![Build status](https://ci.appveyor.com/api/projects/status/p9e5xdd86vnfe0q8?svg=true)](https://ci.appveyor.com/project/MobileEssentials/gitinfo) ## Usage After installing via [NuGet](https://www.nuget.org/packages/GitInfo): - PM> Install-Package 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 +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: - Console.WriteLine(ThisAssembly.Git.Commit); +```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 +> 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)`. +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 +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 + 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, +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#: -``` -[assembly: AssemblyVersion (ThisAssembly.Git.BaseVersion.Major + "." + ThisAssembly.Git.BaseVersion.Minor + "." + ThisAssembly.Git.BaseVersion.Patch)] +```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: 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)] +[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`, +> the corresponding assembly version attribute generation from the .NET SDK, by setting +> the relevant properties to false: `GenerateAssemblyVersionAttribute`, > `GenerateAssemblyFileVersionAttribute` and `GenerateAssemblyInformationalVersionAttribute`. MSBuild: -``` - +```xml - - false + false + - - $(GitSemVerMajor).$(GitSemVerMinor).$(GitSemVerPatch)$(GitSemVerDashLabel)+$(GitBranch).$(GitCommit) - $(Version) - - $(GitBranch) - $(GitCommit) - $(GitBranch) $(GitCommit) - + + $(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 +> 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 +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 +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 +Exposes the following information for use directly from any MSBuild target that depends on the GitInfo target: ``` @@ -163,7 +167,7 @@ target that depends on the GitInfo target: $(GitIsDirty) ``` -For C#, F# and VB, constants are generated too so that the same information can be +For C#, F# and VB, constants are generated too so that the same information can be accessed from code: ``` @@ -185,77 +189,49 @@ accessed from code: ThisAssembly.Git.IsDirty ``` -Available [MSBuild properties](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-properties) +Available [MSBuild properties](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-properties) to customize the behavior: ``` - $(GitVersion): set to 'false' to prevent setting Version - and PackageVersion. - - $(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'. - - $(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). - - $(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)'). - - $(GitNameRevOptions): Options passed to git name-rev when finding - a branch name for the current commit (Detached head). The default is - '--refs=refs/heads/* --no-undefined --always' - meaning branch names only, falling back to commit hash. - For 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. - - $(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. + $(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+)(?:\-(?