Improve documentation

.azure/example-10.yml

@@ -0,0 +1,93 @@
+trigger: none
+
+variables:
+  - name: DOTNET_SKIP_FIRST_TIME_EXPERIENCE
+    value: 'true'
+  - name: DOTNET_CLI_TELEMETRY_OPTOUT
+    value: 'true'
+
+stages:
+  - stage: GitVersion_v5_cross_stage
+    displayName: GitVersion v5 (cross stage)
+    jobs:
+      - job: GitVersion_v5_cross_stage_producer
+        displayName: GitVersion v5 (cross stage producer)
+        pool:
+          vmImage: ubuntu-latest
+        steps:
+          - checkout: self
+            fetchDepth: 0
+
+          - task: gitversion/[email protected]
+            displayName: Install GitVersion
+            inputs:
+              versionSpec: '5.x'
+
+          - task: gitversion/[email protected]
+            displayName: Determine Version
+            name: version_step # step id used as reference for output values
+            inputs:
+              overrideConfig: |
+                update-build-number=false
+  - stage: GitVersion_v5_cross_stage_consumer_without_prefix
+    displayName: GitVersion v5 (cross stage consumer) - without prefix
+    dependsOn: GitVersion_v5_cross_stage
+    condition: and(succeeded(), eq(dependencies.GitVersion_v5_cross_stage.outputs['GitVersion_v5_cross_stage_producer.version_step.branchName'], 'main')) # use in condition
+    jobs:
+      - job: GitVersion_v5_cross_stage_consumer_without_prefix
+        displayName: GitVersion v5 (cross stage consumer) - without prefix
+        variables:
+          myvar_fullSemVer: $[ stageDependencies.GitVersion_v5_cross_stage.GitVersion_v5_cross_stage_producer.outputs['version_step.fullSemVer'] ]
+        pool:
+          vmImage: ubuntu-latest
+        steps:
+          - pwsh: |
+              echo "FullSemVer (myvar_fullSemVer)          : $(myvar_fullSemVer)"
+            displayName: Use mapped job variables (pwsh - outputs without prefix)
+
+          - pwsh: |
+              echo "FullSemVer (env:localvar_fullSemVer)   : $env:localvar_fullSemVer"
+            displayName: Use mapped local env from job variables (pwsh - outputs without prefix)
+            env:
+              localvar_fullSemVer: $(myvar_fullSemVer)
+
+          - bash: |
+              echo "FullSemVer (myvar_fullSemVer)   : $(myvar_fullSemVer)"
+            displayName: Use mapped job variables (bash - outputs without prefix)
+
+          - bash: |
+              echo "FullSemVer (localvar_fullSemVer)   : $localvar_fullSemVer"
+            displayName: Use mapped local env from job variables (bash - outputs without prefix)
+            env:
+              localvar_fullSemVer: $(myvar_fullSemVer)
+  - stage: GitVersion_v5_cross_stage_consumer_with_prefix
+    displayName: GitVersion v5 (cross stage consumer) - with prefix
+    dependsOn: GitVersion_v5_cross_stage
+    condition: and(succeeded(), eq(dependencies.GitVersion_v5_cross_stage.outputs['GitVersion_v5_cross_stage_producer.version_step.GitVersion_BranchName'], 'main')) # use in condition
+    jobs:
+      - job: GitVersion_v5_cross_stage_consumer_with_prefix
+        displayName: GitVersion v5 (cross stage consumer) - with prefix
+        variables:
+          myvar_GitVersion_FullSemVer: $[ stageDependencies.GitVersion_v5_cross_stage.GitVersion_v5_cross_stage_producer.outputs['version_step.GitVersion_FullSemVer'] ]
+        pool:
+          vmImage: ubuntu-latest
+        steps:
+          - pwsh: |
+              echo "FullSemVer (myvar_GitVersion_FullSemVer)          : $(myvar_GitVersion_FullSemVer)"
+            displayName: Use mapped job variables (pwsh - outputs with prefix)
+
+          - pwsh: |
+              echo "FullSemVer (env:localvar_GitVersion_FullSemVer)   : $env:localvar_GitVersion_FullSemVer"
+            displayName: Use mapped local env from job variables (pwsh - outputs with prefix)
+            env:
+              localvar_GitVersion_FullSemVer: $(myvar_GitVersion_FullSemVer)
+
+          - bash: |
+              echo "FullSemVer (localvar_GitVersion_FullSemVer)   : $localvar_GitVersion_FullSemVer"
+            displayName: Use mapped job variables (bash - outputs with prefix)
+
+          - bash: |
+              echo "FullSemVer (localvar_GitVersion_FullSemVer)   : $localvar_GitVersion_FullSemVer"
+            displayName: Use mapped local env from job variables (bash - outputs with prefix)
+            env:
+              localvar_GitVersion_FullSemVer: $(myvar_GitVersion_FullSemVer)

.azure/example-8.yml

@@ -0,0 +1,68 @@
+trigger: none
+
+variables:
+  - name: DOTNET_SKIP_FIRST_TIME_EXPERIENCE
+    value: 'true'
+  - name: DOTNET_CLI_TELEMETRY_OPTOUT
+    value: 'true'
+
+jobs:
+  - job: GitVersion_v5_same_job
+    displayName: GitVersion v5 (same job)
+    pool:
+      vmImage: ubuntu-latest
+    steps:
+      - checkout: self
+        fetchDepth: 0
+
+      - task: gitversion/[email protected]
+        displayName: Install GitVersion
+        inputs:
+          versionSpec: '5.x'
+
+      - task: gitversion/[email protected]
+        displayName: Determine Version
+        name: version_step # step id used as reference for output values
+        inputs:
+          overrideConfig: |
+            update-build-number=false
+
+      - pwsh: |
+          echo "FullSemVer (fullSemVer)            : $(fullSemVer)"
+        displayName: Display GitVersion variables (without prefix)
+
+      - pwsh: |
+          echo "FullSemVer (GitVersion_FullSemVer) : $(GitVersion_FullSemVer)"
+        displayName: Display GitVersion variables (with prefix)
+
+      - pwsh: |
+          echo "FullSemVer (version_step.fullSemVer)            : $(version_step.fullSemVer)"
+        displayName: Display GitVersion outputs (step output without prefix)
+
+      - pwsh: |
+          echo "FullSemVer (version_step.GitVersion_FullSemVer) : $(version_step.GitVersion_FullSemVer)"
+        displayName: Display GitVersion outputs (step output with prefix)
+
+      - pwsh: |
+          echo "FullSemVer (env:myvar_fullSemVer) : $env:myvar_fullSemVer"
+        displayName: Display mapped local env (pwsh - outputs without prefix)
+        env:
+          myvar_fullSemVer: $(version_step.fullSemVer)
+
+      - pwsh: |
+          echo "FullSemVer (env:myvar_GitVersion_FullSemVer) : $env:myvar_GitVersion_FullSemVer"
+        displayName: Display mapped local env (pwsh - outputs with prefix)
+        env:
+          myvar_GitVersion_FullSemVer: $(version_step.GitVersion_FullSemVer)
+
+      - bash: |
+          echo "FullSemVer (myvar_fullSemVer) : $myvar_fullSemVer"
+        displayName: Display mapped local env (bash - outputs without prefix)
+        env:
+          myvar_fullSemVer: $(version_step.fullSemVer)
+
+      - bash: |
+          echo "FullSemVer (myvar_GitVersion_FullSemVer) : $myvar_GitVersion_FullSemVer"
+        displayName: Display mapped local env (bash - outputs with prefix)
+        env:
+          myvar_GitVersion_FullSemVer: $(version_step.GitVersion_FullSemVer)

.azure/example-9.yml

@@ -0,0 +1,86 @@
+trigger: none
+
+variables:
+  - name: DOTNET_SKIP_FIRST_TIME_EXPERIENCE
+    value: 'true'
+  - name: DOTNET_CLI_TELEMETRY_OPTOUT
+    value: 'true'
+
+jobs:
+  - job: GitVersion_v5_cross_job
+    displayName: GitVersion v5 (cross job)
+    pool:
+      vmImage: ubuntu-latest
+    steps:
+      - checkout: self
+        fetchDepth: 0
+
+      - task: gitversion/[email protected]
+        displayName: Install GitVersion
+        inputs:
+          versionSpec: '5.x'
+
+      - task: gitversion/[email protected]
+        displayName: Determine Version
+        name: version_step # step id used as reference for output values
+        inputs:
+          overrideConfig: |
+            update-build-number=false
+
+  - job: GitVersion_v5_cross_job_consumer_without_prefix
+    displayName: GitVersion v5 (cross job consumer) - without prefix
+    dependsOn: GitVersion_v5_cross_job
+    condition: and(succeeded(), eq(dependencies.GitVersion_v5_cross_job.outputs['version_step.branchName'], 'main')) # use in condition
+    variables:
+      myvar_fullSemVer: $[ dependencies.GitVersion_v5_cross_job.outputs['version_step.fullSemVer'] ]
+    pool:
+      vmImage: ubuntu-latest
+    steps:
+      - pwsh: |
+          echo "FullSemVer (myvar_fullSemVer)          : $(myvar_fullSemVer)"
+        displayName: Use mapped job variables (pwsh - outputs without prefix)
+
+      - pwsh: |
+          echo "FullSemVer (env:localvar_fullSemVer)   : $env:localvar_fullSemVer"
+        displayName: Use mapped local env from job variables (pwsh - outputs without prefix)
+        env:
+          localvar_fullSemVer: $(myvar_fullSemVer)
+
+      - bash: |
+          echo "FullSemVer (myvar_fullSemVer)   : $(myvar_fullSemVer)"
+        displayName: Use mapped job variables (bash - outputs without prefix)
+
+      - bash: |
+          echo "FullSemVer (localvar_fullSemVer)   : $localvar_fullSemVer"
+        displayName: Use mapped local env from job variables (bash - outputs without prefix)
+        env:
+          localvar_fullSemVer: $(myvar_fullSemVer)
+
+  - job: GitVersion_v5_cross_job_consumer_with_prefix
+    displayName: GitVersion v5 (cross job consumer) - with prefix
+    dependsOn: GitVersion_v5_cross_job
+    condition: and(succeeded(), eq(dependencies.GitVersion_v5_cross_job.outputs['version_step.GitVersion_BranchName'], 'main')) # use in condition
+    variables:
+      myvar_GitVersion_FullSemVer: $[ dependencies.GitVersion_v5_cross_job.outputs['version_step.GitVersion_FullSemVer'] ]
+    pool:
+      vmImage: ubuntu-latest
+    steps:
+      - pwsh: |
+          echo "FullSemVer (myvar_GitVersion_FullSemVer)          : $(myvar_GitVersion_FullSemVer)"
+        displayName: Use mapped job variables (pwsh - outputs with prefix)
+
+      - pwsh: |
+          echo "FullSemVer (env:localvar_GitVersion_FullSemVer)   : $env:localvar_GitVersion_FullSemVer"
+        displayName: Use mapped local env from job variables (pwsh - outputs with prefix)
+        env:
+          localvar_GitVersion_FullSemVer: $(myvar_GitVersion_FullSemVer)
+
+      - bash: |
+          echo "FullSemVer (myvar_GitVersion_FullSemVer)   : $(myvar_GitVersion_FullSemVer)"
+        displayName: Use mapped job variables (bash - outputs with prefix)
+
+      - bash: |
+          echo "FullSemVer (localvar_GitVersion_FullSemVer)   : $localvar_GitVersion_FullSemVer"
+        displayName: Use mapped local env from job variables (bash - outputs with prefix)
+        env:
+          localvar_GitVersion_FullSemVer: $(myvar_GitVersion_FullSemVer)

