Renamed to cli version.

Sources/CliVersion/Documentation.docc/Articles/GettingStarted.md

@@ -0,0 +1,69 @@
+# Getting Started
+
+Learn how to integrate the plugins into your project
+
+## Overview
+
+Use the plugins by including as a package to your project and declaring in the `plugins` section of
+your target.
+
+> Note: You must use swift-tools version 5.6 or greater for package plugins and
+> target `macOS(.v10_15)` or greater.
+
+```swift
+// swift-tools-version: 5.7
+
+import PackageDescription
+
+let package = Package(
+  platforms:[.macOS(.v10_15)],
+  dependencies: [
+    ...,
+    .package(url: "https://github.com/m-housh/swift-cli-version.git", from: "0.1.0")
+  ],
+  targets: [
+    .executableTarget(
+      name: "<target name>",
+      dependencies: [...],
+      plugins: [ 
+        .plugin(name: "BuildWithVersionPlugin", package: "swift-cli-version")
+      ]
+    )
+  ]
+)
+```
+
+The above example uses the build tool plugin.  The `BuildWithVersionPlugin` will give you access
+to a `VERSION` variable in your project that you can use to supply the version of the tool.
+
+### Example
+
+```swift
+import ArgumentParser
+
+@main
+struct MyCliTool: ParsableCommand { 
+  static let configuration = CommandConfiguration(
+    abstract: "My awesome cli tool",
+    version: VERSION
+  )
+
+  func run() throws { 
+    print("Version: \(VERSION)")
+  }
+}
+```
+
+After you enable the plugin, you will have access to the `VERSION` string variable even though it is 
+not declared in your source files.
+
+![Trust & Enable](trust)
+
+> Note: If your `DerivedData` folder lives in a directory that is a mounted volume / or somewhere
+> that is not under your home folder then you may get build failures using the build tool
+> plugin, it will work if you build from the command line and pass the `--disable-sandbox` flag to the
+> build command or use one of the manual methods.
+
+## See Also
+
+<doc:ManualPlugins>

Sources/CliVersion/Documentation.docc/Articles/ManualPlugins.md

@@ -0,0 +1,68 @@
+# Manual Plugins
+
+There are two plugins that are included that can be ran manually, if the build tool plugin does not fit
+your use case.
+
+## Generate Version
+
+The `generate-version` plugin will create a `Version.swift` file in the given target.  You can
+run it by running the following command.
+
+```bash
+swift package --disable-sandbox \
+  --allow-writing-to-package-directory \
+  generate-version \
+  <target>
+```
+
+> Note: If using the manual version then the `VERSION` variable is an optional string that will be
+> `nil`, allowing you to run the `update-version` command in your build pipeline.
+
+## Update Version
+
+The `update-version` plugin can be ran in your build pipeline process to set the version prior to
+building for distribution.
+
+```bash
+swift package --disable-sandbox \
+  --allow-writing-to-package-directory \
+  update-version \
+  <target>
+```
+
+## Options
+
+Both manual versions also allow the following options to customize the operation, the
+options need to come after the plugin name.
+
+| Option | Description |
+| ------ | ----------- |
+| --dry-run | Do not write to any files, but describe where values would be written |
+| --filename | Override the file name to be written in the target directory |
+| --verbose | Increase the logging output |
+
+### Example with options
+```bash
+swift package \
+  --allow-writing-to-package-directory \
+  generate-version \
+  --dry-run \
+  --verbose \
+  <target>
+```
+
+## View the Executable Options
+
+You can also run the following command to view the options in your terminal
+
+```bash
+swift run cli-version --help
+```
+
+Or
+
+```bash
+swift run cli-version <verb> --help
+```
+
+Where `verb` is one of, `build`, `generate`, or `update`.

Sources/CliVersion/Documentation.docc/CliVersion.md

@@ -0,0 +1,23 @@
+# ``CliVersion``
+
+Derive a version for a command line tool from git tags or a git sha.
+
+## Additional Resources
+
+[Github Repo](https://github.com/m-housh/swift-cli-version)
+
+## Overview
+
+This tool exposes several plugins that can be used to derive a version for a command line program at
+build time or by manually running the plugin.  The version is derived from git tags and falling back to 
+the branch and git sha if a tag is not set for the current worktree state.
+
+## Articles
+
+- <doc:GettingStarted>
+- <doc:ManualPlugins>
+
+## Api
+
+- ``FileClient``
+- ``GitVersionClient``

Sources/CliVersion/FileClient.swift

@@ -0,0 +1,97 @@
+import Dependencies
+import Foundation
+#if canImport(FoundationNetworking)
+  import FoundationNetworking
+#endif
+import XCTestDynamicOverlay
+
+/// Represents the interactions with the file system.  It is able
+/// to read from and write to files.
+///
+/// ```swift
+///  @Dependency(\.fileClient) var fileClient
+/// ```
+///
+public struct FileClient {
+
+  /// Write `Data` to a file `URL`.
+  public private(set) var write: (Data, URL) throws -> Void
+
+  /// Create a new ``GitVersion/FileClient`` instance.
+  ///
+  /// This is generally not interacted with directly, instead access as a dependency.
+  ///
+  ///```swift
+  /// @Dependency(\.fileClient) var fileClient
+  ///```
+  ///
+  /// - Parameters:
+  ///   - write: Write the data to a file.
+  public init(
+    write: @escaping (Data, URL) throws -> Void
+  ) {
+    self.write = write
+  }
+
+  /// Write's the the string to a  file path.
+  ///
+  /// - Parameters:
+  ///   - string: The string to write to the file.
+  ///   - path: The file path.
+  public func write(string: String, to path: String) throws {
+    let url = try url(for: path)
+    try self.write(string: string, to: url)
+  }
+
+  /// Write's the the string to a  file path.
+  ///
+  /// - Parameters:
+  ///   - string: The string to write to the file.
+  ///   - url: The file url.
+  public func write(string: String, to url: URL) throws {
+    try self.write(Data(string.utf8), url)
+  }
+}
+
+extension FileClient: DependencyKey {
+
+  /// A ``FileClient`` that does not do anything.
+  public static let noop = FileClient.init(
+    write: { _, _ in }
+  )
+
+  /// An `unimplemented` ``FileClient``.
+  public static let testValue = FileClient(
+    write: unimplemented("\(Self.self).write")
+  )
+
+  /// The live ``FileClient``
+  public static let liveValue = FileClient(
+    write: { try $0.write(to: $1, options: .atomic) }
+  )
+
+}
+
+extension DependencyValues {
+
+  /// Access a basic ``FileClient`` that can read / write data to the file system.
+  ///
+  public var fileClient: FileClient {
+    get { self[FileClient.self] }
+    set { self[FileClient.self] = newValue }
+  }
+}
+
+// MARK: - Private
+fileprivate func url(for path: String) throws -> URL {
+  #if os(Linux)
+    return URL(fileURLWithPath: path)
+  #else
+    if #available(macOS 13.0, *) {
+      return URL(filePath: path)
+    } else {
+      // Fallback on earlier versions
+      return URL(fileURLWithPath: path)
+    }
+  #endif
+}

Sources/CliVersion/GitVersionClient.swift

