state

Documentation

Overview

Package state defines and sores the state for gs.

Index

• Variables
• type CachedTemplate
• type Continuation
• type DB
• type InitStoreRequest
• type LookupResponse
• type PreparedBranch
• type Store
  • func InitStore(ctx context.Context, req InitStoreRequest) (*Store, error)
  • func OpenStore(ctx context.Context, db DB, logger *log.Logger) (*Store, error)
  • func (s *Store) AppendContinuations(ctx context.Context, msg string, conts ...Continuation) error
  • func (s *Store) CacheTemplates(ctx context.Context, cacheKey string, ts []*CachedTemplate) error
  • func (s *Store) ClearPreparedBranch(ctx context.Context, name string) error
  • func (s *Store) ListBranches(ctx context.Context) ([]string, error)
  • func (s *Store) LoadCachedTemplates(ctx context.Context, cacheKey string) ([]*CachedTemplate, error)
  • func (s *Store) LoadPreparedBranch(ctx context.Context, name string) (*PreparedBranch, error)
  • func (s *Store) LookupBranch(ctx context.Context, name string) (*LookupResponse, error)
  • func (s *Store) Remote() (string, error)
  • func (s *Store) SavePreparedBranch(ctx context.Context, b *PreparedBranch) error
  • func (s *Store) SetRemote(ctx context.Context, remote string) error
  • func (s *Store) TakeContinuations(ctx context.Context, msg string) ([]Continuation, error)
  • func (s *Store) Trunk() string
  • func (s *Store) UpdateBranch(ctx context.Context, req *UpdateRequest) error
• type UpdateRequest
• type UpsertRequest

Variables

var ErrNotExist = storage.ErrNotExist

ErrNotExist indicates that a key that was expected to exist does not exist.

var ErrUninitialized = errors.New("store not initialized")

ErrUninitialized indicates that the store is not initialized.

Types

type CachedTemplate

type CachedTemplate struct {
	// Filename is the name of the template file.
	//
	// This is NOT the path, and is not guaranteed
	// to correspond to a file on disk.
	Filename string

	// Body is the content of the template file.
	Body string
}

CachedTemplate is a change template cached in the git spice store.

type Continuation

type Continuation struct {
	// Command specifies the arguments for the gs operation
	// that was interrupted.
	Command []string

	// Branch is the branch that the command should be run on.
	Branch string
}

Continuation includes the information needed to resume a rebase operation that was interrupted.

type DB

type DB interface {
	Get(ctx context.Context, k string, v any) error
	Keys(ctx context.Context, dir string) ([]string, error)

	Set(ctx context.Context, k string, v any, msg string) error
	Delete(ctx context.Context, k, msg string) error
	Update(ctx context.Context, req storage.UpdateRequest) error
	Clear(ctx context.Context, msg string) error
}

DB provides a key-value store that holds JSON values.

type InitStoreRequest

type InitStoreRequest struct {
	DB DB

	// Trunk is the name of the trunk branch,
	// e.g. "main" or "master".
	Trunk string

	// Remote is the name of the remote to use for pushing and pulling.
	// e.g. "origin" or "upstream".
	//
	// If empty, a remote will not be configured and push/pull
	// operations will not be available.
	Remote string

	// Reset indicates that the store's state should be nuked
	// if it's already initialized.
	Reset bool

	// Log is the logger to use for logging.
	Log *log.Logger
}

InitStoreRequest is a request to initialize the store in a Git repository.

type LookupResponse

type LookupResponse 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

	// ChangeMetadata holds the metadata for the published change.
	// This is forge-specific and must be deserialized by the forge.
	ChangeMetadata json.RawMessage

	// ChangeForge is the forge that the change was published to.
	ChangeForge string

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

LookupResponse is the response to a Lookup request.

type PreparedBranch

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

	// Subject is the subject of the change that was recorded.
	Subject string

	// Body is the body of the change that was recorded.
	Body string
}

PreparedBranch is a branch that is ready to be submitted.

type Store

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

Store implements storage for state tracked by gs.

func InitStore

func InitStore(ctx context.Context, req InitStoreRequest) (*Store, error)

InitStore initializes the store in the given Git repository. If the repository is already initialized, it will be re-initialized, while retaining existing tracked branches. If Reset is true, existing tracked branches will be cleared.

func OpenStore

func OpenStore(ctx context.Context, db DB, logger *log.Logger) (*Store, error)

