git

package
v2.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 4, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package git is a thin wrapper over the git CLI. It is the only place in tbd that shells out to git; every other package works through these primitives so behavior is easy to test against throwaway repositories.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NowRFC3339 

func NowRFC3339() string

NowRFC3339 exists so callers can use one timestamp format consistently for git-visible metadata.

Types

type Commit 

type Commit struct {
	Short   string
	Subject string
}

Commit is a short sha plus its subject line.

type GraphCommit added in v2.1.0 

type GraphCommit struct {
	SHA     string
	Short   string
	Parents []string
	Author  string
	Email   string
	Unix    int64
	Subject string
}

GraphCommit is a commit node with enough metadata for a browser visualizer.

type GraphRef added in v2.1.0 

type GraphRef struct {
	Full       string
	Short      string
	ObjectType string
	Target     string
}

GraphRef is a git ref resolved to the commit it points at. For annotated tags, Target is the peeled object rather than the tag object.

type Repo 

type Repo struct{ Dir string }

Repo binds a working directory so callers need not repeat it.

func Open 

func Open(dir string) (*Repo, error)

Open returns a Repo for dir after verifying it is inside a git work tree.

func (*Repo) AheadBehind 

func (r *Repo) AheadBehind(a, b string) (ahead, behind int, err error)

AheadBehind returns how many commits a is ahead of and behind b.

func (*Repo) BranchCreate 

func (r *Repo) BranchCreate(name, start string) error

BranchCreate creates a branch at start without checking it out.

func (*Repo) BranchCreateForce 

func (r *Repo) BranchCreateForce(name, start string) error

BranchCreateForce creates or moves a local branch to start.

func (*Repo) BranchDelete 

func (r *Repo) BranchDelete(name string) error

BranchDelete removes a local branch (force).

func (*Repo) BranchesContaining 

func (r *Repo) BranchesContaining(sha string) []string

BranchesContaining returns the local branches whose history includes sha.

func (*Repo) Checkout 

func (r *Repo) Checkout(ref string) error

Checkout switches the working tree to ref.

func (*Repo) CheckoutCreate 

func (r *Repo) CheckoutCreate(name, start string) error

CheckoutCreate creates and switches to a new branch at start.

func (*Repo) CherryPick 

func (r *Repo) CherryPick(ref string) error

CherryPick replays ref's commit onto the current branch, keeping its message.

func (*Repo) CherryPickAbort 

func (r *Repo) CherryPickAbort() error

CherryPickAbort cancels an in-progress cherry-pick.

func (*Repo) CherryPickContinue 

func (r *Repo) CherryPickContinue() error

CherryPickContinue resumes a stopped cherry-pick without opening an editor.

func (*Repo) CherryPickInProgress 

func (r *Repo) CherryPickInProgress() bool

CherryPickInProgress reports whether a cherry-pick stopped on a conflict.

func (*Repo) Commit 

func (r *Repo) Commit(msg string) error

Commit creates a commit from the staged changes with the given message.

func (*Repo) CommitAmend 

func (r *Repo) CommitAmend(msg string) error

CommitAmend folds staged changes into the current commit. An empty msg keeps the existing message; otherwise it replaces it. --allow-empty so a pure re-sync (no staged changes) still succeeds.

func (*Repo) CommitInteractive 

func (r *Repo) CommitInteractive(amend bool, seed string) error

CommitInteractive makes a commit that opens the user's editor for the message, inheriting the terminal. With amend it rewords/folds into the current commit; a non-empty seed pre-fills the editor (used when squashing, to start from the kept message).

func (*Repo) CommitOf 

func (r *Repo) CommitOf(ref string) string

CommitOf returns the commit ref points at, or "" if it does not resolve.

func (*Repo) CommitTree 

func (r *Repo) CommitTree(tree, msg string) (string, error)

CommitTree creates an orphan commit with msg and returns its object id.

func (*Repo) CommitterName 

