forge

package
v0.22.0 Latest Latest
Warning

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

 Go to latest Published: Mar 1, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package forge provides an abstraction layer for git hosting services.

The package supports GitHub (via gh CLI) and GitLab (via glab CLI), enabling wt commands to work seamlessly with both platforms without duplicating logic.

Forge Interface

The Forge interface defines operations for:

  • Fetching PR/MR information for a branch
  • Getting the source branch for a PR number
  • Cloning repositories
  • Creating, viewing, and merging PRs

Platform Detection

Use Detect or [DetectFromRepo] to automatically determine the forge from a repository's origin URL. Detection checks:

  1. Custom host mappings from config (for self-hosted instances)
  2. URL patterns (gitlab.com, gitlab.* domains)
  3. Falls back to GitHub (most common)

Usage 

forge := forge.DetectFromRepo(repoPath, hostMap)
pr, err := forge.GetPRForBranch(originURL, branch)

Platform Differences

Some features have platform-specific limitations:

  • GitLab does not support rebase merge via CLI (only squash and merge)
  • PR state names differ (OPEN/MERGED/CLOSED vs open/merged/closed)
  • Draft PR handling varies between platforms

Any feature involving forge operations must implement both GitHub and GitLab. Never call gh or glab directly outside this package.

Index

Constants

View Source 
const (
	PRStateMerged = "MERGED"
	PRStateOpen   = "OPEN"
	PRStateClosed = "CLOSED"
	PRStateDraft  = "DRAFT"
)

PR state constants (normalized across GitHub/GitLab)

View Source 
const MaxConcurrentFetches = 5

MaxConcurrentFetches limits parallel forge API calls to avoid rate limiting

Variables

This section is empty.

Functions

This section is empty.

Types

type CreatePRParams added in v0.3.0 

type CreatePRParams struct {
	Title string
	Body  string
	Base  string // base branch (empty = repo default)
	Head  string // head/source branch
	Draft bool
}

CreatePRParams contains parameters for creating a PR/MR

type CreatePRResult added in v0.3.0 

type CreatePRResult struct {
	Number int
	URL    string
}

CreatePRResult contains the result of creating a PR/MR

type Forge 

type Forge interface {
	// Name returns the forge name ("github" or "gitlab")
	Name() string

	// Check verifies the CLI is installed and authenticated
	Check(ctx context.Context) error

	// GetPRForBranch fetches PR info for a branch
	GetPRForBranch(ctx context.Context, repoURL, branch string) (*PRInfo, error)

	// GetPRBranch gets the source branch name for a PR number
	GetPRBranch(ctx context.Context, repoURL string, number int) (string, error)

	// CloneRepo clones a repository to destPath, returns the full clone path
	CloneRepo(ctx context.Context, repoSpec, destPath string) (string, error)

	// CloneBareRepo clones a repository as a bare repo inside .git directory.
	// This creates:
	//   destPath/<repo>/
	//   └── .git/    # bare git repo contents (HEAD, objects/, refs/, etc.)
	// Returns the full path to the repo directory.
	CloneBareRepo(ctx context.Context, repoSpec, destPath string) (string, error)

	// CreatePR creates a new PR/MR
	CreatePR(ctx context.Context, repoURL string, params CreatePRParams) (*CreatePRResult, error)

	// MergePR merges a PR by number with the given strategy
	// strategy: "squash", "rebase", or "merge"
	// Returns error if repo doesn't allow the requested merge strategy
	MergePR(ctx context.Context, repoURL string, number int, strategy string) error

	// ViewPR shows PR details or opens in browser
	// If web is true, opens in browser; otherwise shows details in terminal
	ViewPR(ctx context.Context, repoURL string, number int, web bool) error

	// ListOpenPRs lists all open PRs for a repository
	ListOpenPRs(ctx context.Context, repoURL string) ([]OpenPR, error)

	// FormatState returns a human-readable PR state
	FormatState(state string) string
}

Forge represents a git hosting service (GitHub, GitLab, etc.)

func ByNameWithConfig added in v0.8.0 

func ByNameWithConfig(name string, forgeConfig *config.ForgeConfig) Forge

ByNameWithConfig returns a Forge implementation by name with config. Supported names: "github", "gitlab" Returns GitHub as default for unknown names.

func Detect 

func Detect(remoteURL string, hostMap map[string]string, forgeConfig *config.ForgeConfig) Forge

Detect returns the appropriate Forge implementation based on the remote URL. If hostMap is provided, checks for exact domain matches first. Falls back to pattern matching, then defaults to GitHub. If forgeConfig is provided, it's passed to the forge for user lookup.

type GitHub 

type GitHub struct {
	ForgeConfig *config.ForgeConfig
}

GitHub implements Forge for GitHub repositories using the gh CLI.

func (*GitHub) Check 

func (g *GitHub) Check(ctx context.Context) error

Check verifies that gh CLI is available and authenticated

func (*GitHub) CloneBareRepo added in v0.13.0 

func (g *GitHub) CloneBareRepo(ctx context.Context, repoSpec, destPath string) (string, error)

