Documentation
¶
Overview ¶
Package gitstatus reads the git state of session checkouts: branch, dirty tree, unpushed commits and the line delta against the default branch.
Index ¶
- Variables
- func DiffBaseNames() []string
- func FileDiffStateNames() []string
- func RemoteCoordinates(remote string) (host, owner, repo string)
- type Changes
- type DiffBase
- type DiffTarget
- type FileDiff
- type FileDiffState
- type Git
- type Options
- type Service
- func (s *Service) Read(ctx context.Context, path string, opts Options) Status
- func (s *Service) ReadBatch(ctx context.Context, paths []string, opts Options) map[string]Status
- func (s *Service) ReadBranches(ctx context.Context, sess session.Session) ([]string, error)
- func (s *Service) ReadChanges(ctx context.Context, sess session.Session, target DiffTarget) (Changes, error)
- func (s *Service) ReadFileDiffs(ctx context.Context, sess session.Session, target DiffTarget, paths []string) ([]FileDiff, error)
- func (s *Service) ReadSession(ctx context.Context, sess session.Session) Status
- func (s *Service) ReadSessions(ctx context.Context, sessions []session.Session) map[string]Status
- type Status
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidDiffBase = fmt.Errorf("not a valid DiffBase, try [%s]", strings.Join(_DiffBaseNames, ", "))
var ErrInvalidFileDiffState = fmt.Errorf("not a valid FileDiffState, try [%s]", strings.Join(_FileDiffStateNames, ", "))
Functions ¶
func DiffBaseNames ¶ added in v0.69.0
func DiffBaseNames() []string
DiffBaseNames returns a list of possible string values of DiffBase.
func FileDiffStateNames ¶ added in v0.69.0
func FileDiffStateNames() []string
FileDiffStateNames returns a list of possible string values of FileDiffState.
func RemoteCoordinates ¶
RemoteCoordinates reads the host, owner and repo off a remote. The host is lowered so a forge match and a cache key are canonical however the remote spells it.
A remote naming no host returns nothing: git.ExtractOwnerRepo is host-agnostic and would read the last two path segments of a local path.
Types ¶
type Changes ¶ added in v0.69.0
type Changes struct {
Resolved bool
Branch string
DefaultBranch string
Base DiffBase
BranchAvailable bool
Against string
Commit string
Commits []git.CommitInfo
Files []git.ChangedFile
Truncated bool
}
Changes is what differs in a session's checkout against a target. Base is the base the read used, which is uncommitted when a branch read has nothing to compare with: on the default branch, or when the default branch or merge base can't be resolved, as in a shallow clone.
Against is the chosen ref a branch read used. It is empty for the default branch, including when a chosen ref no longer resolves. Commit is the full id a commit read showed. Commits lists what the branch added, newest first, or HEAD's recent history when it has no merge base.
type DiffBase ¶ added in v0.69.0
type DiffBase string
ENUM(branch, uncommitted, staged, unstaged, commit)
const ( // DiffBaseBranch is a DiffBase of type branch. DiffBaseBranch DiffBase = "branch" // DiffBaseUncommitted is a DiffBase of type uncommitted. DiffBaseUncommitted DiffBase = "uncommitted" // DiffBaseStaged is a DiffBase of type staged. DiffBaseStaged DiffBase = "staged" // DiffBaseUnstaged is a DiffBase of type unstaged. DiffBaseUnstaged DiffBase = "unstaged" // DiffBaseCommit is a DiffBase of type commit. DiffBaseCommit DiffBase = "commit" )
func ParseDiffBase ¶ added in v0.69.0
ParseDiffBase attempts to convert a string to a DiffBase.
func (*DiffBase) AppendText ¶ added in v0.69.0
AppendText appends the textual representation of itself to the end of b (allocating a larger slice if necessary) and returns the updated slice.
Implementations must not retain b, nor mutate any bytes within b[:len(b)].
func (DiffBase) IsValid ¶ added in v0.69.0
IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values
func (DiffBase) MarshalText ¶ added in v0.69.0
MarshalText implements the text marshaller method.
func (*DiffBase) UnmarshalText ¶ added in v0.69.0
UnmarshalText implements the text unmarshaller method.
type DiffTarget ¶ added in v0.69.0
DiffTarget says what a read compares. Against is the full ref a branch read compares with, and empty means the default branch. Commit is the commit a commit read shows, and empty means HEAD.
type FileDiff ¶ added in v0.69.0
type FileDiff struct {
Path string
State FileDiffState
Text string
Error string
}
FileDiff is one file's diff. Text is the unified diff in FileDiffStateText, and is empty for a rename with no edits. Error is why this one file failed in FileDiffStateError, so it can't blank the rest of a batch.
type FileDiffState ¶ added in v0.69.0
type FileDiffState string
FileDiffState says what a FileDiff holds. Truncated is a diff past the caps. Unavailable is a path with no text to show: a FIFO, a symlink, or a nested repository. Gone is a path no longer in the change list, which is routine: an agent can revert a file between the list and the read.
ENUM(text, binary, truncated, unavailable, gone, error)
const ( // FileDiffStateText is a FileDiffState of type text. FileDiffStateText FileDiffState = "text" // FileDiffStateBinary is a FileDiffState of type binary. FileDiffStateBinary FileDiffState = "binary" // FileDiffStateTruncated is a FileDiffState of type truncated. FileDiffStateTruncated FileDiffState = "truncated" FileDiffStateUnavailable FileDiffState = "unavailable" // FileDiffStateGone is a FileDiffState of type gone. FileDiffStateGone FileDiffState = "gone" // FileDiffStateError is a FileDiffState of type error. FileDiffStateError FileDiffState = "error" )
func ParseFileDiffState ¶ added in v0.69.0
func ParseFileDiffState(name string) (FileDiffState, error)
ParseFileDiffState attempts to convert a string to a FileDiffState.
func (*FileDiffState) AppendText ¶ added in v0.69.0
func (x *FileDiffState) AppendText(b []byte) ([]byte, error)
AppendText appends the textual representation of itself to the end of b (allocating a larger slice if necessary) and returns the updated slice.
Implementations must not retain b, nor mutate any bytes within b[:len(b)].
func (FileDiffState) IsValid ¶ added in v0.69.0
func (x FileDiffState) IsValid() bool
IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values
func (FileDiffState) MarshalText ¶ added in v0.69.0
func (x FileDiffState) MarshalText() ([]byte, error)
MarshalText implements the text marshaller method.
func (FileDiffState) String ¶ added in v0.69.0
func (x FileDiffState) String() string
String implements the Stringer interface.
func (*FileDiffState) UnmarshalText ¶ added in v0.69.0
func (x *FileDiffState) UnmarshalText(text []byte) error
UnmarshalText implements the text unmarshaller method.
type Git ¶
type Git interface {
Branch(ctx context.Context, dir string) (string, error)
IsClean(ctx context.Context, dir string) (bool, error)
HasUnpushedCommits(ctx context.Context, dir string) (bool, error)
DiffStats(ctx context.Context, dir string) (additions, deletions int, err error)
DefaultBranch(ctx context.Context, dir string) (string, error)
MergeBase(ctx context.Context, dir, branch string) (string, error)
MergeBaseRef(ctx context.Context, dir, ref string) (string, error)
ResolveCommit(ctx context.Context, dir, rev string) (string, error)
CommitRange(ctx context.Context, dir, commit string) (git.DiffRange, error)
Commits(ctx context.Context, dir, since string, limit int) ([]git.CommitInfo, error)
Branches(ctx context.Context, dir string, limit int) ([]string, error)
ChangedFiles(ctx context.Context, dir string, diff git.DiffRange) ([]git.ChangedFile, error)
FileDiffs(ctx context.Context, dir string, diff git.DiffRange, files []git.ChangedFile) []git.FileDiffResult
}
Git is the subset of git.Git a status read needs.
type Options ¶
type Options struct {
Unpushed bool
}
Options picks the optional reads. The unpushed check costs up to three git calls, so a caller that does not show it leaves it off.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
func NewService ¶
NewService returns a Service that runs at most workers reads at once in a batch. A workers value below one means one.
func (*Service) Read ¶
Read reads one checkout. A failed branch read stands for the whole status, because every other read needs the working checkout it proves.
func (*Service) ReadBatch ¶
ReadBatch reads every path, each under its own timeout, with at most the service's worker count running at once.
func (*Service) ReadBranches ¶ added in v0.69.0
ReadBranches lists the full refs a session's checkout can compare against. A session with no checkout has none.
func (*Service) ReadChanges ¶ added in v0.69.0
func (s *Service) ReadChanges(ctx context.Context, sess session.Session, target DiffTarget) (Changes, error)
ReadChanges answers the zero Changes for a session with no checkout, as ReadSession does: there is nothing to read, which is not a failure. Files stops at maxChangedFiles.
func (*Service) ReadFileDiffs ¶ added in v0.69.0
func (s *Service) ReadFileDiffs(ctx context.Context, sess session.Session, target DiffTarget, paths []string) ([]FileDiff, error)
ReadFileDiffs returns one FileDiff per path, in order. It reads only paths in the current change list. A session with no checkout reports every path Gone.
func (*Service) ReadSession ¶
ReadSession reads a session's checkout with every read, and adds the remote's coordinates. A session with no checkout (not active, or no path) returns the zero Status: there is nothing to read, which is not a failure.
type Status ¶
type Status struct {
Path string
Branch string
Dirty bool
Unpushed bool
// Additions and Deletions are the working tree against the merge base with
// the default branch.
Additions int
Deletions int
// Host, Owner and Repo are the remote's coordinates. They are empty for a
// remote that names no host, such as a local path.
Host string
Owner string
Repo string
Resolved bool
// Err is the first failed read of the branch, the dirty check or the diff.
Err error
// UnpushedErr is kept apart from Err because a branch with no upstream
// fails this read on every poll, and that must not hide the rest.
UnpushedErr error
}
Status is one checkout's git state.
Resolved separates "git answered" from the zero value. Err carries why a read failed and is never a substitute for it: a failed IsClean leaves Dirty false rather than assuming dirty, because a badge claiming uncommitted work on a git that never ran is a lie the user acts on.
Source Files