func (r *Repo) CommitterName(ref string) string

CommitterName returns the committer name of ref's tip ("" on error).

func (*Repo) ConfigGet 

func (r *Repo) ConfigGet(key string) string

ConfigGet returns a git config value, or "" when it is unset.

func (*Repo) ConfigSet 

func (r *Repo) ConfigSet(key, value string) error

ConfigSet writes a repository-local git config value.

func (*Repo) ConflictingBranch 

func (r *Repo) ConflictingBranch(branch string) (string, bool)

ConflictingBranch returns an existing local branch that would block creating branch because of git's directory/file ref layout: you cannot have both "a/b" (a file) and "a" or "a/b/c" (a needs "a/" to be a directory). It returns the conflicting branch and true, or "" and false when branch is creatable.

func (*Repo) CurrentBranch 

func (r *Repo) CurrentBranch() (string, error)

CurrentBranch returns the checked-out branch name, erroring on detached HEAD.

func (*Repo) DecoratedGraph 

func (r *Repo) DecoratedGraph(limit int) (string, error)

DecoratedGraph returns a compact decorated graph with all refs. It is meant as raw material for tbd's richer horizon views.

func (*Repo) DeleteRef 

func (r *Repo) DeleteRef(name string) error

DeleteRef removes a local ref.

func (*Repo) EmptyTree 

func (r *Repo) EmptyTree() (string, error)

EmptyTree returns git's canonical empty tree object id.

func (*Repo) Exists 

func (r *Repo) Exists(ref string) bool

Exists reports whether ref resolves to anything.

func (*Repo) FFMerge 

func (r *Repo) FFMerge(ref string) error

FFMerge fast-forwards the current branch to ref, refusing a merge commit.

func (*Repo) Fetch 

func (r *Repo) Fetch(remote string) error

Fetch updates remote-tracking refs and prunes deleted ones.

func (*Repo) FetchTags 

func (r *Repo) FetchTags(remote string) error

FetchTags updates local tags from the remote, overwriting moved ones so lease status reflects the authoritative remote position.

func (*Repo) FullMessage 

func (r *Repo) FullMessage(ref string) string

FullMessage returns ref's complete commit message ("" on error).

func (*Repo) GitDir 

func (r *Repo) GitDir() (string, error)

GitDir returns the absolute path to this repository's .git directory, used to stash tbd's own per-repo state (e.g. a pending operation to resume).

func (*Repo) GraphCommits added in v2.1.0 

func (r *Repo) GraphCommits(limit int) ([]GraphCommit, error)

GraphCommits returns commits reachable from HEAD and all refs, newest first in topological order. Parent SHAs are full-length IDs so callers can build edges without depending on git-log's ASCII graph output.

func (*Repo) GraphRefs added in v2.1.0 

func (r *Repo) GraphRefs() ([]GraphRef, error)

GraphRefs returns local branches, remote-tracking branches, tags, stash, and tbd-owned refs. Missing namespaces are not errors.

func (*Repo) HasRemote 

func (r *Repo) HasRemote(remote string) bool

HasRemote reports whether the named remote is configured.

func (*Repo) HasStaged 

func (r *Repo) HasStaged() bool

HasStaged reports whether the index has staged changes.

func (*Repo) IsAncestor 

func (r *Repo) IsAncestor(a, b string) bool

IsAncestor reports whether a is an ancestor of (or equal to) b. This is the core invariant primitive.

func (*Repo) IsClean 

func (r *Repo) IsClean() (bool, error)

IsClean reports whether the working tree has no uncommitted changes.

func (*Repo) ListBranches 

func (r *Repo) ListBranches(pattern string) ([]string, error)

ListBranches returns local branch names matching pattern (glob, e.g. "feature/*"). An empty result is not an error.

func (*Repo) ListTags 

func (r *Repo) ListTags(pattern string) ([]string, error)

ListTags returns tag names matching pattern (glob).

