Documentation
¶
Overview ¶
Package gitx is the binary's one door to git. The reads mirror the shell-outs bin/f10-load-project.sh makes - the bash script is the semantics oracle, and shelling out identically keeps the two comparable. The writes are `f10 start`'s - a branch (new, or tracking origin's), a worktree, and the config entries that record what a branch depends on - and `f10 finish`'s, which undoes them once the branch has merged: the pull, the worktree removal, the branch deletion. `f10 drive` adds one: the push of a branch it caught up before merging.
Everything goes through Exec, a variable so a test can answer git without a checkout. No go-git.
Index ¶
- Variables
- func AddWorktree(ctx context.Context, dir, path, branch, base string, create bool) error
- func CommitTree(ctx context.Context, dir, tree string, parents []string, message ...string) (string, error)
- func Config(ctx context.Context, dir, key string) (string, error)
- func CurrentBranch(ctx context.Context, dir string) string
- func DeleteBranch(ctx context.Context, dir, branch string) error
- func DeleteRemoteRef(ctx context.Context, dir, branch string) error
- func Fetch(ctx context.Context, dir string) error
- func FetchInto(ctx context.Context, dir, branch string) error
- func IsAncestor(ctx context.Context, dir, commit, ref string) (bool, error)
- func MergeTree(ctx context.Context, dir, base, head string) (string, error)
- func MergesCleanly(ctx context.Context, dir, base, head string) (bool, error)
- func Out(ctx context.Context, dir string, args ...string) string
- func PullFF(ctx context.Context, dir string) error
- func Push(ctx context.Context, dir, branch, lease string) error
- func Read(ctx context.Context, dir string, args ...string) (string, bool, error)
- func Ref(ctx context.Context, dir, ref string) (string, error)
- func Refs(ctx context.Context, dir string, patterns ...string) ([]string, error)
- func RemoteBranchExists(ctx context.Context, dir, branch string) (bool, error)
- func RemoteBranches(ctx context.Context, dir string) (map[string]string, error)
- func RemoveWorktree(ctx context.Context, dir, path string) error
- func Resolved(p string) string
- func SamePath(a, b string) bool
- func SetConfig(ctx context.Context, dir, key, value string) error
- func Status(ctx context.Context, dir string) ([]string, error)
- func Switch(ctx context.Context, dir, branch string) error
- func TrackBranch(ctx context.Context, dir, branch string, force bool) error
- func UnsetConfig(ctx context.Context, dir, key string) error
- func UpdateRef(ctx context.Context, dir, ref, sha, old string) error
- type ConfigEntry
- type Conflict
- type ExitError
- type Worktree
Constants ¶
This section is empty.
Variables ¶
var Exec = func(ctx context.Context, dir string, args ...string) (string, error) { cmd := exec.CommandContext(ctx, "git", args...) cmd.Dir = dir var stderr strings.Builder cmd.Stderr = &stderr out, err := cmd.Output() if err != nil { if exit, ok := errors.AsType[*exec.ExitError](err); ok && ctx.Err() == nil { return "", &ExitError{ Args: args, Code: exit.ExitCode(), Stdout: strings.TrimSpace(string(out)), Stderr: strings.TrimSpace(stderr.String()), } } if msg := strings.TrimSpace(stderr.String()); msg != "" { return "", fmt.Errorf("git %s: %s", args[0], msg) } return "", fmt.Errorf("git %s: %w", args[0], err) } return strings.TrimSpace(string(out)), nil }
Exec runs git with args in dir and returns trimmed stdout. A non-zero exit is an *ExitError carrying git's own stderr, which names the cause better than any wrapper could, and the code, which Read needs.
Functions ¶
func AddWorktree ¶
AddWorktree checks branch out at path. With create, the branch is made from base - git's HEAD when base is "" - and must not exist yet; otherwise it must.
func CommitTree ¶ added in v0.42.0
func CommitTree(ctx context.Context, dir, tree string, parents []string, message ...string) (string, error)
CommitTree writes a commit of tree on parents with a message of one paragraph per part, and returns its sha. No ref moves.
func CurrentBranch ¶
CurrentBranch is the branch dir has checked out, or "" when detached.
func DeleteBranch ¶
DeleteBranch deletes the local branch whether or not git sees it as merged: a squash or rebase merge leaves no trace git recognises, so the caller's proof is the host's, not git's. The branch's config section goes with it.
func DeleteRemoteRef ¶ added in v0.33.0
DeleteRemoteRef drops the local copy of origin's branch, which a branch deleted through the host's API leaves behind until a pruning fetch. git deletes a ref that is not there without complaint.
func FetchInto ¶
FetchInto updates local branch from origin's branch of the same name without touching the checkout: git fast-forwards a branch that is not checked out and refuses anything else.
func IsAncestor ¶
IsAncestor reports whether commit is reachable from ref: git answers with exit 0 or 1. An unknown object is a no too, since a recorded sha may name a commit squashed away; anything else is an error.
func MergeTree ¶ added in v0.42.0
MergeTree is the tree of head merged into base, built in memory as MergesCleanly tries it; a conflict is an error.
func MergesCleanly ¶ added in v0.33.0
MergesCleanly reports whether head merges into base without a conflict, tried in memory the way a host tries a pull request: nothing is checked out or written. git exits 1 both for a conflict, reported on stdout, and for a ref it cannot merge, reported on stderr, which is an error. Not --quiet: git 2.56 exits 0 with it on a conflict.
func Out ¶
Out runs git and returns trimmed stdout, or "" on any error. It cannot tell "not there" from "git failed", so it is for display only: a read that decides what f10 does next goes through Read.
func PullFF ¶
PullFF fast-forwards the checked-out branch from its upstream, and fails rather than merge when it cannot.
func Push ¶ added in v0.33.0
Push sends HEAD to origin's branch. A lease (the sha origin's branch had when the caller read it) forces the push only while origin still has that sha, which a rebased branch needs; "" pushes a fast-forward and nothing else.
func Read ¶ added in v0.46.0
Read runs a quiet git read: exit 0 is the value and present, exit 1 is absent with no error, and anything else - a lock, a broken worktree, a killed git - is the error. A form whose "not there" exits 128 (a rev-parse --verify without -q) reads absence as an error, which halts rather than proceeds.
func Refs ¶
Refs lists the refs matching patterns, in git's own order, as branch names: `refs/heads/` and `refs/remotes/` stripped, so a remote branch reads `origin/x`. The full refname is asked for rather than the short one, which git disambiguates to `heads/x` when a tag shares the name. A pattern is what for-each-ref takes: a literal ref, which also matches everything under it at a slash, or a glob.
func RemoteBranchExists ¶
RemoteBranchExists asks origin whether it still has branch, which is the one git read here that reaches the network.
func RemoteBranches ¶ added in v0.45.0
RemoteBranches is every branch origin has, name to tip sha, in one network read. A checkout with no origin has none.
func RemoveWorktree ¶
RemoveWorktree removes the checkout at path. A dirty tree makes git refuse, which callers rule out first.
func Resolved ¶ added in v0.46.0
Resolved is the path with symlinks resolved. A component that does not exist - a removed or never-created path - keeps its name below the longest prefix that does, so two spellings of one place still compare.
func SamePath ¶ added in v0.46.0
SamePath compares two worktree paths with symlinks resolved where they exist.
func SetConfig ¶
SetConfig writes one entry to the repository's local config, replacing any value the key held. Local config never leaves the machine, which is what makes it the place for a per-branch fact in stealth mode.
func Status ¶
Status lists what `status --porcelain` reports for dir: one line per changed or untracked path, empty for a clean tree. Ignored files are not listed, so an excluded .f10/ never counts.
func Switch ¶ added in v0.35.0
Switch checks out branch in dir. A dirty tree can make git refuse, which callers rule out first.
func TrackBranch ¶ added in v0.35.0
TrackBranch creates local branch from origin's branch of the same name, tracking it, so a pull or push in its worktree needs no upstream set. With force an existing branch is moved there, which git refuses while a worktree has it checked out.
func UnsetConfig ¶
UnsetConfig removes one entry from the repository's local config.
Types ¶
type ConfigEntry ¶
A ConfigEntry is one key and its value as `config --get-regexp` lists them.
func ConfigEntries ¶
func ConfigEntries(ctx context.Context, dir, pattern string) ([]ConfigEntry, error)
ConfigEntries lists the local config entries whose key matches pattern, in git's order. No match is an empty list, not an error: git exits 1 for it.
type Conflict ¶ added in v0.47.0
A Conflict is one path a merge would conflict on, with the blob each stage brought: 1 the merge base, 2 base's side, 3 head's side, "" where a side lacks the path. Two conflicts on a path are the same conflict only when their blobs are.
func Conflicts ¶ added in v0.47.0
Conflicts is what head conflicts on in base, sorted by path, tried in memory as MergesCleanly does: nil is a clean merge. git exits 1 with the tree and a `<mode> <oid> <stage>\t<path>` line per conflicted stage on stdout, and with its reason on stderr for a ref it cannot merge, which is an error.
type ExitError ¶ added in v0.46.0
An ExitError is git having run and exited non-zero. Stdout is what git printed before exiting, for the reads whose exit 1 carries an answer (merge-tree names the conflicting files that way).
Source Files