Skip to content

Commit

Permalink
GitTools#1053 - split execution with different inputs examples from o…
Browse files Browse the repository at this point in the history
…utput examples
  • Loading branch information
arturcic committed Mar 11, 2024
1 parent 8fc305d commit c92ade5
Show file tree
Hide file tree
Showing 2 changed files with 41 additions and 38 deletions.
40 changes: 21 additions & 19 deletions docs/examples/azure/gitversion/execute/usage-examples.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,25 @@
# Execute GitVersion Task (gitversion/execute) Usage Examples
# Execute GitVersion Task (gitversion/execute) usage Examples

Find out how to use the **gitversion/execute** task using the examples below.

> The examples use the latest _0.x_ version of the GitVersion Execute task. It is recommended to use the latest released version in your own pipelines.
Note that if the pipeline is setup to use a shallow git fetch mode the GitVersion Execute task will fail. It is required to use `fetchDepth: 0`.
You must also run the GitVersion Setup step before the Execute step:

```yaml
- checkout: self
fetchDepth: 0
steps:
- checkout: self
fetchDepth: 0

- task: gitversion/setup@0.13.4
displayName: Install GitVersion
inputs:
versionSpec: '5.x'
- task: gitversion/setup@0.13.4
displayName: Install GitVersion
inputs:
versionSpec: '5.x'
```
These steps are omitted from the examples for brevity.
> The examples use version _0.13.4_ of the GitVersion Execute task. It is recommended to use the latest released version in your own workflows.
## Inputs
The Execute GitVersion task accepts the following inputs:
Expand Down Expand Up @@ -101,18 +102,9 @@ The Execute GitVersion task creates the following job-scoped variables and multi
- commitsSinceVersionSourcePadded (since 5.2.0, removed in 6.0.0)
- uncommittedChanges (since 5.5.0)
- commitDate
The outputs can be accessed using the syntax `$(<id>.<outputName>)` or `$(<id>.GitVersion_<OutputName>)`, where `<id>` is the ID assigned to the step that calls the action, by subsequent steps later in the same job. See example [5](#example-5).

The action also creates environment variables of the form `$(<outputName>)` or `$(GitVersion_<OutputName>)` for use by other steps in the same job. See example [6](#example-6).

The multi-job output variables can be accessed across jobs and stages, in both conditions and variables. See examples [7](#example-7) to [10](#example-10).

**GitVersion also automatically updates the pre-defined Build variable `Build.BuildNumber`.**

---
## Examples
## Execution Examples
### Example 1
Expand Down Expand Up @@ -225,6 +217,16 @@ steps:
next-version=1.0.0
```
## Output usage
The outputs can be accessed using the syntax `$(<id>.<outputName>)` or `$(<id>.GitVersion_<OutputName>)`, where `<id>` is the ID assigned to the step that calls the action, by subsequent steps later in the same job. See example [5](#example-5).

The action also creates environment variables of the form `$(<outputName>)` or `$(GitVersion_<OutputName>)` for use by other steps in the same job. See example [6](#example-6).

The multi-job output variables can be accessed across jobs and stages, in both conditions and variables. See examples [7](#example-7) to [10](#example-10).

**GitVersion also automatically updates the pre-defined Build variable `Build.BuildNumber`.**

### Example 8

Calculate the version for the build and display all the calculated variables in the next step.
Expand Down
39 changes: 20 additions & 19 deletions docs/examples/github/gitversion/execute/usage-examples.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Execute GitVersion Action (gitversion/execute) Usage Examples
# Execute GitVersion Action (gitversion/execute) usage Examples

Find out how to use the **gitversion/execute** action using the examples below.

For the GitVersion workflow to execute successfully, you must checkout your Git repository with `fetch-depth: 0` to fetch all history for all tags and branches.
Note that if the pipeline is setup to use a shallow git fetch mode the GitVersion Execute action will fail. It is required to use `fetch-depth: 0`.
You must also run the GitVersion Setup step before the Execute step:

```yaml
Expand All @@ -12,7 +12,7 @@ steps:
with:
fetch-depth: 0

- task: gitversion/setup@v0.13.4
- task: gittools/actions/gitversion/setup@v0.13.4
displayName: Install GitVersion
inputs:
versionSpec: '5.x'
Expand Down Expand Up @@ -104,24 +104,17 @@ The Execute GitVersion action creates the following outputs:
- commitsSinceVersionSourcePadded (since 5.2.0, removed in 6.0.0)
- uncommittedChanges (since 5.5.0)
- commitDate
The outputs can be accessed using the syntax `${{ steps.<id>.outputs.<outputName> }}` or `${{ steps.<id>.outputs.GitVersion_<OutputName> }}`, where `<id>` is the ID assigned to the step that calls the action, by subsequent steps later in the same job. See example [5](#example-5).

The action also creates environment variables of the form `${{ env.<outputName> }}` or `${{ env.GitVersion_<OutputName> }}` for use by other steps in the same job. See example [6](#example-6).

The outputs can be accessed across jobs by mapping them to job outputs and referencing the job outputs using the `needs` context in dependent jobs. See examples [7](#example-7) and [8](#example-8).

---
## Examples
## Execution Examples
### Example 1
Calculate the version for the build.
```yaml
steps:
# gitversion/setup@v0.13.4 action omitted for brevity.
# gittools/actions/gitversion/setup@v0.13.4 action omitted for brevity.

- name: Determine Version
uses: gittools/actions/gitversion/execute@v0.13.4
Expand Down Expand Up @@ -156,7 +149,7 @@ Calculate the version for the build using a config file named **VersionConfig.ym
```yaml
steps:
# gitversion/setup@v0.13.4 action omitted for brevity.
# gittools/actions/gitversion/setup@v0.13.4 action omitted for brevity.

- name: Determine Version
uses: gittools/actions/gitversion/execute@v0.13.4
Expand All @@ -171,7 +164,7 @@ Show the effective configuration for GitVersion by running the **/showConfig** c
```yaml
steps:
# gitversion/setup@v0.13.4 action omitted for brevity.
# gittools/actions/gitversion/setup@v0.13.4 action omitted for brevity.

- name: Display GitVersion config
uses: gittools/actions/gitversion/execute@v0.13.4
Expand All @@ -186,7 +179,7 @@ Calculate the version for the build. Disabling the cache and normalization.
```yaml
steps:
# gitversion/setup@v0.13.4 action omitted for brevity.
# gittools/actions/gitversion/setup@v0.13.4 action omitted for brevity.

- name: Determine Version
uses: gittools/actions/gitversion/execute@v0.13.4
Expand All @@ -201,7 +194,7 @@ Calculate the version for the build. Update the version in the AssemblyInfo file
```yaml
steps:
# gitversion/setup@v0.13.4 action omitted for brevity.
# gittools/actions/gitversion/setup@v0.13.4 action omitted for brevity.

- name: Determine Version
uses: gittools/actions/gitversion/execute@v0.13.4
Expand All @@ -215,7 +208,7 @@ Calculate the version for the build. Override the configuration file with the sp
```yaml
steps:
# gitversion/setup@v0.13.4 action omitted for brevity.
# gittools/actions/gitversion/setup@v0.13.4 action omitted for brevity.

- name: Determine Version
uses: gittools/actions/gitversion/execute@v0.13.4
Expand All @@ -225,13 +218,21 @@ steps:
next-version=1.0.0
```
## Output usage
The outputs can be accessed using the syntax `${{ steps.<id>.outputs.<outputName> }}` or `${{ steps.<id>.outputs.GitVersion_<OutputName> }}`, where `<id>` is the ID assigned to the step that calls the action, by subsequent steps later in the same job. See example [5](#example-5).

The action also creates environment variables of the form `${{ env.<outputName> }}` or `${{ env.GitVersion_<OutputName> }}` for use by other steps in the same job. See example [6](#example-6).

The outputs can be accessed across jobs by mapping them to job outputs and referencing the job outputs using the `needs` context in dependent jobs. See examples [7](#example-7) and [8](#example-8).

### Example 8

Calculate the version for the build and display all the calculated variables in the next step.

```yaml
steps:
# gitversion/setup@v0.13.4 action omitted for brevity.
# gittools/actions/gitversion/setup@v0.13.4 action omitted for brevity.
- name: Determine Version
id: gitversion # id to later be referenced
Expand Down Expand Up @@ -314,7 +315,7 @@ Calculate the version for the build and display the value of the `env.GitVersion

```yaml
steps:
# gitversion/setup@v0.13.4 action omitted for brevity.
# gittools/actions/gitversion/setup@v0.13.4 action omitted for brevity.
- name: Determine Version
uses: gittools/actions/gitversion/execute@v0.13.4
Expand Down

0 comments on commit c92ade5

Please sign in to comment.