spice

Documentation

Overview

Package spice intends to provide the core functionality of the tool.

Index

• Variables
• func GenerateBranchName(subject string) string
• type BranchNeedsRestackError
  • func (e *BranchNeedsRestackError) Error() string
• type BranchStore
• type DeletedBranchError
  • func (e *DeletedBranchError) Error() string
• type GitRepository
• type GuessOp
• type Guesser
  • func (g *Guesser) GuessRemote(ctx context.Context, repo GitRepository) (string, error)
  • func (g *Guesser) GuessTrunk(ctx context.Context, repo GitRepository, remote string) (string, error)
• type LoadBranchItem
• type LookupBranchResponse
• type RestackResponse
• type Service
  • func NewService(repo GitRepository, store BranchStore, log *log.Logger) *Service
  • func (s *Service) FindBottom(ctx context.Context, start string) (string, error)
  • func (s *Service) FindTop(ctx context.Context, start string) ([]string, error)
  • func (s *Service) ForgetBranch(ctx context.Context, name string) error
  • func (s *Service) ListAbove(ctx context.Context, base string) ([]string, error)
  • func (s *Service) ListDownstack(ctx context.Context, start string) ([]string, error)
  • func (s *Service) ListStack(ctx context.Context, start string) ([]string, error)
  • func (s *Service) ListUpstack(ctx context.Context, start string) ([]string, error)
  • func (s *Service) LoadBranches(ctx context.Context) ([]LoadBranchItem, error)
  • func (s *Service) LookupBranch(ctx context.Context, name string) (*LookupBranchResponse, error)
  • func (s *Service) RenameBranch(ctx context.Context, oldName, newName string) error
  • func (s *Service) Restack(ctx context.Context, name string) (*RestackResponse, error)
  • func (s *Service) VerifyRestacked(ctx context.Context, name string) error

Variables

var ErrAlreadyRestacked = errors.New("branch is already restacked")

ErrAlreadyRestacked indicates that a branch is already restacked on top of its base.

Functions

func GenerateBranchName

func GenerateBranchName(subject string) string

GenerateBranchName generates a branch name from a commit message subject.

The branch name is generated by converting the subject to lowercase, replacing spaces with hyphens, and removing all non-alphanumeric characters.

If the subject has more than 32 characters, it is truncated to 32 characters at word boundaries.

Types

type BranchNeedsRestackError

type BranchNeedsRestackError struct {
	// Base is the name of the base branch for the branch.
	Base string

	// BaseHash is the hash of the base branch.
	// Note that this is the actual hash, not the hash stored in state.
	BaseHash git.Hash
}

BranchNeedsRestackError is returned by Service.VerifyRestacked when a branch needs to be restacked.

func (*BranchNeedsRestackError) Error

func (e *BranchNeedsRestackError) Error() string

type BranchStore

type BranchStore interface {
	// Lookup returns the branch state for the given branch,
	// or [state.ErrNotExist] if the branch does not exist.
	Lookup(ctx context.Context, name string) (*state.LookupResponse, error)

	// Update adds, updates, or removes state information
	// for zero or more branches.
	Update(ctx context.Context, req *state.UpdateRequest) error

	// List returns a list of all tracked branch names.
	// This list never includes the trunk branch.
	List(ctx context.Context) ([]string, error)

	// Trunk returns the name of the trunk branch.
	Trunk() string
}

BranchStore provides storage for branch state for gs.

It is a subset of the functionality provided by the state.Store type.

type DeletedBranchError

type DeletedBranchError struct {
	Name string

	Base     string
	BaseHash git.Hash
}

DeletedBranchError is returned when a branch was deleted out of band.

This error is used to indicate that the branch does not exist, but its base might.

func (*DeletedBranchError) Error

func (e *DeletedBranchError) Error() string

type GitRepository

type GitRepository interface {
	// MergeBase reports the merge base of the two given commits.
	// This is a commit that is an ancestor of both commits.
	MergeBase(ctx context.Context, a, b string) (git.Hash, error)

	// IsAncestor reports whether commit a is an ancestor of commit b.
	IsAncestor(ctx context.Context, a, b git.Hash) bool

	// ForkPoint reports the git hash at which branch b
	// forked from branch a.
	ForkPoint(ctx context.Context, a, b string) (git.Hash, error)

	// PeelToCommit returns the commit hash for the given commit-ish.
	PeelToCommit(ctx context.Context, ref string) (git.Hash, error)

	// CurrentBranch returns the name of the current branch.
	CurrentBranch(ctx context.Context) (string, error)

	// LocalBranches returns a list of all local branches.
	LocalBranches(ctx context.Context) ([]git.LocalBranch, error)

	// RemoteDefaultBranch reports the default branch of the given remote.
	RemoteDefaultBranch(ctx context.Context, remote string) (string, error)

	// ListRemotes returns the names of all known remotes.
	ListRemotes(ctx context.Context) ([]string, error)

	Rebase(context.Context, git.RebaseRequest) error
	RenameBranch(context.Context, git.RenameBranchRequest) error
	DeleteBranch(context.Context, string, git.BranchDeleteOptions) error
}

GitRepository provides read/write access to the conents of a git repository. It is a subset of the functionality provied by the git.Repository type.

type GuessOp

type GuessOp int

GuessOp specifies the kind of guess operation that the Guesser is performing.

const (
	GuessUnknown GuessOp = iota
	GuessRemote
	GuessTrunk
)

List of guess operations.

type Guesser

