diff --git a/readme.md b/readme.md index ceb8c28..f4007e0 100644 --- a/readme.md +++ b/readme.md @@ -17,22 +17,34 @@ After installing via [NuGet](https://www.nuget.org/packages/GitInfo): 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: +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); -All generated constants also have a Summary documentation tag that shows the current -value in the intellisense tooltip, making it easier to see what the different values contain: - -![](https://raw.githubusercontent.com/devlooped/GitInfo/main/assets/images/tooltip.png) - > 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. -With this information at your fingertips, you can build any versioning attributes you want, +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: @@ -82,16 +94,29 @@ VB: ThisAssembly.Git.Commit)> ``` +> 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: ``` + + + false + - + + $(GitSemVerMajor).$(GitSemVerMinor).$(GitSemVerPatch)$(GitSemVerDashLabel)+$(GitBranch).$(GitCommit) + $(Version) + $(GitBranch) $(GitCommit) $(GitBranch) $(GitCommit) @@ -99,6 +124,12 @@ MSBuild: ``` +> 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 @@ -107,22 +138,6 @@ 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). -### MSBuild - -If you want to set other properties in your project, such as `$(Version)` or `$(PackageVersion)` -based on the populated values from GitInfo, you must do so from a target, such as: - -```xml - - - $(GitSemVerMajor).$(GitSemVerMinor).$(GitSemVerPatch)$(GitSemVerDashLabel)+$(GitBranch).$(GitCommit) - $(Version) - - -``` - -In this case, we're setting the version and package version. - ## Details Exposes the following information for use directly from any MSBuild @@ -148,31 +163,8 @@ target that depends on the GitInfo target: $(GitIsDirty) ``` -From C#, F# and VB, by default code is generated too so that the same -information can be accessed from code, to construct your own -assembly/file version attributes with whatever format you want: - -```csharp -[assembly: AssemblyVersion (ThisAssembly.Git.SemVer.Major + "." + ThisAssembly.Git.SemVer.Minor + "." + ThisAssembly.Git.SemVer.Patch)] -[assembly: AssemblyInformationalVersion ( - ThisAssembly.Git.SemVer.Major + "." + - ThisAssembly.Git.SemVer.Minor + "." + - ThisAssembly.Git.SemVer.Patch + "-" + - ThisAssembly.Git.Branch + "+" + - ThisAssembly.Git.Commit)] -// i..e ^: 1.0.2-main+c218617 -``` - -> NOTE: you may need to close and reopen the solution in order -> for Visual Studio to refresh intellisense and show the -> ThisAssembly type right after package installation for -> the first time. - -All generated constants also have a Summary documentation tag -that shows the current value in the intellisense tooltip, making -it very easy to see what the different values contain. - -The available constants from code are: +For C#, F# and VB, constants are generated too so that the same information can be +accessed from code: ``` ThisAssembly.Git.RepositoryUrl @@ -193,15 +185,21 @@ The available constants from code are: 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'. + 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. diff --git a/src/GitInfo/build/GitInfo.targets b/src/GitInfo/build/GitInfo.targets index 2627ed4..e09e5ad 100644 --- a/src/GitInfo/build/GitInfo.targets +++ b/src/GitInfo/build/GitInfo.targets @@ -1,5 +1,5 @@ - +