.github/workflows/example-8.yml

@@ -0,0 +1,82 @@
+name: example-8
+on:
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: pwsh
+
+jobs:
+  GitVersion_v5_same_job:
+    name: GitVersion v5 (same job)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install GitVersion
+        uses: gittools/actions/gitversion/[email protected]
+        with:
+          versionSpec: '5.x'
+
+      - name: Determine Version
+        id: version_step # step id used as reference for output values
+        uses: gittools/actions/gitversion/[email protected]
+
+      - run: |
+          echo "FullSemVer (env.fullSemVer)            : ${{ env.fullSemVer }}"
+        name: Display GitVersion variables (without prefix)
+
+      - run: |
+          echo "FullSemVer (env.GitVersion_FullSemVer) : ${{ env.GitVersion_FullSemVer }}"
+        name: Display GitVersion variables (with prefix)
+
+      - run: |
+          echo "FullSemVer (steps.version_step.outputs.fullSemVer)            : ${{ steps.version_step.outputs.fullSemVer }}"
+        name: Display GitVersion outputs (step output without prefix)
+
+      - run: |
+          echo "FullSemVer (steps.version_step.outputs.GitVersion_FullSemVer) : ${{ steps.version_step.outputs.GitVersion_FullSemVer }}"
+        name: Display GitVersion outputs (step output with prefix)
+
+      - run: |
+          echo "FullSemVer (env.myvar_fullSemVer)            : ${{ env.myvar_fullSemVer }}"
+        name: Display mapped local env (outputs without prefix)
+        env:
+          myvar_fullSemVer: ${{ steps.version_step.outputs.fullSemVer }}
+
+      - run: |
+          echo "FullSemVer (env.myvar_GitVersion_FullSemVer) : ${{ env.myvar_GitVersion_FullSemVer }}"
+        name: Display mapped local env (outputs with prefix)
+        env:
+          myvar_GitVersion_FullSemVer: ${{ steps.version_step.outputs.GitVersion_FullSemVer }}
+
+      - run: |
+          echo "FullSemVer (env.myvar_fullSemVer)            : $env:myvar_fullSemVer"
+        name: Display mapped local env (pwsh - outputs without prefix)
+        shell: pwsh
+        env:
+          myvar_fullSemVer: ${{ steps.version_step.outputs.fullSemVer }}
+
+      - run: |
+          echo "FullSemVer (env.myvar_GitVersion_FullSemVer) : $env:myvar_GitVersion_FullSemVer"
+        name: Display mapped local env (pwsh - outputs with prefix)
+        shell: pwsh
+        env:
+          myvar_GitVersion_FullSemVer: ${{ steps.version_step.outputs.GitVersion_FullSemVer }}
+
+      - run: |
+          echo "FullSemVer (myvar_fullSemVer)            : $myvar_fullSemVer"
+        name: Display mapped local env (bash - outputs without prefix)
+        shell: bash
+        env:
+          myvar_fullSemVer: ${{ steps.version_step.outputs.fullSemVer }}
+
+      - run: |
+          echo "FullSemVer (myvar_GitVersion_FullSemVer) : $myvar_GitVersion_FullSemVer"
+        name: Display mapped local env (bash - outputs with prefix)
+        shell: bash
+        env:
+          myvar_GitVersion_FullSemVer: ${{ steps.version_step.outputs.GitVersion_FullSemVer }}