Allow for .package(url: , branch:) syntax (#3292)

motivation: simpler/nicer syntax 

changes: Permit .package(url: String, branch: String) syntax

Author: miggs597

CHANGELOG.md

@@ -1,5 +1,13 @@
 Note: This is in reverse chronological order, so newer entries are added to the top.
 
+Swift v.Next
+-----------
+* [#3292]
+   * Improvements
+   
+   Adding a dependency requirement can now be done with the convenience initializer `.package(url: String, branch: String)`.
+
+
 Swift 5.4
 -----------
 * [#2937]
@@ -21,6 +29,8 @@ Swift 5.4
   * Source Breakages for Swift Packages
 
     The package manager now throws an error if a manifest file contains invalid UTF-8 byte sequences.
+    
+
 
 Swift 4.2
 ---------

Documentation/PackageDescription.md

@@ -296,6 +296,16 @@ static func package(url: String, from version: Version) -> Package.Dependency
 ///     - requirement: A dependency requirement. See static methods on `Package.Dependency.Requirement` for available options.
 static func package(url: String, _ requirement: Package.Dependency.Requirement) -> Package.Dependency
 
+/// Adds a remote package dependency given a branch requirement.
+///
+///    .package(url: "https://example.com/example-package.git", branch: "main"),
+///
+/// - Parameters:
+///     - name: The name of the package, or nil to deduce it from the URL.
+///     - url: The valid Git URL of the package.
+///     - branch: A dependency requirement. See static methods on `Package.Dependency.Requirement` for available options.
+static func package(name: String? = nil, url: String, branch: String) -> Package.Dependency
+
 /// Add a package dependency starting with a specific minimum version, up to
 /// but not including a specified maximum version.
 ///

Fixtures/DependencyResolution/External/Branch/Bar/Package.swift

@@ -0,0 +1,26 @@
+// swift-tools-version:999.0
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "Bar",
+    products: [
+        // Products define the executables and libraries a package produces, and make them visible to other packages.
+        .library(
+            name: "Bar",
+            targets: ["Bar"]),
+    ],
+    dependencies: [
+        // Dependencies declare other packages that this package depends on.
+        // .package(url: /* package url */, from: "1.0.0"),
+	.package(url: "../Foo", branch: "main")
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
+        // Targets can depend on other targets in this package, and on products in packages this package depends on.
+        .target(
+            name: "Bar",
+            dependencies: ["Foo"]),
+    ]
+)

Fixtures/DependencyResolution/External/Branch/Bar/Sources/Bar/Bar.swift

@@ -0,0 +1,5 @@
+import Foo
+
+struct Bar {
+    var text = "Hello, World!"
+}

Fixtures/DependencyResolution/External/Branch/Foo/Package.swift

@@ -0,0 +1,25 @@
+// swift-tools-version:999.0
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "Foo",
+    products: [
+        // Products define the executables and libraries a package produces, and make them visible to other packages.
+        .library(
+            name: "Foo",
+            targets: ["Foo"]),
+    ],
+    dependencies: [
+        // Dependencies declare other packages that this package depends on.
+        // .package(url: /* package url */, from: "1.0.0"),
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
+        // Targets can depend on other targets in this package, and on products in packages this package depends on.
+        .target(
+            name: "Foo",
+            dependencies: []),
+    ]
+)

Fixtures/DependencyResolution/External/Branch/Foo/Sources/Foo/Foo.swift

@@ -0,0 +1,3 @@
+struct Foo {
+    var text = "Hello, World!"
+}

Sources/PackageDescription/PackageDependency.swift

@@ -64,6 +64,23 @@ extension Package.Dependency {
     ) -> Package.Dependency {
         return .init(name: name, url: url, requirement: .upToNextMajor(from: version))
     }
+    
+    /// Adds a remote package dependency given a branch requirement.
+    ///
+    ///    .package(url: "https://example.com/example-package.git", branch: "main"),
+    ///
+    /// - Parameters:
+    ///     - name: The name of the package, or nil to deduce it from the URL.
+    ///     - url: The valid Git URL of the package.
+    ///     - branch: A dependency requirement. See static methods on `Package.Dependency.Requirement` for available options.
+    @available(_PackageDescription, introduced: 999.0)
+    public static func package(
+        name: String? = nil,
+        url: String,
+        branch: String
+    ) -> Package.Dependency {
+        return .init(name: name, url: url, requirement: .branch(branch))
+    }
 
     /// Adds a remote package dependency given a version requirement.
     ///
@@ -249,11 +266,6 @@ extension Package.Dependency {
         fatalError()
     }
 
-    @available(*, unavailable, message: "use package(url:_:) with the .branch(String) initializer instead")
-    public static func package(url: String, branch: String) -> Package.Dependency {
-        fatalError()
-    }
-
     @available(*, unavailable, message: "use package(url:_:) with the .revision(String) initializer instead")
     public static func package(url: String, revision: String) -> Package.Dependency {
         fatalError()

Sources/SPMTestSupport/misc.swift

@@ -132,6 +132,7 @@ public func initGitRepo(
         for tag in tags {
             try repo.tag(name: tag)
         }
+        try systemQuietly([Git.tool, "-C", dir.pathString, "branch", "-m", "main"])
     } catch {
         XCTFail("\(error)", file: file, line: line)
     }

Tests/FunctionalTests/DependencyResolutionTests.swift

@@ -65,6 +65,15 @@ class DependencyResolutionTests: XCTestCase {
             XCTAssertEqual(output, "♣︎K\n♣︎Q\n♣︎J\n♣︎10\n♣︎9\n♣︎8\n♣︎7\n♣︎6\n♣︎5\n♣︎4\n")
         }
     }
+    
+    func testConvenienceBranchInit() throws {
+        fixture(name: "DependencyResolution/External/Branch") { prefix in
+            // Tests the convenience init .package(url: , branch: )
+            let app = prefix.appending(component: "Bar")
+            let result = try SwiftPMProduct.SwiftBuild.executeProcess([], packagePath: app)
+            XCTAssert(result.exitStatus == .terminated(code: 0))
+        }
+    }
 
     func testMirrors() {
         fixture(name: "DependencyResolution/External/Mirror") { prefix in
@@ -76,7 +85,7 @@ class DependencyResolutionTests: XCTestCase {
             try ["Foo", "Bar", "BarMirror"].forEach { directory in
                 let path = prefix.appending(component: directory)
                 _ = try Process.checkNonZeroExit(args: "git", "-C", path.pathString, "init")
-                _ = try Process.checkNonZeroExit(args: "git", "-C", path.pathString, "checkout", "-b", "main")
+                _ = try Process.checkNonZeroExit(args: "git", "-C", path.pathString, "checkout", "-b", "newMain")
             }
 
             // run with no mirror

Tests/PackageLoadingTests/PD4_0LoadingTests.swift

@@ -299,7 +299,6 @@ class PackageDescription4_0LoadingTests: PackageDescriptionLoadingTests {
             XCTFail("this package should not load succesfully")
         } catch ManifestParseError.invalidManifestFormat(let error, _) {
             XCTAssert(error.contains("error: 'package(url:version:)' is unavailable: use package(url:_:) with the .exact(Version) initializer instead\n"), "\(error)")
-            XCTAssert(error.contains("error: 'package(url:branch:)' is unavailable: use package(url:_:) with the .branch(String) initializer instead\n"), "\(error)")
             XCTAssert(error.contains("error: 'package(url:revision:)' is unavailable: use package(url:_:) with the .revision(String) initializer instead\n"), "\(error)")
             XCTAssert(error.contains("error: 'package(url:range:)' is unavailable: use package(url:_:) without the range label instead\n"), "\(error)")
         }

Tests/SourceControlTests/GitRepositoryTests.swift

@@ -59,15 +59,15 @@ class GitRepositoryTests: XCTestCase {
                 XCTFail("unexpected resolution of invalid tag to \(revision)")
             }
 
-            let master = try repository.resolveRevision(identifier: "master")
+            let main = try repository.resolveRevision(identifier: "main")
 
-            XCTAssertEqual(master.identifier,
+            XCTAssertEqual(main.identifier,
                 try Process.checkNonZeroExit(
-                    args: Git.tool, "-C", testRepoPath.pathString, "rev-parse", "--verify", "master").spm_chomp())
+                    args: Git.tool, "-C", testRepoPath.pathString, "rev-parse", "--verify", "main").spm_chomp())
 
             // Check that git hashes resolve to themselves.
-            let masterIdentifier = try repository.resolveRevision(identifier: master.identifier)
-            XCTAssertEqual(master.identifier, masterIdentifier.identifier)
+            let mainIdentifier = try repository.resolveRevision(identifier: main.identifier)
+            XCTAssertEqual(main.identifier, mainIdentifier.identifier)
 
             // Check that invalid identifier doesn't resolve.
             if let revision = try? repository.resolveRevision(identifier: "invalid") {
@@ -157,7 +157,7 @@ class GitRepositoryTests: XCTestCase {
             try repo.stageEverything()
             try repo.commit()
             // We should be able to read a repo which as a submdoule.
-            _ = try repo.read(tree: try repo.resolveHash(treeish: "master"))
+            _ = try repo.read(tree: try repo.resolveHash(treeish: "main"))
         }
     }
 
@@ -365,7 +365,7 @@ class GitRepositoryTests: XCTestCase {
             // We should have commits which are not pushed.
             XCTAssert(try checkoutRepo.hasUnpushedCommits())
             // Push the changes and check again.
-            try checkoutTestRepo.push(remote: "origin", branch: "master")
+            try checkoutTestRepo.push(remote: "origin", branch: "main")
             XCTAssertFalse(try checkoutRepo.hasUnpushedCommits())
         }
     }
@@ -437,7 +437,7 @@ class GitRepositoryTests: XCTestCase {
             let repo = GitRepository(path: testRepoPath)
             var currentRevision = try repo.getCurrentRevision()
             // This is the default branch of a new repo.
-            XCTAssert(repo.exists(revision: Revision(identifier: "master")))
+            XCTAssert(repo.exists(revision: Revision(identifier: "main")))
             // Check a non existent revision.
             XCTAssertFalse(repo.exists(revision: Revision(identifier: "nonExistent")))
             // Checkout a new branch using command line.
@@ -470,9 +470,9 @@ class GitRepositoryTests: XCTestCase {
                 try repo.stage(file: "test.txt")
             }
 
-            try repo.checkout(revision: Revision(identifier: "master"))
-            // Current branch must be master.
-            XCTAssertEqual(try repo.currentBranch(), "master")
+            try repo.checkout(revision: Revision(identifier: "main"))
+            // Current branch must be main.
+            XCTAssertEqual(try repo.currentBranch(), "main")
             // Create a new branch.
             try repo.checkout(newBranch: "TestBranch")
             XCTAssertEqual(try repo.currentBranch(), "TestBranch")
@@ -657,9 +657,9 @@ class GitRepositoryTests: XCTestCase {
             initGitRepo(testRepoPath)
             let repo = GitRepository(path: testRepoPath)
 
-            // Create a `main` branch and remove `master`.
-            try repo.checkout(newBranch: "main")
-            try systemQuietly([Git.tool, "-C", testRepoPath.pathString, "branch", "-D", "master"])
+            // Create a `newMain` branch and remove `main`.
+            try repo.checkout(newBranch: "newMain")
+            try systemQuietly([Git.tool, "-C", testRepoPath.pathString, "branch", "-D", "main"])
 
             // Change the branch name to something non-existent.
             try systemQuietly([Git.tool, "-C", testRepoPath.pathString, "symbolic-ref", "HEAD", "refs/heads/_non_existent_branch_"])
@@ -679,7 +679,7 @@ class GitRepositoryTests: XCTestCase {
             let checkoutRepo = try provider.openCheckout(at: checkoutPath)
 
             // Try to check out the `main` branch.
-            try checkoutRepo.checkout(revision: Revision(identifier: "main"))
+            try checkoutRepo.checkout(revision: Revision(identifier: "newMain"))
             XCTAssertTrue(localFileSystem.exists(checkoutPath.appending(component: "file.swift")))
 
             // The following will throw if HEAD was set incorrectly and we didn't do a no-checkout clone.