Documentation
¶
Overview ¶
Package git is outpost's embedded git client. It wraps go-git/v5 to provide the typical clone → edit → add → commit → push lifecycle plus the common read/inspect verbs (status, log, diff, branch, show, remote, fetch, pull). The whole point is to ship a usable git on Windows hosts where setting up a system git binary + credentials is painful — go-git is pure Go, no cgo, no shell-out, so the same code path works on every platform outpost builds for.
Scope intentionally stops at the simple-drop-in line: rebase, stash, merge, tag, reset, blame, submodules, worktrees, reflog, bisect are not implemented. Users who need those can install system git.
Index ¶
- func BuildAuthMethod(auth AuthConfig) (transport.AuthMethod, error)
- func Log(opts LogOptions) (*Result, []LogEntry, error)
- func Remotes(repoPath string) (*Result, []RemoteEntry, error)
- func Show(opts ShowOptions) (*Result, *ShowResult, error)
- func Status(repoPath string) (*Result, []StatusEntry, error)
- func StatusCode(status gogit.StatusCode) string
- type AddOptions
- type AuthConfig
- type BranchOptions
- type CheckoutOptions
- type CloneOptions
- type CommitOptions
- type FetchOptions
- type InitOptions
- type LogEntry
- type LogOptions
- type PullOptions
- type PushOptions
- type RemoteEntry
- type Result
- func Add(opts AddOptions) (*Result, error)
- func Branch(opts BranchOptions) (*Result, []string, error)
- func Checkout(opts CheckoutOptions) (*Result, error)
- func Clone(opts CloneOptions) (*Result, error)
- func Commit(opts CommitOptions) (*Result, error)
- func Fetch(opts FetchOptions) (*Result, error)
- func Init(opts InitOptions) (*Result, error)
- func Pull(opts PullOptions) (*Result, error)
- func Push(opts PushOptions) (*Result, error)
- type RevParseOptions
- type RevParseResult
- type ShowOptions
- type ShowResult
- type StatusEntry
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildAuthMethod ¶
func BuildAuthMethod(auth AuthConfig) (transport.AuthMethod, error)
BuildAuthMethod resolves AuthConfig to a go-git transport.AuthMethod.
Order of preference:
- Explicit SSHKey path → public-key auth.
- Explicit Username + Password → HTTP basic.
- $GITHUB_TOKEN / $GIT_TOKEN env var → HTTP basic with username="oauth2", password=<token>. This is GitHub's documented token-over-HTTPS idiom and lets a Windows user set one env var instead of wiring a credential helper.
Returns (nil, nil) for the "no auth" case (public clones over HTTPS, or SSH against a host trusted via ~/.ssh/known_hosts + ssh-agent).
func Log ¶
func Log(opts LogOptions) (*Result, []LogEntry, error)
Log returns the first opts.Number commits walking back from HEAD.
func Remotes ¶
func Remotes(repoPath string) (*Result, []RemoteEntry, error)
Remotes lists the configured remotes for repoPath.
func Show ¶
func Show(opts ShowOptions) (*Result, *ShowResult, error)
Show resolves opts.Commit (defaulting to HEAD) and returns its metadata.
func Status ¶
func Status(repoPath string) (*Result, []StatusEntry, error)
Status returns the working-tree state of repoPath. When the tree is clean, entries is nil and Result.Message says so; otherwise entries has one row per changed file. Callers use entries == nil as the clean signal.
func StatusCode ¶
func StatusCode(status gogit.StatusCode) string
StatusCode renders a go-git StatusCode as the XY pair upstream git uses in `git status --short`.
Types ¶
type AddOptions ¶
AddOptions configures an Add call.
type AuthConfig ¶
AuthConfig is the set of credentials the user can supply. Empty fields mean "not provided"; BuildAuthMethod resolves the final auth method, including env-var fallbacks.
type BranchOptions ¶
BranchOptions configures a Branch call.
type CheckoutOptions ¶
CheckoutOptions configures a Checkout call.
type CloneOptions ¶
type CloneOptions struct {
URL string
Path string
Depth int
Branch string // ref name to check out after clone (branch or tag); empty = remote HEAD
SingleBranch bool // when true with Branch, fetch only that ref
Auth AuthConfig
Progress io.Writer
}
CloneOptions configures a Clone call.
type CommitOptions ¶
type CommitOptions struct {
RepoPath string
Message string
Amend bool
All bool
AuthorName string
AuthorEmail string
}
CommitOptions configures a Commit call. AuthorName / AuthorEmail override the repo's configured identity; when both are empty the underlying go-git fallback to repo/global config applies and will surface a "user.name / user.email not configured" error if absent.
type FetchOptions ¶
type FetchOptions struct {
RepoPath string
Remote string
Auth AuthConfig
}
FetchOptions configures a Fetch call.
type LogOptions ¶
LogOptions configures a Log call.
type PullOptions ¶
type PullOptions struct {
RepoPath string
Remote string
Branch string
Auth AuthConfig
}
PullOptions configures a Pull call.
type PushOptions ¶
type PushOptions struct {
RepoPath string
Remote string
Branch string
Force bool
Auth AuthConfig
}
PushOptions configures a Push call.
type RemoteEntry ¶
RemoteEntry is one configured remote.
type Result ¶
Result captures the outcome of a single git operation. Message is human-readable; library callers that need machine-readable status should branch on the per-operation return type (e.g. []LogEntry).
func Add ¶
func Add(opts AddOptions) (*Result, error)
Add stages Path (or everything when All is set).
func Branch ¶
func Branch(opts BranchOptions) (*Result, []string, error)
Branch lists branches when Name is empty, creates a new branch when Name is set, or deletes it when Delete is set.
func Checkout ¶
func Checkout(opts CheckoutOptions) (*Result, error)
Checkout switches the working tree to opts.Branch, optionally creating it first when Create is set.
func Clone ¶
func Clone(opts CloneOptions) (*Result, error)
Clone clones URL into Path (or filepath.Base(URL) with .git stripped when Path is empty).
func Commit ¶
func Commit(opts CommitOptions) (*Result, error)
Commit records a new commit (or amends HEAD when Amend is set).
func Fetch ¶
func Fetch(opts FetchOptions) (*Result, error)
Fetch fetches refs from opts.Remote without updating the working tree.
func Init ¶
func Init(opts InitOptions) (*Result, error)
Init creates an empty repository at Path (or cwd when Path is empty).
func Pull ¶
func Pull(opts PullOptions) (*Result, error)
Pull pulls opts.Remote/opts.Branch into the working tree.
func Push ¶
func Push(opts PushOptions) (*Result, error)
Push pushes the current HEAD branch to opts.Remote/opts.Branch.
type RevParseOptions ¶
type RevParseOptions struct {
RepoPath string
// Short, when > 0, abbreviates the SHA to that many leading hex
// chars. 0 means full 40-char SHA.
Short int
}
RevParseOptions configures a RevParse call.
type RevParseResult ¶
RevParseResult is the output of resolving HEAD: the full SHA, a short (abbreviated) form (when Short > 0), and a Dirty flag computed from the worktree status. Build scripts use this to stamp the binary with the source commit + dirty state without shelling out to system git — that's the load-bearing case on Windows hosts where outpost rebuilds itself with only a Go toolchain installed.
func RevParse ¶
func RevParse(opts RevParseOptions) (*RevParseResult, error)
RevParse resolves HEAD of the repo at opts.RepoPath (default ".") and reports whether the worktree is dirty (any staged or unstaged change relative to HEAD). When opts.Short > 0, Short is filled with the abbreviated SHA; otherwise Short is empty.
type ShowOptions ¶
ShowOptions configures a Show call.
type ShowResult ¶
ShowResult is the parsed view of one commit.
type StatusEntry ¶
StatusEntry is one file's status in the working tree.