state

Documentation

Overview

Package state defines and sores the state for gs.

Index

• Variables
• type BranchTx
  • func (tx *BranchTx) Commit(ctx context.Context, msg string) error
  • func (tx *BranchTx) Delete(ctx context.Context, name string) error
  • func (tx *BranchTx) Upsert(ctx context.Context, req UpsertRequest) error
• 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) BeginBranchTx() *BranchTx
  • 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, ts []*CachedTemplate, err 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
• type UpsertRequest

Variables

var ErrNotExist = storage.ErrNotExist

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

var ErrTrunk = errors.New("trunk branch is not allowed")

ErrTrunk is returned when a trunk branch is used in a request that does not allow it.

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

ErrUninitialized indicates that the store is not initialized.

var Null = json.RawMessage("null")

Null is a JSON null value.

Types

type BranchTx

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

BranchTx is an ongoing change to the branch graph. Changes made to it are not persisted until Commit is called. However, in-flight changes are visible to the transaction, so it can use them to prevent cycles and other issues.

func (*BranchTx) Commit

func (tx *BranchTx) Commit(ctx context.Context, msg string) error

Commit persists all planned changes to the store. If there are no changes, this is a no-op.

func (*BranchTx) Delete

func (tx *BranchTx) Delete(ctx context.Context, name string) error

Delete removes information about a branch from the store.

The branch must not be a base for any other branch, or an error will be returned.

func (*BranchTx) Upsert

func (tx *BranchTx) Upsert(ctx context.Context, req UpsertRequest) error

Upsert adds or updates information about a branch. If the branch is not known, it will be added. For new branches, a base MUST be provided.

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

func (s *Store) BeginBranchTx() *BranchTx

BeginBranchTx starts a new transaction for updating the branch graph. Changes are not persisted until Commit is called.

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, ts []*CachedTemplate, err error)

LoadCachedTemplates returns the cached templates and the key used to cache them. Returns ErrNotExist if there are no cached templates.

Caller should check the cache key to ensure the templates are still valid.

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.

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.
	//
	// Use Null to clear the current metadata.
	//
	// Leave this unset to keep the current metadata.
	ChangeMetadata json.RawMessage

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

	// UpstreamBranch is the name of the upstream branch to track.
	// Leave nil to leave it unchanged, or set to an empty string to clear it.
	UpstreamBranch *string
}

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