func (*Repo) LogRange 

func (r *Repo) LogRange(revRange string) ([]Commit, error)

LogRange returns commits in revRange (e.g. "fork..head"), newest first.

func (*Repo) MergeBase 

func (r *Repo) MergeBase(a, b string) (string, error)

MergeBase returns the best common ancestor of a and b.

func (*Repo) PushBranch 

func (r *Repo) PushBranch(remote, branch string) error

PushBranch pushes a local branch to remote (never forced; trunk must fast-forward).

func (*Repo) PushBranchCAS 

func (r *Repo) PushBranchCAS(remote, branch, expected string) error

PushBranchCAS publishes a branch with --force-with-lease using an explicit expected remote value (empty means "expect the branch to be absent"), setting upstream. Force is required because tbd rewrites feature history on every commit; the explicit lease makes it a true compare-and-swap that survives a preceding fetch, so a teammate's push is never clobbered.

func (*Repo) PushBranchForce 

func (r *Repo) PushBranchForce(remote, branch string) error

PushBranchForce publishes a branch with an unconditional force (the escape hatch when the lease check is in the way).

func (*Repo) PushDeleteBranch 

func (r *Repo) PushDeleteBranch(remote, branch string) error

PushDeleteBranch deletes a branch on the remote.

func (*Repo) PushDeleteRef 

func (r *Repo) PushDeleteRef(remote, ref string) error

PushDeleteRef removes any remote ref.

func (*Repo) PushDeleteTag 

func (r *Repo) PushDeleteTag(remote, tag string) error

PushDeleteTag deletes a remote tag.

func (*Repo) PushRefCAS 

func (r *Repo) PushRefCAS(remote, ref, expected string) error

PushRefCAS publishes a local ref to the same remote ref name using an explicit compare-and-swap value. expected may be empty when the remote ref is expected not to exist.

func (*Repo) PushTag 

func (r *Repo) PushTag(remote, tag string) error

PushTag pushes a tag to the remote without forcing (for fresh release tags).

func (*Repo) PushTagCAS 

func (r *Repo) PushTagCAS(remote, tag, expectedOld string) error

PushTagCAS pushes a tag using compare-and-swap: the push succeeds only if the remote tag is still at expectedOld (use "" when the tag should not yet exist). This is the sole mutual-exclusion primitive a lease relies on.

func (*Repo) PushTagForce 

func (r *Repo) PushTagForce(remote, tag string) error

PushTagForce pushes a tag with an unconditional force (the escape hatch when tag-push is set to "force" or :force is passed).

func (*Repo) Rebase 

func (r *Repo) Rebase(onto string) error

Rebase replays the current branch onto onto.

func (*Repo) RebaseAbort 

func (r *Repo) RebaseAbort() error

RebaseAbort cancels an in-progress rebase (best effort).

func (*Repo) RebaseContinue 

func (r *Repo) RebaseContinue() error

RebaseContinue resumes a stopped rebase without opening an editor (the existing commit message is kept).

func (*Repo) RebaseInProgress 

func (r *Repo) RebaseInProgress() bool

RebaseInProgress reports whether a rebase is currently stopped (e.g. waiting on conflict resolution).

func (*Repo) RefMessage 

func (r *Repo) RefMessage(ref string) string

RefMessage returns the full commit message at ref, or "" when ref is absent or not a commit.

func (*Repo) RefSha 

func (r *Repo) RefSha(ref string) string

RefSha returns the raw object sha a ref points at, without peeling (so an annotated tag yields the tag object, which is what --force-with-lease compares against). Returns "" when the ref does not exist.

func (*Repo) ReflogContains 

func (r *Repo) ReflogContains(branch, sha string) bool

ReflogContains reports whether branch's reflog ever pointed at sha. This is how we recognize a commit that used to be on the working branch before an amend or rebase rewrote it (a now-orphaned "ours"). Best effort: the reflog is local and expires.

