Help us shape the future of Go! Take the 2026 Go Developer Survey

forge

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package forge connects git-stack to the host of a repository through a provider plugin, or to no host at all (provider "none").

Index

Constants

View Source
const (
	// Marker is searched for to find stacks on the host.
	Marker = "git-stack:begin"
	// LegacyMarker starts blocks written by glab-stax, which are still read.
	LegacyMarker = "glab-stax:begin"
	// RepoURL is git-stack's home page, linked from every block.
	RepoURL = "https://gitlab.com/malephex/git-stack"
)
View Source
const (
	StateOpen    = protocol.StateOpen
	StateClosed  = protocol.StateClosed
	StateMerged  = protocol.StateMerged
	StateMerging = protocol.StateMerging
)

CR states.

View Source
const ConfigKey = "git-stack.provider"

ConfigKey is the git config key that pins a repository's provider.

View Source
const None = "none"

None is the provider used when the host is unknown: plain git, no CRs.

Variables

View Source
var NoneInfo = Info{
	Name:     None,
	Protocol: protocol.Version,
	Terms:    protocol.Terms{Short: "PR", Long: "pull request", Ref: "#%d"},
}

NoneInfo describes provider "none".

Functions

func Describe

func Describe(t Transport) (*protocol.Info, error)

Describe asks a plugin for its Info.

func Detect

func Detect(t Transport, repo protocol.Repo) bool

Detect asks a plugin whether repo is hosted where it works.

func GuessProvider

func GuessProvider(host string) string

GuessProvider names the provider for host from its name alone: a known public host, an Azure DevOps organization (<org>.visualstudio.com), or a self-hosted one whose first label names the product (github.example.com, gitlab.example.com). It returns "" if it cannot tell.

func SSHHostname

func SSHHostname(host string) string

SSHHostname resolves an ssh config alias (e.g. "work-gitlab") to its real hostname with `ssh -G`. It returns host unchanged if it looks like a real hostname or cannot be resolved.

func SetBlock

func SetBlock(desc, block string) string

SetBlock replaces the stack block in desc, or appends it.

func StripBlock

func StripBlock(desc string) string

StripBlock removes the stack block from desc. Text before and after a block in the middle stays in separate paragraphs.

Types

type Block

type Block struct {
	Style string // a protocol.Block* constant; "" is BlockHTMLComment
	Short string // e.g. PR
	// Ref writes a reference to CR n, e.g. "!12" or a Markdown link.
	Ref func(n int) string
}

Block renders stack blocks for one forge.

func (Block) Render

func (b Block) Render(info StackInfo, self int) string

Render renders the stack block for the CR numbered self.

type Branch

type Branch = protocol.Branch

Type aliases keep the core's code short; the types live in pkg/protocol so that plugins outside this module can use them.

type CR

type CR = protocol.CR

Type aliases keep the core's code short; the types live in pkg/protocol so that plugins outside this module can use them.

type DetectCache

type DetectCache interface {
	Get(host string) (provider string, ok bool)
	Set(host, provider string)
}

DetectCache stores the outcome of asking plugins about a host.

type FileCache

type FileCache struct {
	Path string
	Now  func() time.Time
}

FileCache is a DetectCache in a JSON file, e.g. in the git common dir.

func (FileCache) Get

func (c FileCache) Get(host string) (string, bool)

Get returns the provider recorded for host, if it is recent.

func (FileCache) Set

func (c FileCache) Set(host, provider string)

Set records provider for host. Failures are ignored: the cache only saves time.

type Finder

type Finder struct {
	// Dirs are searched before PATH, e.g. the directory of git-stack itself.
	Dirs []string
}

Finder locates provider plugins.

func DefaultFinder

func DefaultFinder() Finder

DefaultFinder searches next to the running executable, then PATH.

func (Finder) Find

func (f Finder) Find(provider string) (string, error)

Find returns the path of the plugin for provider.

func (Finder) Installed

func (f Finder) Installed() []string

Installed lists the providers that have a plugin, sorted by name.

type Forge

