swift-developer-tools/swift-libgit2

Direct Swift bindings to libgit2.

Overview

swift-libgit2 provides direct Swift bindings to libgit2. libgit2 is a pure C implementation of core Git methods.

Swift bindings are provided for every libgit2 API, except opaque objects and initialization macros. Direct access to the libgit2 C library is also provided by the package. See Usage for an example of how to import and use either library.

The bindings use memory-safe Swift types wherever possible, while preserving libgit2's behavior and semantics. For example, some bindings use native Swift types like String instead of UnsafePointer<CChar>, and accept inout parameters to memory-safe Swift structs instead of unsafe pointers to C structs. In these cases, swift-libgit2 safely converts types between Swift and C, managing and freeing memory as needed. See Memory Management for more information.

The bindings use the same signatures and names as their C equivalents, but are written using camel case instead of snake case. Similar to libgit2, the bindings do not use namespaces. All bindings are available globally.

Documentation

See swift-libgit2 documentation for the complete API reference.

Installation

Swift Package Manager

swift-libgit2 may be installed using Swift Package Manager.

See Xcode documentation for instructions on how to add package dependencies.

Requirements

| Platform | Minimum Version | |-----------------|-----------------| | iOS | 15.0 | | macOS | 13.0 | | Swift | 6.1 |

swift-libgit2 supports both devices and simulators. The macOS builds support both Apple Silicon and Intel.

Usage

See libgit2 documentation for in-depth guides, examples, and references.

swift-libgit2 tests may also be referenced for general usage examples. However, keep in mind that these tests focus on validating binding behavior, not demonstrating complete Git workflows or best practices.

Below is a brief example showing how to import both the Swift and C libraries into a Swift project, and then use them to initialize and shut down the global libgit2 state.

// Import the Swift library.
import SwiftLibgit2

// Import the C library.
import CLibgit2

// Initialize and shut down the global libgit2 state using the Swift library.
let swiftInitResult     : Int32 = gitLibgit2Init()
let swiftShutdownResult : Int32 = gitLibgit2Shutdown()

// Initialize and shut down the global libgit2 state using the C library.
let cInitResult     : Int32 = git_libgit2_init()
let cShutdownResult : Int32 = git_libgit2_shutdown()

Best Practices

Error Handling

Most swift-libgit2 functions return a libgit2 result code. Handle errors before moving on to the next step of the process.

GIT_EUSER is a special error code that is never generated by libgit2. swift-libgit2 functions will return this error code if a value could not be converted from Swift to C, or in other cases specific to individual functions.

Memory Management

swift-libgit2 handles memory management for most bindings. For example, inout Swift types are safely converted between Swift and C, with any allocated memory being freed as needed.

However, some bindings require manual memory management, particularly when working with opaque or unsafe pointers. The caller is responsible for freeing the memory using the appropriate swift-libgit2 or libgit2 function.

Consider using defer statements with memory-freeing functions to consistently and safely free memory.

Thread Safety

libgit2 objects cannot be safely accessed by multiple threads simultaneously. Doing so may result in data loss or undefined behavior.

Consider using threading APIs such as DispatchQueue to ensure thread-safe access to libgit2.

Concurrency

Some libgit2 APIs are asynchronous, but are not exposed as asynchronous. Generally, any API that interacts with a remote repository is asynchronous. Since swift-libgit2 provides direct bindings to libgit2, no Swift bindings are asynchronous either.

Consider using an appropriate concurrency API to handle these cases and other synchronous work which may be better performed off the main thread.

Secure Storage

libgit2 supports the use of personal access tokens and SSH credentials to authenticate when accessing remote repositories. swift-libgit2 has been built to support these authentication methods, including in-memory SSH.

Consider using iCloud Keychain or other cryptographic APIs to securely store authentication data with end-to-end encryption.

License

swift-libgit2 is licensed under the Apache License, Version 2.0.

See LICENSE for the complete license terms.

Attribution

See Licenses for the complete third-party license terms.

Documentation

swift-libgit2 documentation is adapted from libgit2 under the MIT License.

Source Code

swift-libgit2 includes source code adapted from the Swift.org open source project under the Apache License, Version 2.0, with Runtime Library Exception.

See https://swift.org/LICENSE.txt for license information.

See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors.

Bundled Dependencies

swift-libgit2 includes the following compiled libraries:

| Library | Version | Source | License | |---------|---------|---------|---------| | libgit2 | 1.9.1 | https://github.com/libgit2/libgit2 | GNU GPL, Version 2, with linking exception | | libssh2 | 1.11.1 | https://github.com/libssh2/libssh2 | BSD-3-Clause License | | OpenSSL | 3.5.2 | https://github.com/openssl/openssl | Apache License, Version 2.0 |

Package Metadata

Repository: swift-developer-tools/swift-libgit2

Default branch: main

README: README.md