spice

package
v0.1.0-beta5 Latest Latest
Warning

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

 Go to latest Published: Jun 17, 2024 License: GPL-3.0 Imports: 14 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

View Source 
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 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)
	RemoteURL(ctx context.Context, remote string) (string, error)

	Rebase(context.Context, git.RebaseRequest) error
	RenameBranch(context.Context, git.RenameBranchRequest) error
	DeleteBranch(context.Context, string, git.BranchDeleteOptions) error
	HashAt(context.Context, string, string) (git.Hash, 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

	// Change is the metadata associated with the branch.
	// This is nil if the branch has not been published.
	Change forge.ChangeMetadata

	// 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 {
	// Base is the base branch configured
	// for the requested branch.
	Base string

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

	// Change is information about the published change
	// associated with the branch.
	//
	// This is nil if the branch hasn't been published yet.
	Change forge.ChangeMetadata

	// UpstreamBranch is the name of the upstream branch
	// or an empty string if the branch is not tracking an upstream branch.
	UpstreamBranch string

	// 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 RebaseRescueRequest 

type RebaseRescueRequest struct {
	// Err is the error that caused the rebase operation to be interrupted.
	Err error

	// Command is the command that should be run
	// after the rebase operation has been rescued.
	//
	// If this is unset, a continuation will NOT be recorded.
	Command []string

	// Branch is the branch on which the command should be run.
	//
	// If this is unset, the continuation will run on the interrupted
	// branch.
	Branch string

	// Message is the message that should be recorded
	// for debugging this continuation.
	Message string // optional
}

RebaseRescueRequest is a request to rescue a rebase operation.

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(ctx context.Context, repo GitRepository, store Store, 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.

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) ListChangeTemplates 

func (s *Service) ListChangeTemplates(ctx context.Context, fr forge.Repository) ([]*forge.ChangeTemplate, error)

ListChangeTemplates returns the Change templates defined in the repository. For GitHub, these are PR templates.

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) RebaseRescue 

func (s *Service) RebaseRescue(ctx context.Context, req RebaseRescueRequest) error

RebaseRescue helps operations continue from rebase conflicts. To use it, call RebaseRescue with the error that caused the rebase operation to be interrupted.

For example: 

func myOperation(...) error {
	if err := repo.Rebase(ctx, ...); err != nil {
		return svc.RebaseRescue(ctx, ...)
	}
	return nil
}

The function returns an error back to the caller so that the program can exit.

For commands that invoke other commands that may be interrupted by a rebase, assuming both commands are idempotent and re-entrant, the parent should also wrap the command in a rebase rescue operation. For example, if we have a leaf operation that rescues: 

func childOperation(...) error {
	if err := repo.Rebase(ctx, ...); err != nil {
		return svc.RebaseRescue(ctx, ...)
	}
	return nil
}

func parentOperation(...) error {
	for _, child := range children {
		if err := childOperation(...); err != nil {
			return svc.RebaseRescue(ctx, ...)
		}
	}
}

Note that this tends to not be necessary for commands that end with a single child operation, e.g. 

func parentOperation(...) error {
	// ...
	return childOperation(...)
}

As at that point, re-running the child operation is sufficient.

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.

type Store 

type Store interface {
	// Trunk returns the name of the trunk branch.
	Trunk() string
	Remote() (string, error)

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

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

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

	AppendContinuations(context.Context, string, ...state.Continuation) error
	TakeContinuations(context.Context, string) ([]state.Continuation, error)

	LoadCachedTemplates(context.Context, string) ([]*state.CachedTemplate, error)
	CacheTemplates(context.Context, string, []*state.CachedTemplate) error
}

Store provides storage for gs. It is a subset of the functionality provided by the state.Store type.

Source Files

View all Source files

Directories

Path Synopsis
Package state defines and sores the state for gs.
 Package state defines and sores the state for gs.

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.