Merge pull request #4096 from arturcic/feat/4078

#4078 - update dockerhub README info

Author: arturcic

build/common/Utilities/DockerContextExtensions.cs

@@ -202,7 +202,7 @@ private static IEnumerable<string> GetDockerTags(this BuildContextBase context,
         var distro = dockerImage.Distro;
         var targetFramework = dockerImage.TargetFramework;
 
-        if (context.Version == null) return Enumerable.Empty<string>();
+        if (context.Version == null) return [];
         var tags = new List<string>
         {
             $"{name}:{context.Version.Version}-{distro}-{targetFramework}",
@@ -211,12 +211,13 @@ private static IEnumerable<string> GetDockerTags(this BuildContextBase context,
 
         if (distro == Constants.DockerDistroLatest && targetFramework == Constants.VersionLatest)
         {
-            tags.AddRange(new[] { $"{name}:{context.Version.Version}", $"{name}:{context.Version.SemVersion}", });
+            tags.Add($"{name}:{context.Version.SemVersion}");
 
             if (context.IsStableRelease)
             {
                 tags.AddRange(
                 [
+                    $"{name}:{context.Version.Version}",
                     $"{name}:latest",
                     $"{name}:latest-{targetFramework}",
                     $"{name}:latest-{distro}",

build/common/Utilities/Models.cs

@@ -40,7 +40,7 @@ public static BuildVersion Calculate(GitVersion gitVersion)
             nugetVersion += $".{gitVersion.BuildMetaData}";
         }
 
-        return new BuildVersion(
+        return new(
             GitVersion: gitVersion,
             Version: version,
             Milestone: semVersion,

build/docker/Tasks/DockerHubReadmePublish.cs

@@ -55,6 +55,7 @@ private static string GetReadmeContent(BuildContextBase context)
         // language=markdown
         var readme = $"""
 # GitVersion
+
 ![GitVersion – From git log to SemVer in no time][banner]
 
 Versioning when using Git, solved. GitVersion looks at your git history and works out the [Semantic Version][semver] of the commit being built.
@@ -63,18 +64,35 @@ private static string GetReadmeContent(BuildContextBase context)
 
 ## Usage
 
-The recommended image to run is `alpine`, as they are the smallest Docker images we provide (83 MB). This will execute GitVersion for the current working directory (`$(pwd)`) on Linux and Unix or powershell on Windows:
+The recommended image to run is `alpine`, as they are the smallest Docker images we provide. This will execute GitVersion for the current working directory (`$(pwd)`) on Linux and Unix or powershell on Windows:
 
 ```sh
 docker run --rm -v "$(pwd):/repo" gittools/gitversion:{tag} /repo
 ```
+
 The following command will execute GitVersion for the current working directory (`%CD%`) on Windows with CMD:
 
 ```sh
 docker run --rm -v "%CD%:/repo" gittools/gitversion:{tag} /repo
 ```
+
 Note that the path `/repo` needs to be passed as an argument since the `gitversion` executable within the container is not aware of the fact that it's running inside a container.
 
+### CI Agents
+
+If you are running GitVersion on a CI agent, you may need to specify environment variables to allow GitVersion to work correctly.
+For example, on Azure DevOps you may need to set the following environment variables:
+
+```sh
+docker run --rm -v "$(pwd):/repo" --env TF_BUILD=true --env BUILD_SOURCEBRANCH=$(Build.SourceBranch) gittools/gitversion:{tag} /repo
+```
+
+On GitHub Actions, you may need to set the following environment variables:
+
+```sh
+docker run --rm -v "$(pwd):/repo" --env GITHUB_ACTIONS=true --env GITHUB_REF=$(GITHUB_REF) gittools/gitversion:{tag} /repo
+```
+
 ### Tags
 
 Most of the tags we provide have both arm64 and amd64 variants. If you need to pull a architecture specific tag you can do that like:

docs/input/docs/usage/docker.md

@@ -5,22 +5,45 @@ Description: |
     Use GitVersion through one of its many published Docker containers.
 ---
 
-GitVersion can be used through one of its many published Docker
-containers. The list of available containers can be found on
-[Docker Hub][docker-hub]. Once you've found the image you want to use,
-you can run it like this:
+The recommended image to run is `alpine`, as they are the smallest Docker images we provide. This will execute GitVersion for the current working directory (`$(pwd)`) on Linux and Unix or powershell on Windows:
 
-```shell
-docker run --rm --volume "$(pwd):/repo" gittools/gitversion:6.0.0-fedora.36-6.0 /repo
+```sh
+docker run --rm -v "$(pwd):/repo" gittools/gitversion:{tag} /repo
 ```
 
-The above command will run GitVersion with the current directory
-mapped to `/repo` inside the container (the `--volume "$(pwd):/repo"`
-part). The `/repo` directory is then passed in as the argument
-GitVersion should use to calculate the version.
+The following command will execute GitVersion for the current working directory (`%CD%`) on Windows with CMD:
 
-The `--rm` flag will remove the container after it has finished
-running.
+```sh
+docker run --rm -v "%CD%:/repo" gittools/gitversion:{tag} /repo
+```
+
+Note that the path `/repo` needs to be passed as an argument since the `gitversion` executable within the container is not aware of the fact that it's running inside a container.
+
+### CI Agents
+
+If you are running GitVersion on a CI agent, you may need to specify environment variables to allow GitVersion to work correctly.
+For example, on Azure DevOps you may need to set the following environment variables:
+
+```sh
+docker run --rm -v "$(pwd):/repo" --env TF_BUILD=true --env BUILD_SOURCEBRANCH=$(Build.SourceBranch) gittools/gitversion:{tag} /repo
+```
+
+On GitHub Actions, you may need to set the following environment variables:
+
+```sh
+docker run --rm -v "$(pwd):/repo" --env GITHUB_ACTIONS=true --env GITHUB_REF=$(GITHUB_REF) gittools/gitversion:{tag} /repo
+```
+
+### Tags
+
+Most of the tags we provide have both arm64 and amd64 variants. If you need to pull a architecture specific tag you can do that like:
+
+```sh
+docker run --rm -v "$(pwd):/repo" gittools/gitversion:{tag}-amd64 /repo
+docker run --rm -v "$(pwd):/repo" gittools/gitversion:{tag}-arm64 /repo
+```
+
+The list of available containers can be found on [Docker Hub][docker-hub].
 
 [Explore GitVersion on Docker Hub][docker-hub]{.btn .btn-primary}