OpenStore opens the Store for the given Git repository.

It returns ErrUninitialized if the repository is not initialized.

func (*Store) AppendContinuations

func (s *Store) AppendContinuations(ctx context.Context, msg string, conts ...Continuation) error

AppendContinuations records one or more commands to run when an interrupted rebase operation is resumed. If there are existing continuations, this will append to the list.

func (*Store) CacheTemplates

func (s *Store) CacheTemplates(ctx context.Context, cacheKey string, ts []*CachedTemplate) error

CacheTemplates caches the given templates with the given cache key. If there's existing cached data, it will be overwritten.

func (*Store) ClearPreparedBranch

func (s *Store) ClearPreparedBranch(ctx context.Context, name string) error

ClearPreparedBranch removes the information saved about a branch that was previously saved with SavePreparedBranch. This is a no-op if the branch information isn't saved anymore.

func (*Store) ListBranches

func (s *Store) ListBranches(ctx context.Context) ([]string, error)

ListBranches reports the names of all tracked branches. The list is sorted in lexicographic order.

func (*Store) LoadCachedTemplates

func (s *Store) LoadCachedTemplates(ctx context.Context, cacheKey string) ([]*CachedTemplate, error)

LoadCachedTemplates returns the cached templates if the cache key matches. Returns ErrNotExist if the cache key does not match, or there are no cached templates.

func (*Store) LoadPreparedBranch

func (s *Store) LoadPreparedBranch(ctx context.Context, name string) (*PreparedBranch, error)

LoadPreparedBranch retrieves metadata about a branch submission that was previously saved with SavePreparedBranch. If there's no information saved, it returns nil.

It may be used to recover from past failures in submitting a branch so users do not have to re-enter the change metadata.

func (*Store) LookupBranch

func (s *Store) LookupBranch(ctx context.Context, name string) (*LookupResponse, error)

LookupBranch returns information about a tracked branch. If the branch is not found, ErrNotExist will be returned.

func (*Store) Remote

func (s *Store) Remote() (string, error)

Remote returns the remote configured for the repository. Returns ErrNotExist if no remote is configured.

func (*Store) SavePreparedBranch

func (s *Store) SavePreparedBranch(ctx context.Context, b *PreparedBranch) error

SavePreparedBranch saves information about a branch that is ready for submission. This information may be retrieved later with TakePreparedBranch to recover change metadata in case of failure in submitting. If the branch is already saved, it will be overwritten. Use ClearPreparedBranch to remove the saved information.

func (*Store) SetRemote

func (s *Store) SetRemote(ctx context.Context, remote string) error

SetRemote changes teh remote name configured for the repository.

func (*Store) TakeContinuations

func (s *Store) TakeContinuations(ctx context.Context, msg string) ([]Continuation, error)

TakeContinuations removes all recorded rebase continuations from the store and returns them.

If there are no continuations, it returns an empty slice.

func (*Store) Trunk

func (s *Store) Trunk() string

Trunk reports the trunk branch configured for the repository.

func (*Store) UpdateBranch

func (s *Store) UpdateBranch(ctx context.Context, req *UpdateRequest) error

UpdateBranch upates the store with the parameters in the request.

type UpdateRequest

type UpdateRequest struct {
	// Upserts are requests to add or update information about branches.
	Upserts []UpsertRequest

	// Deletes are requests to delete information about branches.
	Deletes []string

	// Message is a message specifying the reason for the update.
	// This will be persisted in the Git commit message.
	Message string
}

UpdateRequest is a request to add, update, or delete information about branches.

type UpsertRequest

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

	// Base branch to update to.
	//
	// Leave empty to keep the current base.
	Base string

	// BaseHash is the last known hash of the base branch.
	// This is used to detect if the base branch has been updated.
	//
	// Leave empty to keep the current base hash.
	BaseHash git.Hash

	// ChangeMetadata is arbitrary, forge-specific metadata
	// recorded with the branch.
	//
	// Leave this unset to keep the current metadata.
	ChangeMetadata json.RawMessage

	// ChangeForge is the forge that recorded the change.
	//
	// If ChangeMetadata is set, this must also be set.
	ChangeForge string

	// UpstreamBranch is the name of the upstream branch to track.
	// Leave empty to stop tracking an upstream branch.
	UpstreamBranch string
}

UpsertRequest is a request to add or update information about a branch.