added gitversion/command

.azure/ci.yml

@@ -71,6 +71,24 @@ jobs:
         node gitversion/setup/main.mjs
       displayName: gitversion/setup
       workingDirectory: dist/vsix
+    - pwsh: |
+        # set the inputs for the 'gitversion/command' action
+        $env:INPUT_TARGETPATH = './'
+        $env:INPUT_ARGUMENTS = '/showvariable FullSemVer'
+
+        # run the 'gitversion/command' action
+        node gitversion/command/main.mjs
+      displayName: gitversion/command (showvariable)
+      workingDirectory: dist/vsix
+    - pwsh: |
+        # set the inputs for the 'gitversion/command' action
+        $env:INPUT_TARGETPATH = './'
+        $env:INPUT_ARGUMENTS = '/format {Major}.{Minor}'
+
+        # run the 'gitversion/command' action
+        node gitversion/command/main.mjs
+      displayName: gitversion/command (format)
+      workingDirectory: dist/vsix
     - pwsh: |
         # set the inputs for the 'gitversion/execute' action
         $env:INPUT_TARGETPATH = './'

.github/workflows/ci.yml

@@ -54,6 +54,14 @@ jobs:
       uses: ./gitversion/setup
       with:
         versionSpec: '6.x'
+    - name: gitversion/command (showvariable)
+      uses: ./gitversion/command
+      with:
+        arguments: '/showvariable FullSemVer'
+    - name: gitversion/command (format)
+      uses: ./gitversion/command
+      with:
+        arguments: '/format {Major}.{Minor}'
     - name: gitversion/execute
       id: gitversion # step id used as reference for output values
       uses: ./gitversion/execute

dist/azure/gitversion/command/main.mjs

@@ -0,0 +1,2 @@
+import { run } from './tools/lib.mjs'
+await run('azure', 'gitversion', 'command')

dist/azure/gitversion/command/task.json

@@ -0,0 +1,51 @@
+{
+  "id": "41dc3dd2-6a51-4ba5-a889-824274acca8b",
+  "name": "gitversion/command",
+  "friendlyName": "Command GitVersion Task",
+  "description": "Easy Semantic Versioning (https://semver.org) for projects using Git",
+  "author": "GitTools Contributors",
+  "helpMarkDown": "See the [documentation](https://gitversion.net/docs/) for help",
+  "category": "Build",
+  "demands": [],
+  "version": {
+    "Major": 0,
+    "Minor": 0,
+    "Patch": 1
+  },
+  "minimumAgentVersion": "3.224.0",
+  "execution": {
+    "Node20_1": {
+      "target": "main.mjs",
+      "argumentFormat": "",
+      "workingDirectory": "."
+    }
+  },
+  "instanceNameFormat": "gitversion/command",
+  "inputs": [
+    {
+      "name": "targetPath",
+      "type": "string",
+      "label": "Working directory path",
+      "defaultValue": "",
+      "required": false,
+      "helpMarkDown": "Optionally supply the path to the working directory",
+      "groupName": "gitversionDetails"
+    },
+    {
+      "name": "disableShallowCloneCheck",
+      "type": "boolean",
+      "label": "Disable Shallow Clone Check",
+      "defaultValue": "false",
+      "required": false,
+      "helpMarkDown": "Whether to disable GitVersion shallow clone check"
+    },
+    {
+      "name": "arguments",
+      "type": "string",
+      "label": "GitVersion arguments",
+      "defaultValue": "",
+      "required": true,
+      "helpMarkDown": "Arguments to send to GitVersion"
+    }
+  ]
+}

dist/azure/manifest.config.cjs

