repo¶

Git repository operations for Go. Clone, commit, push, branch, inspect trees and work with worktrees, over go-git, behind focused interfaces that make consumers easy to test.

go get gitlab.com/phpboyscout/go/repo

r, err := repo.NewRepo(repo.Settings{
    Forge: repo.ForgeGitHub,
    Token: repo.StaticToken(os.Getenv("GITHUB_TOKEN")),
    FS:    afero.NewOsFs(),
})

Why¶

• No forge dependency. It authenticates to GitHub, GitLab, Bitbucket, Gitea and Codeberg while importing none of them. You pass a forge name and a token, not a forge client, and an unrecognised name is accepted so a self-hosted forge needs no code change. No vendor SDK enters your dependency graph. See why git needs no forge.
• Depend on the narrowest role. RepoLike composes nine small interfaces: TreeReader, Opener, Committer, Brancher and friends. Take the one your code actually uses and mocking becomes trivial. See role interfaces.
• In memory or on disk. The same API drives a real checkout or a purely in-memory repository, which is what makes tests fast and hermetic. See work in memory.
• The worktree is an afero.Fs. Read and write a checked-out tree with ordinary afero code, live: no copy, no sync step. See read and write the worktree.
• Lazy credentials. A token is a TokenSource, resolved only if the token path is taken, so an SSH-configured repository never triggers a keychain prompt.

Where next¶

Reference¶

• Settings reference: every configuration field, its default, and what happens when it is wrong.
• Options reference: the constructor and clone options, and which methods honour them.
• Errors reference: the four sentinels, every error this module emits, what causes it, and how to match it.

The generated API reference (signatures, types, doc comments) is on pkg.go.dev.

Limits¶

What this module does not do lists the git operations it deliberately does not wrap, the guarantees that are narrower than they sound, and how to reach past it when you need to.

Further reading¶

The blog carries a curated route through this subject: CI/CD, and getting things released collects everything written about it, ordered so you can start at the beginning rather than newest-first.