CloneBareRepo clones a GitHub repo as a bare repo inside .git directory

func (*GitHub) CloneRepo 

func (g *GitHub) CloneRepo(ctx context.Context, repoSpec, destPath string) (string, error)

CloneRepo clones a GitHub repo using gh CLI

func (*GitHub) CreatePR added in v0.3.0 

func (g *GitHub) CreatePR(ctx context.Context, repoURL string, params CreatePRParams) (*CreatePRResult, error)

CreatePR creates a new PR using gh CLI

func (*GitHub) FormatState 

func (g *GitHub) FormatState(state string) string

FormatState returns a human-readable PR state

func (*GitHub) GetPRBranch 

func (g *GitHub) GetPRBranch(ctx context.Context, repoURL string, number int) (string, error)

GetPRBranch fetches the head branch name for a PR number using gh CLI

func (*GitHub) GetPRForBranch 

func (g *GitHub) GetPRForBranch(ctx context.Context, repoURL, branch string) (*PRInfo, error)

GetPRForBranch fetches PR info for a branch using gh CLI

func (*GitHub) ListOpenPRs added in v0.10.0 

func (g *GitHub) ListOpenPRs(ctx context.Context, repoURL string) ([]OpenPR, error)

ListOpenPRs lists all open PRs for a repository

func (*GitHub) MergePR 

func (g *GitHub) MergePR(ctx context.Context, repoURL string, number int, strategy string) error

MergePR merges a PR by number with the given strategy

func (*GitHub) Name 

func (g *GitHub) Name() string

Name returns "github"

func (*GitHub) ViewPR added in v0.4.0 

func (g *GitHub) ViewPR(ctx context.Context, repoURL string, number int, web bool) error

ViewPR shows PR details or opens in browser

type GitLab 

type GitLab struct {
	ForgeConfig *config.ForgeConfig
}

GitLab implements Forge for GitLab repositories using the glab CLI. Note: glab doesn't support --user flag like gh, so user field in config is ignored

func (*GitLab) Check 

func (g *GitLab) Check(ctx context.Context) error

Check verifies that glab CLI is available and authenticated

func (*GitLab) CloneBareRepo added in v0.13.0 

func (g *GitLab) CloneBareRepo(ctx context.Context, repoSpec, destPath string) (string, error)

CloneBareRepo clones a GitLab repo as a bare repo inside .git directory

func (*GitLab) CloneRepo 

func (g *GitLab) CloneRepo(ctx context.Context, repoSpec, destPath string) (string, error)

CloneRepo clones a GitLab repo using glab CLI

func (*GitLab) CreatePR added in v0.3.0 

func (g *GitLab) CreatePR(ctx context.Context, repoURL string, params CreatePRParams) (*CreatePRResult, error)

CreatePR creates a new MR using glab CLI

func (*GitLab) FormatState 

func (g *GitLab) FormatState(state string) string

FormatState returns a human-readable PR state

func (*GitLab) GetPRBranch 

func (g *GitLab) GetPRBranch(ctx context.Context, repoURL string, number int) (string, error)

GetPRBranch fetches the source branch name for a PR number using glab CLI

func (*GitLab) GetPRForBranch 

func (g *GitLab) GetPRForBranch(ctx context.Context, repoURL, branch string) (*PRInfo, error)

GetPRForBranch fetches PR info for a branch using glab CLI

func (*GitLab) ListOpenPRs added in v0.10.0 

func (g *GitLab) ListOpenPRs(ctx context.Context, repoURL string) ([]OpenPR, error)

ListOpenPRs lists all open MRs for a repository

func (*GitLab) MergePR 

func (g *GitLab) MergePR(ctx context.Context, repoURL string, number int, strategy string) error

MergePR merges a MR by number with the given strategy

func (*GitLab) Name 

func (g *GitLab) Name() string

Name returns "gitlab"

func (*GitLab) ViewPR added in v0.4.0 

func (g *GitLab) ViewPR(ctx context.Context, repoURL string, number int, web bool) error

ViewPR shows MR details or opens in browser

type OpenPR added in v0.10.0 

type OpenPR struct {
	Number  int
	Title   string
	Author  string
	Branch  string
	IsDraft bool
}

OpenPR represents a PR in a list of open PRs

type PRInfo 

type PRInfo struct {
	Number       int       `json:"number"`
	State        string    `json:"state"`    // Normalized: OPEN, MERGED, CLOSED
	IsDraft      bool      `json:"is_draft"` // true if PR is a draft
	URL          string    `json:"url"`
	Author       string    `json:"author"`        // username/login
	CommentCount int       `json:"comment_count"` // number of comments
	HasReviews   bool      `json:"has_reviews"`   // any reviews submitted
	IsApproved   bool      `json:"is_approved"`   // approved status
	CachedAt     time.Time `json:"cached_at"`
	Fetched      bool      `json:"fetched"` // true = API was queried (distinguishes "not fetched" from "no PR")
}

PRInfo represents pull request information

Source Files

View all Source files

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.