type Forge struct {
	protocol.Provider
	Info Info
	Repo Repo
}

Forge is a provider bound to one repository.

func New

func New(t Transport, info Info, repo Repo) *Forge

New binds a plugin, reached through t, to repo.

func NewNone

func NewNone(repo Repo) *Forge

NewNone returns the git-only forge.

func (*Forge) Block

func (f *Forge) Block(url func(n int) string) Block

Block returns the block renderer for f. url returns a CR's web URL, or "", for hosts without a short reference syntax.

func (*Forge) HasCRs

func (f *Forge) HasCRs() bool

HasCRs reports whether the forge manages change requests at all.

func (*Forge) HostName

func (f *Forge) HostName() string

HostName is a display name for the host, e.g. GitHub.

func (*Forge) Long

func (f *Forge) Long() string

Long is the host's name for a CR, e.g. pull request or merge request.

func (*Forge) Ref

func (f *Forge) Ref(n int) string

Ref formats CR number n the way the host writes it, e.g. #12 or !12.

func (*Forge) Short

func (f *Forge) Short() string

Short is the host's abbreviation for a CR, e.g. PR or MR.

type Info

type Info = protocol.Info

Type aliases keep the core's code short; the types live in pkg/protocol so that plugins outside this module can use them.

type NewCR

type NewCR = protocol.NewCR

Type aliases keep the core's code short; the types live in pkg/protocol so that plugins outside this module can use them.

type Repo

type Repo = protocol.Repo

Type aliases keep the core's code short; the types live in pkg/protocol so that plugins outside this module can use them.

func ParseRemoteURL

func ParseRemoteURL(raw string) (Repo, error)

ParseRemoteURL extracts host and project path from a git remote URL (https, ssh:// or scp-like git@host:path).

type RepoSettings

type RepoSettings = protocol.RepoSettings

Type aliases keep the core's code short; the types live in pkg/protocol so that plugins outside this module can use them.

type Resolver

type Resolver struct {
	Finder Finder
	// Explicit is the provider chosen by flag or git config; "" to detect.
	Explicit string
	// Warn reports a fallback to provider none.
	Warn func(format string, args ...any)
	// Transport overrides how plugins are run (tests).
	Transport func(path string) Transport
	// Cache remembers which provider claimed an unknown host ("none" if no
	// plugin did), so plugins are not asked on every command. It may be nil.
	Cache DetectCache
}

Resolver picks the provider for a repository.

func (Resolver) Resolve

func (r Resolver) Resolve(remoteURL string) (*Forge, error)

Resolve returns the forge for remoteURL. An explicitly chosen provider must be installed; a detected one falls back to "none" with a warning.

type StackInfo

type StackInfo struct {
	Version int         `json:"v"`
	Trunk   string      `json:"trunk"`
	Items   []StackItem `json:"crs"` // bottom first
}

StackInfo is the machine-readable part of the block in each CR description.

func ParseBlock

func ParseBlock(desc string) (*StackInfo, bool)

ParseBlock extracts stack info from a CR description.

func (*StackInfo) Branches

func (s *StackInfo) Branches() []string

Branches returns the branch of every item, bottom first.

func (*StackInfo) UnmarshalJSON

func (s *StackInfo) UnmarshalJSON(data []byte) error

UnmarshalJSON also reads the glab-stax format ("mrs" of {"iid", "branch"}).

type StackItem

type StackItem struct {
	Number int    `json:"n"`
	Branch string `json:"branch"`
}

StackItem is one CR of a stack.

type Transport

type Transport func(op string, req protocol.Request) (protocol.Response, error)

Transport runs one operation of a provider plugin.

func ExecTransport

func ExecTransport(path string) Transport

ExecTransport runs the plugin executable at path.

func LocalTransport

func LocalTransport(p protocol.Plugin) Transport

LocalTransport runs p in this process, through the same JSON encoding as ExecTransport. Tests use it, and so can built-in providers.

type Update

type Update = protocol.Update

Type aliases keep the core's code short; the types live in pkg/protocol so that plugins outside this module can use them.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL