From 9a35a04f4cba279306928ce6af73e569d5bdc1d3 Mon Sep 17 00:00:00 2001 From: Chris Davis <74455480+chris-codeflow@users.noreply.github.com> Date: Thu, 19 Nov 2020 22:10:23 +0000 Subject: [PATCH] Added setup and execute task examples. --- .../gitversion/execute/usage-examples.md | 294 ++++++++++++++++++ docs/examples/azure/gitversion/index.md | 52 +--- .../azure/gitversion/setup/usage-examples.md | 57 ++++ 3 files changed, 361 insertions(+), 42 deletions(-) create mode 100644 docs/examples/azure/gitversion/execute/usage-examples.md create mode 100644 docs/examples/azure/gitversion/setup/usage-examples.md diff --git a/docs/examples/azure/gitversion/execute/usage-examples.md b/docs/examples/azure/gitversion/execute/usage-examples.md new file mode 100644 index 0000000..1fc9708 --- /dev/null +++ b/docs/examples/azure/gitversion/execute/usage-examples.md @@ -0,0 +1,294 @@ +# Execute GitVersion Task (gitversion/execute) Usage Examples + +Find out how to use the **gitversion/execute** task using the examples below. + +## Task inputs + +The Execute GitVersion task accepts the following inputs: + +```yaml +targetPath: + description: Optionally supply the path to the working directory. + required: false + default: '' +useConfigFile: + description: Whether to use a custom configuration file. + required: false + default: false +configFilePath: + description: Optional path to config file (defaults to GitVersion.yml). + required: false + default: '' +updateAssemblyInfo: + description: Whether to update versions in the AssemblyInfo files. + required: false + default: false +updateAssemblyInfoFilename: + description: Update versions in specified file. + required: false + default: '' +additionalArguments: + description: Additional arguments to send to GitVersion. + required: false + default: '' +``` + +## Task outputs + +The Execute GitVersion task creates the following job-scoped variables and multi-job output variables: + +- GitVersion.Major +- GitVersion.Minor +- GitVersion.Patch +- GitVersion.PreReleaseTag +- GitVersion.PreReleaseTagWithDash +- GitVersion.PreReleaseLabel +- GitVersion.PreReleaseNumber +- GitVersion.WeightedPreReleaseNumber +- GitVersion.BuildMetaData +- GitVersion.BuildMetaDataPadded +- GitVersion.FullBuildMetaData +- GitVersion.MajorMinorPatch +- GitVersion.SemVer +- GitVersion.LegacySemVer +- GitVersion.LegacySemVerPadded +- GitVersion.AssemblySemVer +- GitVersion.AssemblySemFileVer +- GitVersion.FullSemVer +- GitVersion.InformationalVersion +- GitVersion.BranchName +- GitVersion.EscapedBranchName +- GitVersion.Sha +- GitVersion.ShortSha +- GitVersion.NuGetVersionV2 +- GitVersion.NuGetVersion +- GitVersion.NuGetPreReleaseTagV2 +- GitVersion.NuGetPreReleaseTag +- GitVersion.VersionSourceSha +- GitVersion.CommitsSinceVersionSource +- GitVersion.CommitsSinceVersionSourcePadded +- GitVersion.UncommittedChanges +- GitVersion.CommitDate + +The job-scoped variables can be accessed using the macro syntax `$(GitVersion.)` in subsequent steps in the same job. Azure Pipelines also creates environment variables of the form `GITVERSION_`. See examples 5 and 6. + +The multi-job output variables can be accessed across jobs and stages, in both conditions and variables. See examples 7 to 10. + +**GitVersion also automatically updates the pre-defined Build variable `Build.BuildNumber`.** + +--- + +## Examples + +- Example 1: Calculate the version for the build. + + ```yaml + steps: + - task: gitversion/execute@0 + displayName: Determine Version + ``` + +--- + +- Example 2: Calculate the version for the build using the default config file (**GitVersion.yml**). + + ```yaml + steps: + - task: gitversion/execute@0 + displayName: Determine Version + inputs: + useConfigFile: true + ``` + + Example contents of **GitVersion.yml**: + + ```yaml + mode: Mainline + branches: + master: + regex: ^latest$ + pull-request: + tag: pr + ``` + +--- + +- Example 3: Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder. + + ```yaml + steps: + - task: gitversion/execute@0 + displayName: Determine Version + inputs: + useConfigFile: true + configFilePath: 'VersionConfig.yml' + ``` + +--- + +- Example 4: Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument). + + ```yaml + steps: + - task: gitversion/execute@0 + displayName: Display GitVersion config + inputs: + additionalArguments: '/showConfig' + ``` + +--- + +- Example 5: Calculate the version for the build and display all the calculated variables in the next step. + + ```yaml + - task: gitversion/execute@0 + displayName: Determine Version + + - script: | + echo Major: $(GitVersion.Major) + echo Minor: $(GitVersion.Minor) + echo Patch: $(GitVersion.Patch) + echo PreReleaseTag: $(GitVersion.PreReleaseTag) + echo PreReleaseTagWithDash: $(GitVersion.PreReleaseTagWithDash) + echo PreReleaseLabel: $(GitVersion.PreReleaseLabel) + echo PreReleaseNumber: $(GitVersion.PreReleaseNumber) + echo WeightedPreReleaseNumber: $(GitVersion.WeightedPreReleaseNumber) + echo BuildMetaData: $(GitVersion.BuildMetaData) + echo BuildMetaDataPadded: $(GitVersion.BuildMetaDataPadded) + echo FullBuildMetaData: $(GitVersion.FullBuildMetaData) + echo MajorMinorPatch: $(GitVersion.MajorMinorPatch) + echo SemVer: $(GitVersion.SemVer) + echo LegacySemVer: $(GitVersion.LegacySemVer) + echo LegacySemVerPadded: $(GitVersion.LegacySemVerPadded) + echo AssemblySemVer: $(GitVersion.AssemblySemVer) + echo AssemblySemFileVer: $(GitVersion.AssemblySemFileVer) + echo FullSemVer: $(GitVersion.FullSemVer) + echo InformationalVersion: $(GitVersion.InformationalVersion) + echo BranchName: $(GitVersion.BranchName) + echo EscapedBranchName: $(GitVersion.EscapedBranchName) + echo Sha: $(GitVersion.Sha) + echo ShortSha: $(GitVersion.ShortSha) + echo NuGetVersionV2: $(GitVersion.NuGetVersionV2) + echo NuGetVersion: $(GitVersion.NuGetVersion) + echo NuGetPreReleaseTagV2: $(GitVersion.NuGetPreReleaseTagV2) + echo NuGetPreReleaseTag: $(GitVersion.NuGetPreReleaseTag) + echo VersionSourceSha: $(GitVersion.VersionSourceSha) + echo CommitsSinceVersionSource: $(GitVersion.CommitsSinceVersionSource) + echo CommitsSinceVersionSourcePadded: $(GitVersion.CommitsSinceVersionSourcePadded) + echo UncommittedChanges: $(GitVersion.UncommittedChanges) + echo CommitDate: $(GitVersion.CommitDate) + ``` + +--- + +- Example 6: Calculate the version for the build and use the `GitVersion.NuGetVersion` variable to set the NuGet package version. + + ```yaml + - task: gitversion/execute@0 + displayName: Determine Version + + - task: DotNetCoreCLI@2 + displayName: Pack Example + inputs: + command: pack + packagesToPack: src/Example/LibExample.csproj + versioningScheme: byEnvVar + versionEnvVar: GitVersion.NuGetVersion # alternative syntax GITVERSION_NUGETVERSION (the former gets converted into the latter internally) + ``` + +--- + +- Example 7: Calculate the version for the build and use the `GitVersion.BranchName` variable in a condition for starting another job. + + ````yaml + job: CalculateVersion + displayName: Calculate version using GitVersion + steps: + - task: gitversion/setup@0 + displayName: Install GitVersion + inputs: + versionSpec: '5.x' + + - task: gitversion/execute@0 + displayName: Use GitVersion + name: Version # the step MUST be named to access its output variables in another job. + + job: CreateReleaseNotes + condition: and(succeeded(), eq(dependencies.CalculateVersion.outputs['Version.GitVersion.BranchName'], 'main') + dependsOn: CalculateVersion + ``` + +--- + +- Example 8: Calculate the version for the build and map the `GitVersion.SemVer` variable into a variable in another job. + + ```yaml + job: CalculateVersion + displayName: Calculate version using GitVersion + steps: + - task: gitversion/setup@0 + displayName: Install GitVersion + inputs: + versionSpec: '5.x' + + - task: gitversion/execute@0 + displayName: Use GitVersion + name: Version # the step MUST be named to access its output variables in another job. + + job: BuildAndPack + variables: + Ver.MajorMinorPatch: $[ dependencies.CalculateVersion.outputs['Version.GitVersion.MajorMinorPatch'] ] + steps: + ``` + +--- + +- Example 9: Calculate the version for the build and use the `GitVersion.Major` output variable in a condition for starting another stage. + + ````yaml + stages: + - stage: S1 + jobs: + - job: CalculateVersion + displayName: Calculate version number using GitVersion + steps: + - task: gitversion/setup@0 + displayName: Install GitVersion + inputs: + versionSpec: '5.x' + + - task: gitversion/execute@0 + displayName: Use GitVersion + name: Version # the step MUST be named to access its output variables in another stage. + + - stage: S2 + condition: and(succeeded(), gt(dependencies.S1.outputs['CalculateVersion.Version.GitVersion.Major'], 0)) + dependsOn: S1 + ``` + +--- + +- Example 10: Calculate the version for the build and map the `GitVersion.AssemblySemVer` variable into a variable in another job for a different stage. + + ```yaml + stages: + - stage: S1 + jobs: + - job: CalculateVersion + displayName: Calculate version number using GitVersion + steps: + - task: gitversion/setup@0 + displayName: Install GitVersion + inputs: + versionSpec: '5.x' + + - task: gitversion/execute@0 + displayName: Use GitVersion + name: Version # the step MUST be named to access its output variables in another stage. + - stage: S2 + dependsOn: S1 + jobs: + - job: UpdateAssemblyVersions + variables: + Ver.AssemblyVer: $[ stageDependencies.S1.CalculateVersion.outputs['Version.GitVersion.AssemblySemVer'] ] # Note the 'stageDependencies.' syntax. + ``` diff --git a/docs/examples/azure/gitversion/index.md b/docs/examples/azure/gitversion/index.md index 9269c51..c46e04b 100644 --- a/docs/examples/azure/gitversion/index.md +++ b/docs/examples/azure/gitversion/index.md @@ -1,43 +1,11 @@ -# Example +# GitVersion Tasks Usage Examples -```yaml - steps: - - task: gitversion/setup@0 - displayName: Install GitVersion - inputs: - versionSpec: '5.x' - - task: gitversion/execute@0 - displayName: Use GitVersion - - script: | - echo FullSemVer: $(fullSemVer) - echo ##vso[build.updatebuildnumber]$(fullSemVer) - echo Major: ${{ steps.gitversion.outputs.major }} - echo Minor: ${{ steps.gitversion.outputs.minor }} - echo Patch: ${{ steps.gitversion.outputs.patch }} - echo PreReleaseTag: ${{ steps.gitversion.outputs.preReleaseTag }} - echo PreReleaseTagWithDash: ${{ steps.gitversion.outputs.preReleaseTagWithDash }} - echo PreReleaseLabel: ${{ steps.gitversion.outputs.preReleaseLabel }} - echo PreReleaseNumber: ${{ steps.gitversion.outputs.preReleaseNumber }} - echo WeightedPreReleaseNumber: ${{ steps.gitversion.outputs.weightedPreReleaseNumber }} - echo BuildMetaData: ${{ steps.gitversion.outputs.buildMetaData }} - echo BuildMetaDataPadded: ${{ steps.gitversion.outputs.buildMetaDataPadded }} - echo FullBuildMetaData: ${{ steps.gitversion.outputs.fullBuildMetaData }} - echo MajorMinorPatch: ${{ steps.gitversion.outputs.majorMinorPatch }} - echo SemVer: ${{ steps.gitversion.outputs.semVer }} - echo LegacySemVer: ${{ steps.gitversion.outputs.legacySemVer }} - echo LegacySemVerPadded: ${{ steps.gitversion.outputs.legacySemVerPadded }} - echo AssemblySemVer: ${{ steps.gitversion.outputs.assemblySemVer }} - echo AssemblySemFileVer: ${{ steps.gitversion.outputs.assemblySemFileVer }} - echo InformationalVersion: ${{ steps.gitversion.outputs.informationalVersion }} - echo BranchName: ${{ steps.gitversion.outputs.branchName }} - echo Sha: ${{ steps.gitversion.outputs.sha }} - echo ShortSha: ${{ steps.gitversion.outputs.shortSha }} - echo NuGetVersionV2: ${{ steps.gitversion.outputs.nuGetVersionV2 }} - echo NuGetVersion: ${{ steps.gitversion.outputs.nuGetVersion }} - echo NuGetPreReleaseTagV2: ${{ steps.gitversion.outputs.nuGetPreReleaseTagV2 }} - echo NuGetPreReleaseTag: ${{ steps.gitversion.outputs.nuGetPreReleaseTag }} - echo VersionSourceSha: ${{ steps.gitversion.outputs.versionSourceSha }} - echo CommitsSinceVersionSource: ${{ steps.gitversion.outputs.commitsSinceVersionSource }} - echo CommitsSinceVersionSourcePadded: ${{ steps.gitversion.outputs.commitsSinceVersionSourcePadded }} - echo CommitDate: ${{ steps.gitversion.outputs.commitDate }} -``` +Use the following links to see usage examples of the Setup GitVersion (**gitversion/setup**) and Execute GitVersion (**gitversion/execute**) tasks. + +## Setup GitVersion (gitversion/setup) + +- [Usage examples](setup/usage-examples.md) + +## Execute GitVersion (gitversion/execute) + +- [Usage examples](execute/usage-examples.md) diff --git a/docs/examples/azure/gitversion/setup/usage-examples.md b/docs/examples/azure/gitversion/setup/usage-examples.md new file mode 100644 index 0000000..575fd38 --- /dev/null +++ b/docs/examples/azure/gitversion/setup/usage-examples.md @@ -0,0 +1,57 @@ +# Setup GitVersion Task (gitversion/setup) Usage Examples + +Find out how to use the **gitversion/setup** task using the examples below. + +## Task inputs + +The Setup GitVersion task accepts the following inputs: + +```yaml +versionSpec: + description: Required version in the form of 5.x or exact version like 5.0.0. + required: true + default: '' +includePrerelease: + description: Include pre-release versions when matching a version. + required: false + default: false +``` + +--- + +## Usage examples + +- Example 1: Install the latest GitVersion 5 version. + + ```yaml + steps: + - task: gitversion/setup@0 + displayName: Install GitVersion + inputs: + versionSpec: '5.x' + ``` + +--- + +- Example 2: Install GitVersion 5.5.0. + + ```yaml + steps: + - task: gitversion/setup@0 + displayName: Install GitVersion + inputs: + versionSpec: '5.5.0' + ``` + +--- + +- Example 3: Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**. + + ```yaml + steps: + - task: gitversion/setup@0 + displayName: Install GitVersion + inputs: + versionSpec: '6.x' + includePrerelease: true + ```