git

package
v0.4.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 8, 2026 License: MIT Imports: 13 Imported by: 0

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

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:

  1. Explicit SSHKey path → public-key auth.
  2. Explicit Username + Password → HTTP basic.
  3. $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

type AddOptions struct {
	RepoPath string
	Path     string
	All      bool
}

AddOptions configures an Add call.

type AuthConfig

type AuthConfig struct {
	Username   string
	Password   string
	SSHKey     string
	SSHKeyPass string
}

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

type BranchOptions struct {
	RepoPath string
	Name     string
	Delete   bool
	Force    bool
}

BranchOptions configures a Branch call.

type CheckoutOptions

type CheckoutOptions struct {
	RepoPath string
	Branch   string
	Create   bool
}

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 InitOptions

type InitOptions struct {
	Path string
}

InitOptions configures an Init call.

type LogEntry

type LogEntry struct {
	Hash    string
	Message string
}

LogEntry is one row of `git log --oneline`.

type LogOptions

type LogOptions struct {
	RepoPath string
	Number   int
}

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

type RemoteEntry struct {
	Name string
	URLs []string
}

RemoteEntry is one configured remote.

type Result

type Result struct {
	Success bool
	Message string
}

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

type RevParseResult struct {
	Hash  string
	Short string
	Dirty bool
}

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

type ShowOptions struct {
	RepoPath string
	Commit   string
}

ShowOptions configures a Show call.

type ShowResult

type ShowResult struct {
	Hash    string
	Author  string
	Email   string
	Date    string
	Message string
}

ShowResult is the parsed view of one commit.

type StatusEntry

type StatusEntry struct {
	File   string
	Status string
	Staged bool
}

StatusEntry is one file's status in the working tree.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL