diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..876a9ec --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 Michael Housh + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/Makefile b/Makefile index 29a17ec..7ec7157 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -DOCC_TARGET ?= GitVersion +DOCC_TARGET ?= CliVersion DOCC_BASEPATH = $(shell basename "$(PWD)") DOCC_DIR ?= ./docs diff --git a/Package.resolved b/Package.resolved index 2d20565..4ea8763 100644 --- a/Package.resolved +++ b/Package.resolved @@ -86,8 +86,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/m-housh/swift-shell-client.git", "state" : { - "revision" : "28bcd2ecd0022aca20c520fc578a130bec7283e7", - "version" : "0.1.0" + "revision" : "bcd7a06377d43bac71c086d97d82e6c18504277e", + "version" : "0.1.3" } }, { diff --git a/Package.swift b/Package.swift index 52aac02..17a9fa0 100644 --- a/Package.swift +++ b/Package.swift @@ -3,44 +3,44 @@ import PackageDescription let package = Package( - name: "swift-git-version", + name: "swift-cli-version", platforms: [ - .macOS(.v12) + .macOS(.v10_15) ], products: [ - .library(name: "GitVersion", targets: ["GitVersion"]), + .library(name: "CliVersion", targets: ["CliVersion"]), .plugin(name: "BuildWithVersionPlugin", targets: ["BuildWithVersionPlugin"]), .plugin(name: "GenerateVersionPlugin", targets: ["GenerateVersionPlugin"]), .plugin(name: "UpdateVersionPlugin", targets: ["UpdateVersionPlugin"]) ], dependencies: [ - .package(url: "https://github.com/m-housh/swift-shell-client.git", from: "0.1.0"), + .package(url: "https://github.com/m-housh/swift-shell-client.git", from: "0.1.3"), .package(url: "https://github.com/apple/swift-docc-plugin.git", from: "1.0.0"), .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.2.2") ], targets: [ .executableTarget( - name: "git-version", + name: "cli-version", dependencies: [ - "GitVersion", + "CliVersion", .product(name: "ArgumentParser", package: "swift-argument-parser") ] ), .target( - name: "GitVersion", + name: "CliVersion", dependencies: [ .product(name: "ShellClient", package: "swift-shell-client") ] ), .testTarget( - name: "GitVersionTests", - dependencies: ["GitVersion"] + name: "CliVersionTests", + dependencies: ["CliVersion"] ), .plugin( name: "BuildWithVersionPlugin", capability: .buildTool(), dependencies: [ - "git-version" + "cli-version" ] ), .plugin( @@ -55,7 +55,7 @@ let package = Package( ] ), dependencies: [ - "git-version" + "cli-version" ] ), .plugin( @@ -70,7 +70,7 @@ let package = Package( ] ), dependencies: [ - "git-version" + "cli-version" ] ) ] diff --git a/Plugins/BuildWithVersionPlugin/BuildWithVersionPlugin.swift b/Plugins/BuildWithVersionPlugin/BuildWithVersionPlugin.swift index 3bf6f82..a866a46 100644 --- a/Plugins/BuildWithVersionPlugin/BuildWithVersionPlugin.swift +++ b/Plugins/BuildWithVersionPlugin/BuildWithVersionPlugin.swift @@ -13,7 +13,7 @@ struct GenerateVersionBuildPlugin: BuildToolPlugin { .removingLastComponent() .removingLastComponent() - let tool = try context.tool(named: "git-version") + let tool = try context.tool(named: "cli-version") let outputPath = context.pluginWorkDirectory let outputFile = outputPath.appending("Version.swift") diff --git a/Plugins/GenerateVersionPlugin/GenerateVersionPlugin.swift b/Plugins/GenerateVersionPlugin/GenerateVersionPlugin.swift index 5db858e..fd89cd4 100644 --- a/Plugins/GenerateVersionPlugin/GenerateVersionPlugin.swift +++ b/Plugins/GenerateVersionPlugin/GenerateVersionPlugin.swift @@ -5,7 +5,7 @@ import Foundation struct GenerateVersionPlugin: CommandPlugin { func performCommand(context: PluginContext, arguments: [String]) async throws { - let gitVersion = try context.tool(named: "git-version") + let gitVersion = try context.tool(named: "cli-version") let arguments = ["generate"] + arguments diff --git a/Plugins/UpdateVersionPlugin/UpdateVersionPlugin.swift b/Plugins/UpdateVersionPlugin/UpdateVersionPlugin.swift index 559b270..e2776c7 100644 --- a/Plugins/UpdateVersionPlugin/UpdateVersionPlugin.swift +++ b/Plugins/UpdateVersionPlugin/UpdateVersionPlugin.swift @@ -5,7 +5,7 @@ import Foundation struct UpdateVersionPlugin: CommandPlugin { func performCommand(context: PluginContext, arguments: [String]) async throws { - let gitVersion = try context.tool(named: "git-version") + let gitVersion = try context.tool(named: "cli-version") let arguments = ["update"] + arguments diff --git a/README.md b/README.md index b904475..a083fbe 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,74 @@ # swift-git-version -A swift package that exposes some helpers to set the version of a command line tool to the +A swift package that exposes some plugins to set the version of a command line tool to the git tag or the git sha, if a tag is not set for the current commit. -## Usage +[Github Repo](https://github.com/m-housh/swift-cli-version) +[Documentation](https://m-housh.github.io/swift-cli-version/documentation/cliversion) -You can use this in your command line tool via the swift package manager. +## 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-git-version.git", from: "0.1.0") + ..., + .package(url: "https://github.com/m-housh/swift-cli-version.git", from: "0.1.0") ], targets: [ .executableTarget( - name: "my-executable", - dependencies: [ - ... + name: "", + dependencies: [...], + plugins: [ + .plugin(name: "BuildWithVersionPlugin", package: "swift-cli-version") ] - ), - .executableTarget( - name: "my-executable-builder", - dependencies: [ - .product(name: "GitVersion", package: "swift-git-version") - ] - ), + ) ] ) ``` -Inside of your executable (`my-executable`) in the above example, you will want to create -a file that contains your version variable. +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 -// Do not set this variable, it is set by the build script. +import ArgumentParser -let VERSION: String? = nil +@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. + +## Documentation + +You can view the latest [documentation here](https://m-housh.github.io/swift-cli-version/documentation/cliversion). + +## Dependencies + +This project relys on the following dependencies: + +[swift-argument-parser](https://github.com/apple/swift-argument-parser) +[swift-dependencies](https://github.com/pointfreeco/swift-dependencies) +[swift-shell-client](https://github.com/m-housh/swift-shell-client) diff --git a/Sources/GitVersion/Documentation.docc/Articles/GettingStarted.md b/Sources/CliVersion/Documentation.docc/Articles/GettingStarted.md similarity index 53% rename from Sources/GitVersion/Documentation.docc/Articles/GettingStarted.md rename to Sources/CliVersion/Documentation.docc/Articles/GettingStarted.md index 397418e..2a7b613 100644 --- a/Sources/GitVersion/Documentation.docc/Articles/GettingStarted.md +++ b/Sources/CliVersion/Documentation.docc/Articles/GettingStarted.md @@ -7,19 +7,26 @@ Learn how to integrate the plugins into your project 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-git-version.git", from: "0.1.0") + .package(url: "https://github.com/m-housh/swift-cli-version.git", from: "0.1.0") ], targets: [ .executableTarget( name: "", dependencies: [...], plugins: [ - .plugin(name: "BuildWithVersionPlugin", package: "swift-git-version") + .plugin(name: "BuildWithVersionPlugin", package: "swift-cli-version") ] ) ] @@ -47,5 +54,16 @@ struct MyCliTool: ParsableCommand { } ``` -You will have access to the `VERSION` string variable even though it is not declared in your source -files. +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 + + diff --git a/Sources/CliVersion/Documentation.docc/Articles/ManualPlugins.md b/Sources/CliVersion/Documentation.docc/Articles/ManualPlugins.md new file mode 100644 index 0000000..814ed2d --- /dev/null +++ b/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 \ + +``` + +> 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 \ + +``` + +## 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 \ + +``` + +## 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 --help +``` + +Where `verb` is one of, `build`, `generate`, or `update`. diff --git a/Sources/GitVersion/Documentation.docc/GitVersion.md b/Sources/CliVersion/Documentation.docc/CliVersion.md similarity index 81% rename from Sources/GitVersion/Documentation.docc/GitVersion.md rename to Sources/CliVersion/Documentation.docc/CliVersion.md index 54fd22d..4a0dcc3 100644 --- a/Sources/GitVersion/Documentation.docc/GitVersion.md +++ b/Sources/CliVersion/Documentation.docc/CliVersion.md @@ -1,10 +1,10 @@ -# ``GitVersion`` +# ``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-git-version) +[Github Repo](https://github.com/m-housh/swift-cli-version) ## Overview @@ -15,8 +15,9 @@ the branch and git sha if a tag is not set for the current worktree state. ## Articles - +- -### Api +## Api - ``FileClient`` - ``GitVersionClient`` diff --git a/Sources/CliVersion/Documentation.docc/Resources/trust~dark.png b/Sources/CliVersion/Documentation.docc/Resources/trust~dark.png new file mode 100644 index 0000000..15245ce Binary files /dev/null and b/Sources/CliVersion/Documentation.docc/Resources/trust~dark.png differ diff --git a/Sources/GitVersion/FileClient.swift b/Sources/CliVersion/FileClient.swift similarity index 100% rename from Sources/GitVersion/FileClient.swift rename to Sources/CliVersion/FileClient.swift diff --git a/Sources/GitVersion/GitVersionClient.swift b/Sources/CliVersion/GitVersionClient.swift similarity index 100% rename from Sources/GitVersion/GitVersionClient.swift rename to Sources/CliVersion/GitVersionClient.swift diff --git a/Sources/git-version/BuildCommand.swift b/Sources/cli-version/BuildCommand.swift similarity index 96% rename from Sources/git-version/BuildCommand.swift rename to Sources/cli-version/BuildCommand.swift index de60511..abc6108 100644 --- a/Sources/git-version/BuildCommand.swift +++ b/Sources/cli-version/BuildCommand.swift @@ -1,9 +1,9 @@ import ArgumentParser import Foundation -import GitVersion +import CliVersion import ShellClient -extension GitVersionCommand { +extension CliVersionCommand { struct Build: ParsableCommand { static var configuration: CommandConfiguration = .init( abstract: "Used for the build with version plugin.", diff --git a/Sources/git-version/GitVersionCommand.swift b/Sources/cli-version/CliVersionCommand.swift similarity index 75% rename from Sources/git-version/GitVersionCommand.swift rename to Sources/cli-version/CliVersionCommand.swift index 1bdb318..81f66b4 100644 --- a/Sources/git-version/GitVersionCommand.swift +++ b/Sources/cli-version/CliVersionCommand.swift @@ -2,10 +2,10 @@ import ArgumentParser import Foundation @main -struct GitVersionCommand: ParsableCommand { +struct CliVersionCommand: ParsableCommand { static var configuration: CommandConfiguration = .init( - commandName: "git-version", + commandName: "cli-version", version: VERSION ?? "0.0.0", subcommands: [ Build.self, diff --git a/Sources/git-version/GenerateCommand.swift b/Sources/cli-version/GenerateCommand.swift similarity index 96% rename from Sources/git-version/GenerateCommand.swift rename to Sources/cli-version/GenerateCommand.swift index db86cde..41f01c9 100644 --- a/Sources/git-version/GenerateCommand.swift +++ b/Sources/cli-version/GenerateCommand.swift @@ -1,10 +1,10 @@ import ArgumentParser import Dependencies import Foundation -import GitVersion +import CliVersion import ShellClient -extension GitVersionCommand { +extension CliVersionCommand { struct Generate: ParsableCommand { static var configuration: CommandConfiguration = .init( diff --git a/Sources/git-version/Helpers.swift b/Sources/cli-version/Helpers.swift similarity index 100% rename from Sources/git-version/Helpers.swift rename to Sources/cli-version/Helpers.swift diff --git a/Sources/git-version/UpdateCommand.swift b/Sources/cli-version/UpdateCommand.swift similarity index 97% rename from Sources/git-version/UpdateCommand.swift rename to Sources/cli-version/UpdateCommand.swift index 791857e..a97b0e6 100644 --- a/Sources/git-version/UpdateCommand.swift +++ b/Sources/cli-version/UpdateCommand.swift @@ -1,9 +1,9 @@ import ArgumentParser import Foundation -import GitVersion +import CliVersion import ShellClient -extension GitVersionCommand { +extension CliVersionCommand { struct Update: ParsableCommand { static var configuration: CommandConfiguration = .init( diff --git a/Sources/git-version/Version.swift b/Sources/cli-version/Version.swift similarity index 100% rename from Sources/git-version/Version.swift rename to Sources/cli-version/Version.swift diff --git a/Tests/GitVersionTests/GitVersionTests.swift b/Tests/CliVersionTests/CliVersionTests.swift similarity index 95% rename from Tests/GitVersionTests/GitVersionTests.swift rename to Tests/CliVersionTests/CliVersionTests.swift index 20195a3..653cabf 100644 --- a/Tests/GitVersionTests/GitVersionTests.swift +++ b/Tests/CliVersionTests/CliVersionTests.swift @@ -1,5 +1,5 @@ import XCTest -import GitVersion +import CliVersion import ShellClient final class GitVersionTests: XCTestCase { @@ -22,6 +22,7 @@ final class GitVersionTests: XCTestCase { .deletingLastPathComponent() .deletingLastPathComponent() .absoluteString + .replacingOccurrences(of: "file://", with: "") } func test_overrides_work() throws { @@ -36,8 +37,7 @@ final class GitVersionTests: XCTestCase { } func test_live() throws { - - @Dependency(\.gitVersionClient) var versionClient + @Dependency(\.gitVersionClient) var versionClient: GitVersionClient let version = try versionClient.currentVersion(in: gitDir) print("VERSION: \(version)")