@@ -0,0 +1,164 @@
+import Foundation
+#if canImport(FoundationNetworking)
+  import FoundationNetworking
+#endif
+import ShellClient
+import XCTestDynamicOverlay
+
+/// A client that can retrieve the current version from a git directory.
+/// It will use the current `tag`, or if the current git tree does not
+/// point to a commit that is tagged, it will use the `branch git-sha` as
+/// the version.
+///
+/// This is often not used directly, instead it is used with one of the plugins
+/// that is supplied with this library.  The use case is to set the version of a command line
+/// tool based on the current git tag.
+///
+public struct GitVersionClient {
+
+  /// The closure to run that returns the current version from a given
+  /// git directory.
+  private var currentVersion: (String?) throws -> String
+
+  /// Create a new ``GitVersionClient`` instance.
+  ///
+  /// This is normally not interacted with directly, instead access the client through the dependency system.
+  /// ```swift
+  /// @Dependency(\.gitVersionClient)
+  /// ```
+  ///
+  /// - Parameters:
+  ///   - currentVersion: The closure that returns the current version.
+  ///
+  public init(currentVersion: @escaping (String?) throws -> String) {
+    self.currentVersion = currentVersion
+  }
+
+  /// Get the current version from the `git tag` in the given directory.
+  /// If a directory is not passed in, then we will use the current working directory.
+  ///
+  /// - Parameters:
+  ///   - gitDirectory: The directory to run the command in.
+  public func currentVersion(in gitDirectory: String? = nil) throws -> String {
+    try self.currentVersion(gitDirectory)
+  }
+
+  /// Override the `currentVersion` command and return the passed in version string.
+  ///
+  /// This is useful for testing purposes.
+  ///
+  /// - Parameters:
+  ///   - version: The version string to return when `currentVersion` is called.
+  public mutating func override(with version: String) {
+    self.currentVersion = { _ in version }
+  }
+}
+
+extension GitVersionClient: TestDependencyKey {
+
+  /// The ``GitVersionClient`` used in test / debug builds.
+  public static let testValue = GitVersionClient(
+    currentVersion: unimplemented("\(Self.self).currentVersion", placeholder: "")
+  )
+
+  /// The ``GitVersionClient`` used in release builds.
+  public static var liveValue: GitVersionClient {
+    .init(currentVersion: { gitDirectory in
+      try GitVersion(workingDirectory: gitDirectory).currentVersion()
+    })
+  }
+}
+
+extension DependencyValues {
+
+  /// A ``GitVersionClient`` that can retrieve the current version from a
+  /// git directory.
+  public var gitVersionClient: GitVersionClient {
+    get { self[GitVersionClient.self] }
+    set { self[GitVersionClient.self] = newValue }
+  }
+}
+
+extension ShellCommand {
+  public static func gitCurrentSha(gitDirectory: String? = nil) -> Self {
+    GitVersion(workingDirectory: gitDirectory).command(for: .commit)
+  }
+
+  public static func gitCurrentBranch(gitDirectory: String? = nil) -> Self {
+    GitVersion(workingDirectory: gitDirectory).command(for: .branch)
+  }
+
+  public static func gitCurrentTag(gitDirectory: String? = nil) -> Self {
+    GitVersion(workingDirectory: gitDirectory).command(for: .describe)
+  }
+}
+
+// MARK: - Private
+fileprivate struct GitVersion {
+  @Dependency(\.logger) var logger: Logger
+  @Dependency(\.shellClient) var shell: ShellClient
+
+  let workingDirectory: String?
+
+  func currentVersion() throws -> String {
+    logger.debug("\("Fetching current version".bold)")
+    do {
+      logger.debug("Checking for tag.")
+      return try run(command: command(for: .describe))
+    } catch {
+      logger.debug("\("No tag found, deferring to branch & git sha".red)")
+      let branch = try run(command: command(for: .branch))
+      let commit = try run(command: command(for: .commit))
+      return "\(branch) \(commit)"
+    }
+  }
+
+  internal func command(for argument: VersionArgs) -> ShellCommand {
+    .init(
+      shell: .env,
+      environment: nil,
+      in: workingDirectory ?? FileManager.default.currentDirectoryPath,
+      argument.arguments
+    )
+  }
+}
+
+fileprivate extension GitVersion {
+  func run(command: ShellCommand) throws -> String {
+    try shell.background(command, trimmingCharactersIn: .whitespacesAndNewlines)
+  }
+
+  enum VersionArgs {
+    case branch
+    case commit
+    case describe
+
+    var arguments: [Args] {
+      switch self {
+      case .branch:
+        return [.git, .symbolicRef, .quiet, .short, .head]
+      case .commit:
+        return [.git, .revParse, .short, .head]
+      case .describe:
+        return [.git, .describe, .tags, .exactMatch]
+      }
+    }
+
+    enum Args: String, CustomStringConvertible {
+      case git
+      case describe
+      case tags = "--tags"
+      case exactMatch = "--exact-match"
+      case quiet = "--quiet"
+      case symbolicRef = "symbolic-ref"
+      case revParse = "rev-parse"
+      case short = "--short"
+      case head = "HEAD"
+    }
+
+  }
+}
+
+extension RawRepresentable where RawValue == String, Self: CustomStringConvertible {
+  var description: String { rawValue }
+}