func (*Repo) RemoteBranchSha 

func (r *Repo) RemoteBranchSha(remote, branch string) string

RemoteBranchSha returns the sha the remote currently has for a branch, or "" if the remote does not have it.

func (*Repo) RemoteHasBranch 

func (r *Repo) RemoteHasBranch(remote, branch string) bool

RemoteHasBranch reports whether the remote currently has the named branch.

func (*Repo) RemoteRefSha 

func (r *Repo) RemoteRefSha(remote, ref string) string

RemoteRefSha returns the raw sha the remote currently has for ref.

func (*Repo) RemoteTagSha 

func (r *Repo) RemoteTagSha(remote, tag string) string

RemoteTagSha returns the raw sha the remote has for tag, or "" if absent.

func (*Repo) ResetHard 

func (r *Repo) ResetHard(ref string) error

ResetHard moves the current branch and working tree to ref.

func (*Repo) ResetSoft 

func (r *Repo) ResetSoft(ref string) error

ResetSoft moves HEAD to ref while keeping the index and working tree, so the combined content can be re-committed as one.

func (*Repo) RevList 

func (r *Repo) RevList(args ...string) ([]string, error)

RevList returns commit shas in newest-first order for a rev-list expression.

func (*Repo) RevParse 

func (r *Repo) RevParse(ref string) (string, error)

RevParse resolves ref to a full commit sha, erroring if it does not exist.

func (*Repo) RevertNoEdit 

func (r *Repo) RevertNoEdit(ref string) error

RevertNoEdit reverts ref into the current branch using git's default revert message. The caller is responsible for ensuring the working tree is clean.

func (*Repo) Root 

func (r *Repo) Root() (string, error)

Root returns the repository work-tree root.

func (*Repo) Short 

func (r *Repo) Short(ref string) (string, error)

Short returns the abbreviated sha for ref.

func (*Repo) StageAll 

func (r *Repo) StageAll() error

StageAll stages every change in the working tree (tracked and untracked).

func (*Repo) Subject 

func (r *Repo) Subject(ref string) string

Subject returns the first line of ref's commit message ("" on error).

func (*Repo) TagAnnotated 

func (r *Repo) TagAnnotated(name, ref, msg string) error

TagAnnotated creates or moves an annotated tag at ref, recording msg. The tagger identity (git config user) becomes the lease holder record.

func (*Repo) TagDelete 

func (r *Repo) TagDelete(name string) error

TagDelete removes a local tag.

func (*Repo) TagInfo 

func (r *Repo) TagInfo(name string) (TagDetail, bool)

TagInfo returns details for a tag, or ok=false if it does not exist.

func (*Repo) TagLightweight 

func (r *Repo) TagLightweight(name, ref string) error

TagLightweight creates or moves a lightweight tag at ref.

func (*Repo) UnmergedPaths 

func (r *Repo) UnmergedPaths() ([]string, error)

UnmergedPaths lists files that still have unresolved conflicts.

func (*Repo) UpdateRef 

func (r *Repo) UpdateRef(name, value string) error

UpdateRef sets a ref to a value (creates it if absent).

func (*Repo) ValidBranchName 

func (r *Repo) ValidBranchName(branch string) bool

ValidBranchName reports whether branch is a well-formed git branch name (no spaces, control chars, "..", trailing "/", etc.), per git check-ref-format. branch is the full branch name (e.g. "feature/login"); it is validated as the ref "refs/heads/<branch>" so leading-dash and @{...} components are rejected rather than reinterpreted.

func (*Repo) ValidTagName 

func (r *Repo) ValidTagName(tag string) bool

ValidTagName reports whether tag is a well-formed git tag name, per git check-ref-format (validated as "refs/tags/<tag>").

type TagDetail 

type TagDetail struct {
	Name    string
	Short   string
	Tagger  string
	Date    string
	Subject string
}

TagDetail is the resolved state of a tag.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.