@@ -5,7 +5,8 @@ module.exports = (env) => {
 
     const gitversion = [
         { id: 'setup', path: 'gitversion/setup' },
-        { id: 'execute', path: 'gitversion/execute' }
+        { id: 'execute', path: 'gitversion/execute' },
+        { id: 'command', path: 'gitversion/command' }
     ]
 
     const gitreleasemanager = [

dist/azure/tasks.json

@@ -7,6 +7,10 @@
     "execute": {
       "test": "9b58ed30-0deb-4083-b007-5f6ce7787544",
       "prod": "9013cf7f-ee8d-49f4-a39b-db244928d391"
+    },
+    "command": {
+      "test": "b5559270-0af3-49c8-bde3-c44847a8503b",
+      "prod": "41dc3dd2-6a51-4ba5-a889-824274acca8b"
     }
   },
   "gitreleasemanager": {

docs/examples/azure/gitversion/command.md

@@ -0,0 +1,95 @@
+# Command GitVersion Task (gitversion/command) usage Examples
+
+Find out how to use the **gitversion/command** task using the examples below.
+
+Note that if the pipeline is set up to use a shallow git fetch mode the GitVersion Command task will fail. It is required to use `fetchDepth: 0`.
+You must also run the GitVersion Setup step before the Command step:
+
+```yaml
+steps:
+  - checkout: self
+    fetchDepth: 0
+
+  - task: gitversion/setup@2.0.1
+    displayName: Install GitVersion
+    inputs:
+      versionSpec: '6.x'
+```
+
+These steps are omitted from the examples for brevity.
+
+> The examples use version _2.0.1_ of the GitVersion Command task.  It is recommended to use the latest released version in your own workflows.
+
+## Inputs
+
+The Command GitVersion task accepts the following inputs:
+
+```yaml
+targetPath:
+  description: Optionally supply the path to the working directory
+  required: false
+  default: ''
+disableShallowCloneCheck:
+  description: Whether to disable the check for shallow clone
+  required: false
+  default: 'false'
+arguments:
+  description: Arguments to send to GitVersion
+  required: true
+  default: ''
+```
+
+---
+
+## Execution Examples
+
+### Example 1
+
+<details>
+  <summary>Show the effective configuration for GitVersion by running the <b>/showConfig</b> command.</summary>
+
+```yaml
+steps:
+  # gitversion/setup@2.0.1 task omitted for brevity.
+
+  - task: gitversion/command@2.0.1
+    displayName: Display GitVersion config
+    inputs:
+      arguments: '/showConfig'
+```
+
+</details>
+
+### Example 2
+
+<details>
+  <summary>Outputs the <i>FullSemVer</i> variable by running the <b>/showvariable FullSemVer</b> command.</summary>
+
+```yaml
+steps:
+  # gitversion/setup@2.0.1 task omitted for brevity.
+
+  - task: gitversion/command@2.0.1
+    displayName: Output the FullSemVer variable
+    inputs:
+      arguments: '/showvariable FullSemVer'
+```
+
+</details>
+
+### Example 3
+
+<details>
+  <summary>Outputs the formatted version by running the <b>/format {Major}.{Minor}</b> command.</summary>
+
+```yaml
+steps:
+  # gitversion/setup@2.0.1 task omitted for brevity.
+
+  - task: gitversion/command@2.0.1
+    displayName: Output the formatted version
+    inputs:
+      arguments: '/format {Major}.{Minor}' # any Output Variable can be used here
+```
+
+</details>

docs/examples/azure/gitversion/index.md

@@ -11,3 +11,7 @@ Note: You need to run the Setup step before the Execute step, otherwise the Exec
 ## Execute GitVersion (gitversion/execute)
 
 - [Execute](execute.md)
+
+## Execute GitVersion (gitversion/command)
+
+- [Command](command.md)

docs/examples/github/gitversion/command.md

@@ -0,0 +1,98 @@
+# Command GitVersion Action (gitversion/command) usage Examples
+
+Find out how to use the **gitversion/command** action using the examples below.
+
+Note that if the pipeline is set up to use a shallow git fetch mode the GitVersion Command action will fail. It is required to use `fetch-depth: 0`.
+You must also run the GitVersion Setup step before the Command step:
+
+```yaml
+steps:
+  - name: Checkout
+    uses: actions/checkout@v4
+    with:
+      fetch-depth: 0
+
+  - name: Install GitVersion
+    uses: gittools/actions/gitversion/setup@v2.0.1
+    with:
+      versionSpec: '6.x'
+```
+
+These steps are omitted from the examples for brevity.
+
+> The examples use version _2.0.1_ of the GitVersion Command action.  It is recommended to use the latest released version in your own workflows.
+
+## Inputs
+
+The Command GitVersion action accepts the following inputs:
+
+```yaml
+targetPath:
+  description: Optionally supply the path to the working directory
+  required: false
+  default: ''
+disableShallowCloneCheck:
+  description: Whether to disable the check for shallow clone
+  required: false
+  default: 'false'
+arguments:
+  description: Arguments to send to GitVersion
+  required: true
+  default: ''
+```
+
+---
+
+## Execution Examples
+
+### Example 1
+
+<details>
+  <summary>Show the effective configuration for GitVersion by running the <b>/showConfig</b> command.</summary>
+
+```yaml
+steps:
+  # gittools/actions/gitversion/setup@v2.0.1 action omitted for brevity.
+
+  - name: Display GitVersion config
+    uses: gittools/actions/gitversion/command@v2.0.1
+    with:
+      useConfigFile: true
+      arguments: '/showConfig'
+```
+
+</details>
+
+### Example 2
+
+<details>
+  <summary>Outputs the <i>FullSemVer</i> variable by running the <b>/showvariable FullSemVer</b> command.</summary>
+
+```yaml
+steps:
+  # gittools/actions/gitversion/setup@v2.0.1 action omitted for brevity.
+
+  - name: Output the FullSemVer variable
+    uses: gittools/actions/gitversion/command@v2.0.1
+    with:
+      arguments: '/showvariable FullSemVer'
+```
+
+</details>
+
+### Example 3
+
+<details>
+  <summary>Outputs the formatted version by running the <b>/format {Major}.{Minor}</b> command.</summary>
+
+```yaml
+steps:
+  # gittools/actions/gitversion/setup@v2.0.1 action omitted for brevity.
+
+  - name: Output the formatted version
+    uses: gittools/actions/gitversion/command@v2.0.1
+    with:
+      arguments: '/format {Major}.{Minor}' # any Output Variable can be used here
+```
+
+</details>

docs/examples/github/gitversion/index.md

@@ -11,3 +11,7 @@ Note: You need to run the Setup step before the Execute step, otherwise the Exec
 ## Execute GitVersion (gitversion/execute)
 
 - [Execute](execute.md)
+
+## Execute GitVersion (gitversion/command)
+
+- [Command](command.md)

envs/gitversion/command/azure.env

@@ -0,0 +1,4 @@
+BUILD_SOURCESDIRECTORY=.
+AGENT_TEMPDIRECTORY=./.test/temp
+AGENT_TOOLSDIRECTORY=./.test/tools
+GITVERSION_PATH=./.test/tools/GitVersion.Tool/6.0.0

envs/gitversion/command/github.env

@@ -0,0 +1,4 @@
+GITHUB_WORKSPACE=.
+RUNNER_TEMP=./.test/temp
+RUNNER_TOOL_CACHE=./.test/tools
+GITVERSION_PATH=./.test/tools/GitVersion.Tool/6.0.0

envs/gitversion/command/local.env

@@ -0,0 +1,4 @@
+AGENT_SOURCE_DIR=.
+AGENT_TEMP_DIR=./.test/temp
+AGENT_TOOLS_DIR=./.test/tools
+GITVERSION_PATH=./.test/tools/GitVersion.Tool/6.0.0

gitversion/command/action.yml

@@ -0,0 +1,22 @@
+name: gitversion-command
+description: GitHub Action for Easy Semantic Versioning with GitVersion. Run GitVersion with arguments.
+author: GitTools
+branding:
+  color: gray-dark
+  icon: git-pull-request
+runs:
+  using: node20
+  main: main.mjs
+inputs:
+  targetPath:
+    description: Optionally supply the path to the working directory
+    required: false
+    default: ''
+  disableShallowCloneCheck:
+    description: Whether to disable the check for shallow clone
+    required: false
+    default: 'false'
+  arguments:
+    description: Arguments to send to GitVersion
+    required: true
+    default: ''

gitversion/command/main.mjs

@@ -0,0 +1,2 @@
+import { run } from '../../dist/tools/lib.mjs'
+await run('github', 'gitversion', 'command')