git2go

Because Go 1.11 module versions follow semantic versioning and do not align with libgit2's release schedule, you must use the correct git2go module suffix to match your installed libgit2 version. This ensures API stability.

Testing requirements depend on the branch you are using:

• Stable versions: Use go test as usual.
• main branch: Requires a local libgit2 library. You can use the provided Makefile wrapper:

  make test-static

  Or build the library manually first:

  make install-static
  go test -v -tags static ./...

To use a versioned branch with dynamic linking, install the corresponding libgit2 version via your system's package manager. CGo will use pkg-config to locate the library and set up linking automatically.

Example for libgit2 v1.2 (using git2go v34):

go get github.com/libgit2/git2go/v34

import "github.com/libgit2/git2go/v34"

To link statically against a versioned libgit2 already installed on your system, you must pass the -tags static,system_libgit2 flag to all go commands used during the build process.

go build -tags static,system_libgit2 github.com/my/project/...
go test -tags static,system_libgit2 github.com/my/project/...
go install -tags static,system_libgit2 github.com/my/project/...

If you need to support a custom communication protocol for Git remotes, you can implement the SmartSubtransport interface and register it using NewRegisteredSmartTransport.

To implement a custom subtransport, you must provide:

1. An Action(url string, action SmartServiceAction) method: This creates a SmartSubtransportStream for a specific URL and requested action (e.g., SmartServiceActionUploadpack).
2. A Close() method: Closes the subtransport.
3. A Free() method: Releases all resources used by the subtransport.

The SmartSubtransportStream (which you return from Action) must implement io.Reader, io.Writer, and a Free() method to handle the actual data transfer.

The StashCollection type provides the primary interface for managing the stash list in a repository. You can use it to save new stashes, apply existing ones, pop them from the list, drop specific entries, or iterate over all stashed states.

Key methods:

• Save(stasher *Signature, message string, flags StashFlag) (*Oid, error): Saves local modifications to a new stash.
• Apply(index int, opts StashApplyOptions) error: Applies a stashed state at the given index (0 is the most recent).
• Pop(index int, opts StashApplyOptions) error: Applies a stashed state and removes it from the list if successful.
• Drop(index int) error: Removes a stashed state at the given index.
• Foreach(callback StashCallback) error: Iterates over all stashes, calling the provided callback for each entry.

The Odb type provides the primary interface for interacting with Git's object storage. You can use it to read, write, hash, and iterate over Git objects (blobs, trees, commits, etc.).

Key operations include:

• Reading: Use Read(oid) to get an OdbObject or NewReadStream(id) for streaming large objects.
• Writing: Use Write(data, otype) for small objects or NewWriteStream(size, otype) for streaming writes.
• Existence/Metadata: Use Exists(oid) to check for an object or ReadHeader(oid) to get its size and type without loading the full content.
• Hashing: Use Hash(data, otype) to compute the Oid of a data buffer.

In git2go, a Branch is a specialized type that embeds a *Reference. This means a Branch provides all the functionality of a Git reference (like a pointer to a commit) but adds branch-specific logic such as upstream management and branch-specific iteration.

You can convert any *Reference into a *Branch using the Branch() method on the reference.

branch := reference.Branch()

The git2go API provides two primary types for submodule management: SubmoduleCollection (representing the set of submodules in a repository) and Submodule (representing an individual submodule).

• Use SubmoduleCollection.Lookup(name string) to find a specific submodule by its name.
• Use SubmoduleCollection.Foreach(callback SubmoduleCallback) to iterate over all submodules in the repository.
• Use SubmoduleCollection.Add(url, path string, use_git_link bool) to prepare a new submodule.
• Use Submodule.Open() to obtain a *Repository instance for the submodule's own working directory.
• Use Submodule.Update(init bool, opts *SubmoduleUpdateOptions) to update the submodule's content.

The RevWalk type allows you to traverse the commit history of a repository. You can define the scope of the walk by pushing specific commits, globs, ranges, or references, and you can exclude certain commits using Hide methods. The traversal can be configured with different sorting strategies and can be executed manually using Next or via a high-level Iterate function.

To use RevWalk, you typically:

1. Push starting points (e.g., PushHead, Push, PushRef).
2. (Optional) Hide specific commits or references.
3. Set a sorting strategy using Sorting.
4. Iterate through the commits using Iterate.