gitremote

Documentation

Overview

Package gitremote resolves the CircleCI project slug for the current working directory. Resolution prefers the per-checkout .circleci/info.yml recorded by `circleci project link` (so repository renames and standalone projects stay addressable), falling back to parsing the git remote URL.

Index

• func DetectNamespace() (string, error)
• func DetectRepoName() string
• func RepoRootIn(dir string) (_ string, err error)
• func SlugFromRemote(remoteURL string) (string, error)
• type ProjectInfo
  • func Detect() (*ProjectInfo, error)
  • func DetectFromRemote() (_ *ProjectInfo, err error)
  • func DetectFromRemoteIn(dir string) (_ *ProjectInfo, err error)
• type RemoteRef
  • func DetectRemoteRefIn(dir string) (_ RemoteRef, err error)
  • func (r RemoteRef) FullName() string

Functions

func DetectNamespace

func DetectNamespace() (string, error)

DetectNamespace returns the organization name (namespace) from the git remote. For a slug like "gh/myorg/myrepo" it returns "myorg".

func DetectRepoName

func DetectRepoName() string

DetectRepoName returns a human-readable name for the checkout in the working directory, or "" when none can be determined. Callers use it as the suggested project name.

The git remote is preferred. It is read directly rather than through Detect, which prefers .circleci/info.yml: a linked standalone project's slug is "circleci/<orgID>/<projectID>", so its last segment is an opaque ID — useless as a name to show a user.

When the remote cannot be read — no origin, no origin/HEAD, an unsupported host — the name recorded by `circleci project link` is used instead. That is the only other place a readable name for this checkout exists, and without it a linked repository with no usable remote would offer no name at all.

func RepoRootIn

func RepoRootIn(dir string) (_ string, err error)

RepoRootIn returns the root of the working tree containing dir, or an error when dir is not inside a git repository. An empty dir means the process working directory.

Callers that write files describing the repository use this so that running from a subdirectory records them at the root, where they belong, rather than wherever the command happened to be invoked.

func SlugFromRemote

func SlugFromRemote(remoteURL string) (string, error)

SlugFromRemote is exported for testing.

Types

type ProjectInfo

type ProjectInfo struct {
	// Slug is the CircleCI project slug, e.g. "gh/myorg/myrepo".
	Slug string
	// Branch is the current git branch name.
	Branch string
	// DefaultBranch is the default branch name.
	DefaultBranch string
	// OrgID is the organization ID recorded by `circleci project link`
	// (.circleci/info.yml). It is empty when the project was resolved from the
	// git remote, because the org ID is not derivable from a remote URL without
	// an API lookup. Its form is whatever link persisted (a UUID, or a compact
	// base62 ID); consumers that need a UUID must parse and fall back on failure.
	OrgID string
}

ProjectInfo holds the information needed to identify a CircleCI project.

func Detect

func Detect() (*ProjectInfo, error)

Detect resolves the CircleCI project for the current working directory.

Resolution priority:

1. .circleci/info.yml in the working directory (written by `circleci project link`). When this file carries both project_id and organization_id, the canonical "circleci/<orgID>/<projectID>" slug is returned so lookups survive VCS-side renames; otherwise the file's stored slug is returned verbatim.
2. The git remote "origin" URL.

The branch is always read from git (best-effort when info.yml supplied the slug, since the branch is per-checkout and never persisted in info.yml).

func DetectFromRemote

func DetectFromRemote() (_ *ProjectInfo, err error)

DetectFromRemote resolves the project from the git "origin" remote without consulting .circleci/info.yml. Use this from the `project link` command itself — reading info.yml there would short-circuit the very write that link is about to perform.

func DetectFromRemoteIn

func DetectFromRemoteIn(dir string) (_ *ProjectInfo, err error)

DetectFromRemoteIn is DetectFromRemote scoped to the repository containing dir. An empty dir means the process working directory.

Commands that accept a directory argument must use this: reading the process working directory instead would describe a different repository than the one being operated on — or an enclosing one, since detection walks upward.

type RemoteRef

type RemoteRef struct {
	// Host is the remote's host, e.g. "github.com".
	Host string
	// Owner and Repo name the repository, e.g. "acme" and "web".
	Owner, Repo string
}

RemoteRef identifies a repository as its remote URL names it, before any mapping onto CircleCI's own vocabulary.

func DetectRemoteRefIn

func DetectRemoteRefIn(dir string) (_ RemoteRef, err error)

DetectRemoteRefIn reads the origin remote of the repository containing dir and returns what the URL says, without requiring the host to be one CircleCI has a slug form for.

This is the parse to use when a caller resolves the integration itself (see internal/provider). DetectFromRemoteIn is the slug-producing path, and it rejects any host that has no slug segment.

func (RemoteRef) FullName

func (r RemoteRef) FullName() string

FullName is the "owner/repo" form the provider APIs use as a repository key.