add git pull.

Author: dunkbing

Sources/SwiftGitX/Helpers/SwiftGitXError.swift

@@ -423,7 +423,9 @@ extension SwiftGitXError {
         public static let fetch = Operation(rawValue: "fetch")
         public static let head = Operation(rawValue: "head")
         public static let index = Operation(rawValue: "index")
+        public static let merge = Operation(rawValue: "merge")
         public static let patch = Operation(rawValue: "patch")
+        public static let pull = Operation(rawValue: "pull")
         public static let push = Operation(rawValue: "push")
         public static let reset = Operation(rawValue: "reset")
         public static let restore = Operation(rawValue: "restore")

Sources/SwiftGitX/Repository/Repository+pull.swift

@@ -0,0 +1,250 @@
+//
+//  Repository+pull.swift
+//  SwiftGitX
+//
+//  Created by dunkbing
+//
+
+import libgit2
+
+extension Repository {
+    /// Pull changes from the remote repository.
+    ///
+    /// - Parameter remote: The remote to pull the changes from.
+    ///
+    /// This method fetches changes from the remote and merges them into the current branch.
+    /// It supports fast-forward merges and normal merges.
+    ///
+    /// If the remote is not specified, the upstream of the current branch is used
+    /// and if the upstream branch is not found, the `origin` remote is used.
+    ///
+    /// - Throws: `SwiftGitXError` if the pull operation fails or if there are conflicts.
+    ///
+    /// ### Example
+    /// ```swift
+    /// // Pull from the default remote
+    /// try await repository.pull()
+    ///
+    /// // Pull from a specific remote
+    /// let remote = repository.remote["origin"]!
+    /// try await repository.pull(remote: remote)
+    /// ```
+    public nonisolated func pull(remote: Remote? = nil) async throws(SwiftGitXError) {
+        // Get the current branch
+        let currentBranch = try branch.current
+
+        // Get the remote
+        guard let remote = remote ?? currentBranch.remote ?? self.remote["origin"] else {
+            throw SwiftGitXError(code: .notFound, operation: .pull, category: .reference, message: "Remote not found")
+        }
+
+        // Get the upstream branch name
+        guard let upstream = currentBranch.upstream else {
+            throw SwiftGitXError(
+                code: .notFound, operation: .pull, category: .reference,
+                message: "No upstream branch configured for '\(currentBranch.name)'"
+            )
+        }
+
+        // Fetch from remote first
+        try await fetch(remote: remote)
+
+        // Get the remote branch after fetch
+        let remoteBranch = try branch.get(named: upstream.name, type: .remote)
+
+        // Get the commit to merge
+        guard let remoteCommit = remoteBranch.target as? Commit else {
+            throw SwiftGitXError(
+                code: .error, operation: .pull, category: .reference,
+                message: "Remote branch does not point to a commit"
+            )
+        }
+
+        // Perform merge analysis
+        var analysis = git_merge_analysis_t(rawValue: 0)
+        var preference = git_merge_preference_t(rawValue: 0)
+
+        var remoteOID = remoteCommit.id.raw
+        var annotatedCommit: OpaquePointer?
+
+        try git(operation: .pull) {
+            git_annotated_commit_lookup(&annotatedCommit, pointer, &remoteOID)
+        }
+        defer { git_annotated_commit_free(annotatedCommit) }
+
+        var annotatedCommits: [OpaquePointer?] = [annotatedCommit]
+
+        try git(operation: .pull) {
+            annotatedCommits.withUnsafeMutableBufferPointer { buffer in
+                git_merge_analysis(&analysis, &preference, pointer, buffer.baseAddress, 1)
+            }
+        }
+
+        // Check if we're already up to date
+        if analysis.rawValue & GIT_MERGE_ANALYSIS_UP_TO_DATE.rawValue != 0 {
+            // Already up to date, nothing to do
+            return
+        }
+
+        // Check if we can fast-forward
+        if analysis.rawValue & GIT_MERGE_ANALYSIS_FASTFORWARD.rawValue != 0 {
+            // Fast-forward merge: simply reset HEAD to the remote commit
+            try reset(to: remoteCommit, mode: .hard)
+            return
+        }
+
+        // Normal merge required
+        if analysis.rawValue & GIT_MERGE_ANALYSIS_NORMAL.rawValue != 0 {
+            try performMerge(
+                annotatedCommit: annotatedCommit!,
+                remoteBranch: remoteBranch,
+                remoteCommit: remoteCommit
+            )
+            return
+        }
+
+        throw SwiftGitXError(
+            code: .error, operation: .pull, category: .merge,
+            message: "Merge analysis returned unexpected result"
+        )
+    }
+
+    // MARK: - Private Helpers
+
+    /// Performs a normal merge with the given annotated commit.
+    private func performMerge(
+        annotatedCommit: OpaquePointer,
+        remoteBranch: Branch,
+        remoteCommit: Commit
+    ) throws(SwiftGitXError) {
+        // Initialize merge options
+        var mergeOptions = git_merge_options()
+        git_merge_options_init(&mergeOptions, UInt32(GIT_MERGE_OPTIONS_VERSION))
+
+        // Initialize checkout options
+        var checkoutOptions = git_checkout_options()
+        git_checkout_options_init(&checkoutOptions, UInt32(GIT_CHECKOUT_OPTIONS_VERSION))
+        checkoutOptions.checkout_strategy = GIT_CHECKOUT_SAFE.rawValue
+
+        // Perform the merge
+        var annotatedCommits: [OpaquePointer?] = [annotatedCommit]
+
+        try git(operation: .merge) {
+            annotatedCommits.withUnsafeMutableBufferPointer { buffer in
+                git_merge(pointer, buffer.baseAddress, 1, &mergeOptions, &checkoutOptions)
+            }
+        }
+
+        // Check for conflicts
+        let index = try git(operation: .merge) {
+            var indexPointer: OpaquePointer?
+            let status = git_repository_index(&indexPointer, pointer)
+            return (indexPointer, status)
+        }
+        defer { git_index_free(index) }
+
+        if git_index_has_conflicts(index) == 1 {
+            // Clean up merge state
+            git_repository_state_cleanup(pointer)
+
+            throw SwiftGitXError(
+                code: .conflict, operation: .pull, category: .merge,
+                message: "Merge conflicts detected. Please resolve conflicts manually."
+            )
+        }
+
+        // Create merge commit
+        try createMergeCommit(remoteBranch: remoteBranch, remoteCommit: remoteCommit)
+
+        // Clean up merge state
+        git_repository_state_cleanup(pointer)
+    }
+
+    /// Creates a merge commit after a successful merge.
+    private func createMergeCommit(remoteBranch: Branch, remoteCommit: Commit) throws(SwiftGitXError) {
+        // Get the index
+        let index = try git(operation: .merge) {
+            var indexPointer: OpaquePointer?
+            let status = git_repository_index(&indexPointer, pointer)
+            return (indexPointer, status)
+        }
+        defer { git_index_free(index) }
+
+        // Write the index as a tree
+        var treeOID = git_oid()
+        try git(operation: .merge) {
+            git_index_write_tree(&treeOID, index)
+        }
+
+        // Get the tree
+        let tree = try git(operation: .merge) {
+            var treePointer: OpaquePointer?
+            let status = git_tree_lookup(&treePointer, pointer, &treeOID)
+            return (treePointer, status)
+        }
+        defer { git_tree_free(tree) }
+
+        // Get HEAD commit
+        let headCommit = try HEAD.target as! Commit
+
+        // Get signature
+        var signature: UnsafeMutablePointer<git_signature>?
+        try git(operation: .merge) {
+            git_signature_default(&signature, pointer)
+        }
+        defer { git_signature_free(signature) }
+
+        // Create merge commit message
+        let message = "Merge branch '\(remoteBranch.displayName)'"
+
+        // Get parent commit pointers
+        let headCommitPointer = try ObjectFactory.lookupObjectPointer(
+            oid: headCommit.id.raw,
+            type: GIT_OBJECT_COMMIT,
+            repositoryPointer: pointer
+        )
+        defer { git_object_free(headCommitPointer) }
+
+        let remoteCommitPointer = try ObjectFactory.lookupObjectPointer(
+            oid: remoteCommit.id.raw,
+            type: GIT_OBJECT_COMMIT,
+            repositoryPointer: pointer
+        )
+        defer { git_object_free(remoteCommitPointer) }
+
+        // Create the merge commit
+        var commitOID = git_oid()
+        var parents: [OpaquePointer?] = [headCommitPointer, remoteCommitPointer]
+
+        try git(operation: .merge) {
+            parents.withUnsafeMutableBufferPointer { buffer in
+                git_commit_create(
+                    &commitOID,
+                    pointer,
+                    "HEAD",
+                    signature,
+                    signature,
+                    nil,
+                    message,
+                    tree,
+                    2,
+                    buffer.baseAddress
+                )
+            }
+        }
+    }
+}
+
+// MARK: - Branch Display Name Extension
+
+extension Branch {
+    /// Returns a display-friendly name for the branch.
+    var displayName: String {
+        if type == .remote {
+            // Remove remote prefix (e.g., "origin/main" -> "main")
+            let remoteName = remote?.name ?? "origin"
+            return name.replacingOccurrences(of: "\(remoteName)/", with: "")
+        }
+        return name
+    }
+}

Tests/SwiftGitXTests/RepositoryTests/RepositoryPullTests.swift

@@ -0,0 +1,120 @@
+import Foundation
+import SwiftGitX
+import Testing
+
+@Suite("Repository - Pull", .tags(.repository, .operation, .pull))
+final class RepositoryPullTests: SwiftGitXTest {
+    @Test("Pull from remote repository - fast forward")
+    func pullFastForward() async throws {
+        // Create remote repository with initial commit
+        let remoteRepository = mockRepository(suffix: "--remote")
+        try remoteRepository.mockCommit(message: "Initial commit")
+
+        // Clone to create local repository with tracking branch
+        let localDirectory = mockDirectory(suffix: "--local")
+        let localRepository = try await Repository.clone(from: remoteRepository.workingDirectory, to: localDirectory)
+
+        // Add another commit to the remote repository
+        try remoteRepository.mockCommit(message: "Remote commit")
+
+        // Get initial local HEAD
+        let initialLocalHead = try localRepository.HEAD.target.id
+
+        // Pull the changes
+        try await localRepository.pull()
+
+        // Verify local HEAD has been updated
+        let finalLocalHead = try localRepository.HEAD.target.id
+        let remoteHead = try remoteRepository.HEAD.target.id
+
+        #expect(finalLocalHead == remoteHead)
+        #expect(finalLocalHead != initialLocalHead)
+    }
+
+    @Test("Pull when already up to date")
+    func pullUpToDate() async throws {
+        // Create remote repository with initial commit
+        let remoteRepository = mockRepository(suffix: "--remote")
+        try remoteRepository.mockCommit(message: "Initial commit")
+
+        // Clone to create local repository
+        let localDirectory = mockDirectory(suffix: "--local")
+        let localRepository = try await Repository.clone(from: remoteRepository.workingDirectory, to: localDirectory)
+
+        // Get initial local HEAD
+        let initialLocalHead = try localRepository.HEAD.target.id
+
+        // Pull when already up to date
+        try await localRepository.pull()
+
+        // Verify local HEAD is unchanged
+        let finalLocalHead = try localRepository.HEAD.target.id
+        #expect(finalLocalHead == initialLocalHead)
+    }
+
+    @Test("Pull with normal merge")
+    func pullNormalMerge() async throws {
+        // Create remote repository with initial commit
+        let remoteRepository = mockRepository(suffix: "--remote")
+        try remoteRepository.mockCommit(message: "Initial commit")
+
+        // Clone to create local repository
+        let localDirectory = mockDirectory(suffix: "--local")
+        let localRepository = try await Repository.clone(from: remoteRepository.workingDirectory, to: localDirectory)
+
+        // Add a commit to the remote repository
+        try remoteRepository.mockCommit(message: "Remote commit")
+
+        // Add a different commit to the local repository (creates divergence)
+        try localRepository.mockCommit(message: "Local commit")
+
+        // Pull the changes (should create merge commit)
+        try await localRepository.pull()
+
+        // Verify that we now have a merge commit (commit with 2 parents)
+        let headCommit = try localRepository.HEAD.target as! Commit
+        let parents = try headCommit.parents
+        #expect(parents.count == 2)
+    }
+
+    @Test("Pull fails without upstream branch")
+    func pullWithoutUpstream() async throws {
+        // Create a repository without remote
+        let repository = mockRepository()
+        try repository.mockCommit()
+
+        // Try to pull without upstream configured
+        await #expect(throws: SwiftGitXError.self) {
+            try await repository.pull()
+        }
+    }
+
+    @Test("Pull multiple commits")
+    func pullMultipleCommits() async throws {
+        // Create remote repository
+        let remoteRepository = mockRepository(suffix: "--remote")
+        try remoteRepository.mockCommit(message: "Initial commit")
+
+        // Clone to create local repository
+        let localDirectory = mockDirectory(suffix: "--local")
+        let localRepository = try await Repository.clone(from: remoteRepository.workingDirectory, to: localDirectory)
+
+        // Add multiple commits to remote
+        try remoteRepository.mockCommit(message: "Second commit")
+        try remoteRepository.mockCommit(message: "Third commit")
+        try remoteRepository.mockCommit(message: "Fourth commit")
+
+        // Pull all changes
+        try await localRepository.pull()
+
+        // Verify local HEAD matches remote HEAD
+        let localHead = try localRepository.HEAD.target.id
+        let remoteHead = try remoteRepository.HEAD.target.id
+        #expect(localHead == remoteHead)
+
+        // Verify commit count matches
+        let localCommitCount = try localRepository.log().reduce(0) { count, _ in count + 1 }
+        let remoteCommitCount = try remoteRepository.log().reduce(0) { count, _ in count + 1 }
+        #expect(localCommitCount == remoteCommitCount)
+    }
+}

Tests/SwiftGitXTests/Tags.swift

@@ -16,7 +16,9 @@ extension Testing.Tag {
     @Tag static var diff: Self
     @Tag static var fetch: Self
     @Tag static var log: Self
+    @Tag static var merge: Self
     @Tag static var patch: Self
+    @Tag static var pull: Self
     @Tag static var push: Self
     @Tag static var reset: Self
     @Tag static var restore: Self