type Guesser struct {
	// Select prompts a user to select from a list of options
	// and returns the selected option.
	//
	// selected is the the option that should be selected by default
	// or an empty string if there's no preferred default.
	Select func(op GuessOp, opts []string, selected string) (string, error) // required
}

Guesser attempts to make informed guesses about the state of a repository during initialization.

func (*Guesser) GuessRemote

func (g *Guesser) GuessRemote(ctx context.Context, repo GitRepository) (string, error)

GuessRemote attempts to guess the name of the remote to use for the repository.

It returns an empty string if a remote was not found.

func (*Guesser) GuessTrunk

func (g *Guesser) GuessTrunk(ctx context.Context, repo GitRepository, remote string) (string, error)

GuessTrunk attempts to guess the name of the trunk branch of the repository. If remote is non-empty, it should be the name of the remote for the repository.

type LoadBranchItem

type LoadBranchItem struct {
	// Name is the name of the branch.
	Name string

	// Head is the commit at the head of the branch.
	Head git.Hash

	// Base is the name of the branch that this branch is based on.
	Base string

	// BaseHash is the last known commit hash of the base branch.
	// This may not match the current commit hash of the base branch.
	BaseHash git.Hash

	// PR is the pull request number associated with the branch, if any.
	PR int

	// UpstreamBranch is the name under which this branch
	// was pushed to the upstream repository.
	UpstreamBranch string
}

LoadBranchItem is a single branch returned by LoadBranches.

type LookupBranchResponse

type LookupBranchResponse struct {
	*state.LookupResponse

	// Head is the commit at the head of the branch.
	Head git.Hash
}

LookupBranchResponse is the response to a LookupBranch request. It includes information about the tracked branch.

type RestackResponse

type RestackResponse struct {
	Base string
}

RestackResponse is the response to a restack operation.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service provides the core functionality of the tool. It combines together lower level pieces like access to the git repository and the spice state.

func NewService

func NewService(repo GitRepository, store BranchStore, log *log.Logger) *Service

NewService builds a new service operating on the given repository and store.

func (*Service) FindBottom

func (s *Service) FindBottom(ctx context.Context, start string) (string, error)

FindBottom returns the bottom-most branch in the downstack chain starting at the given branch just before trunk.

Returns an error if no downstack branches are found.

func (*Service) FindTop

func (s *Service) FindTop(ctx context.Context, start string) ([]string, error)

FindTop returns the topmost branches in each upstack chain starting at the given branch.

func (*Service) ForgetBranch

func (s *Service) ForgetBranch(ctx context.Context, name string) error

ForgetBranch stops tracking a branch, updating the upstacks for it to point to its base.

Returns an error matching state.ErrNotExist if the branch is not tracked.

func (*Service) ListAbove

func (s *Service) ListAbove(ctx context.Context, base string) ([]string, error)

ListAbove returns a list of branches that are immediately above the given branch. These are branches that have the given branch as their base. The slice is empty if there are no branches above the given branch.

func (*Service) ListDownstack

func (s *Service) ListDownstack(ctx context.Context, start string) ([]string, error)

ListDownstack lists all branches below the given branch in the downstack chain, not including trunk.

The given branch is the first element in the returned slice, and the bottom-most branch is the last element.

If there are no branches downstack because we're on trunk, or because all branches are downstack from trunk have been deleted, the returned slice will be nil.

func (*Service) ListStack

func (s *Service) ListStack(ctx context.Context, start string) ([]string, error)

ListStack returns the full stack of branches that the given branch is in.

If the start branch has multiple upstack branches, all of them are included in the returned slice. The result is ordered by branch position in the stack with the bottom-most branch as the first element.

func (*Service) ListUpstack

func (s *Service) ListUpstack(ctx context.Context, start string) ([]string, error)

ListUpstack will list all branches that are upstack from the given branch, including those that are upstack from the upstack branches. The given branch is the first element in the returned slice.

The returned slice is ordered by branch position in the upstack. It is guaranteed that for i < j, branch[i] is not a parent of branch[j].

func (*Service) LoadBranches

func (s *Service) LoadBranches(ctx context.Context) ([]LoadBranchItem, error)

LoadBranches loads all tracked branches and all their information as a single operation.

The returned branches are sorted by name.

func (*Service) LookupBranch

func (s *Service) LookupBranch(ctx context.Context, name string) (*LookupBranchResponse, error)

LookupBranch returns information about a branch tracked by gs.

It returns git.ErrNotExist if the branch is nt known to the repository, state.ErrNotExist if the branch is not tracked, or a DeletedBranchError if the branch is tracked, but was deleted out of band.

func (*Service) RenameBranch

func (s *Service) RenameBranch(ctx context.Context, oldName, newName string) error

RenameBranch renames a branch tracked by gs. This handles both, renaming the branch in the repository, and updating the internal state to reflect the new name.

func (*Service) Restack

func (s *Service) Restack(ctx context.Context, name string) (*RestackResponse, error)

Restack restacks the given branch on top of its base branch, handling movement of the base branch if necessary.

Returns ErrAlreadyRestacked if the branch does not need to be restacked.

func (*Service) VerifyRestacked

func (s *Service) VerifyRestacked(ctx context.Context, name string) error

VerifyRestacked verifies that the branch is on top of its base branch. This also updates the base branch hash if the hash is out of date, but the branch is restacked properly.

It returns [ErrNeedsRestack] if the branch needs to be restacked, state.ErrNotExist if the branch is not tracked. Any other error indicates a problem with checking the branch.