ghrepo

README

Additional Information

• Go Reference: API documentation.

Contributing

Contributions are welcome — please open an issue or a pull request on GitHub.

License

This project is licensed under the Apache 2.0 License.

Documentation

Index

• func CloneGit(o *repoConfig)
• func CreateOnGitHub(o *repoConfig)
• func CreateRemote(o *repoConfig)
• func InitGit(o *repoConfig)
• func MakeDirAll(o *repoConfig)
• func OwnerIsOrg(o *repoConfig)
• type ExecError
  • func (e ExecError) Error() string
  • func (e ExecError) Unwrap() error
• type Option
  • func WithBaseDir(baseDir string) Option
  • func WithGithubRepo(r *github.Repository) Option
• type Repository
  • func (r *Repository) Archived() bool
  • func (r *Repository) CheckoutDefault() error
  • func (r *Repository) Commit(paths []string, message string) error
  • func (r *Repository) CommitAll(msg string) error
  • func (r *Repository) CreateRelease(ctx context.Context, release *github.RepositoryRelease) (*github.RepositoryRelease, error)
  • func (r *Repository) Description() string
  • func (r *Repository) Edit(ctx context.Context, update *github.Repository) error
  • func (r *Repository) ExecCommand(ctx context.Context, name string, args ...string) ([]byte, error)
  • func (r *Repository) GetChangedFiles() ([]string, error)
  • func (r *Repository) GitClean() error
  • func (r *Repository) GitReset(mode git.ResetMode) error
  • func (r *Repository) GitStatus() (git.Status, error)
  • func (r *Repository) HasChanges() (bool, error)
  • func (r *Repository) IsDefaultBranch() (bool, error)
  • func (r *Repository) LatestRelease(ctx context.Context) (*github.RepositoryRelease, error)
  • func (r *Repository) LatestReleaseVersion(ctx context.Context) (*semver.Version, error)
  • func (r *Repository) Name() string
  • func (r *Repository) Owner() string
  • func (r *Repository) Private() bool
  • func (r *Repository) Pull(ctx context.Context) error
  • func (r *Repository) Push(ctx context.Context) error
  • func (r *Repository) SetDescription(ctx context.Context, descr string) error
  • func (r *Repository) SetTopics(ctx context.Context, topics []string) error
  • func (r *Repository) String() string
  • func (r *Repository) Topics() []string
  • func (r *Repository) UploadReleaseBinary(ctx context.Context, relID int, path string, info fs.FileInfo, suffix string) error
• type Service
  • func NewService(ctx context.Context, githubToken string, opts ...Option) *Service
  • func (s *Service) NewRepository(ctx context.Context, owner, name string, opts ...Option) (*Repository, error)
  • func (s *Service) PrefetchOrgRepositories(ctx context.Context, org string) error
  • func (s *Service) PrefetchUserRepositories(ctx context.Context, user string) error

Functions

func CloneGit

func CloneGit(o *repoConfig)

CloneGit instructs the initializer to clone git in the repository directory, if it does not exist.

func CreateOnGitHub

func CreateOnGitHub(o *repoConfig)

CreateOnGitHub instructs the initializer to create the repository on GitHub, if it does not exists.

func CreateRemote

func CreateRemote(o *repoConfig)

CreateRemote instructs the initializer to create a remote, if it does not exists.

func InitGit

func InitGit(o *repoConfig)

InitGit instructs the initializer to initialize git in the repository directory, if it was not initialized.

func MakeDirAll

func MakeDirAll(o *repoConfig)

MakeDirAll instructs the initializer to create the repository directory, if it does not exists.

func OwnerIsOrg

func OwnerIsOrg(o *repoConfig)

OwnerIsOrg clarifies that the given owner is not the user, but an organization on GitHub.

Types

type ExecError

type ExecError struct {
	// Cmd is the full command that was attempted (e.g. "go mod tidy").
	Cmd string
	// Out is the combined stdout and stderr output from the command, if any.
	Out string
	// Err is the underlying error returned by exec.Command.
	Err error
}

ExecError represents an error that occurred while executing a command in the repository.

func (ExecError) Error

func (e ExecError) Error() string

Error returns a string representation of the ExecError, including the command, output, and underlying error.

func (ExecError) Unwrap

func (e ExecError) Unwrap() error

Unwrap allows errors.Is and errors.As to work with ExecError by unwrapping the underlying error.

type Option

type Option func(*repoConfig)

Option is a functional option for configuring Repository creation/opening

func WithBaseDir

func WithBaseDir(baseDir string) Option

WithBaseDir sets a custom base directory for the repository. If not set, uses the current directory.

func WithGithubRepo

func WithGithubRepo(r *github.Repository) Option

WithGithubRepo sets the GitHub repository to link to, so that no fetching/creation is needed.

type Repository

type Repository struct {

	// Use the repository folder as its own file system.
	afero.Fs
	// contains filtered or unexported fields
}

Repository represents a local Git repository linked to a GitHub remote.

func (*Repository) Archived

func (r *Repository) Archived() bool

Archived returns whether the repository is archived.

func (*Repository) CheckoutDefault

func (r *Repository) CheckoutDefault() error

CheckoutDefault checks out the default branch (either main or master).

func (*Repository) Commit

func (r *Repository) Commit(paths []string, message string) error

Commit commits all files that match a certain pattern, then commits with the given message.

func (*Repository) CommitAll

func (r *Repository) CommitAll(msg string) error

Commit adds all changes, commits with the given message.

func (*Repository) CreateRelease

func (r *Repository) CreateRelease(ctx context.Context, release *github.RepositoryRelease) (*github.RepositoryRelease, error)

CreateRelease creates a new release for the repository.

func (*Repository) Description

func (r *Repository) Description() string

Description returns the GitHub description of the repository.

func (*Repository) Edit

func (r *Repository) Edit(ctx context.Context, update *github.Repository) error

Edit edits the repository on GitHub.

func (*Repository) ExecCommand

func (r *Repository) ExecCommand(ctx context.Context, name string, args ...string) ([]byte, error)

ExecCommand runs a command in the repository's root directory. It returns the combined stdout + stderr as a string. The command name and arguments are passed separately (like exec.Command).

func (*Repository) GetChangedFiles

func (r *Repository) GetChangedFiles() ([]string, error)

GetChangedFiles returns a list of files that were changed.

func (*Repository) GitClean

func (r *Repository) GitClean() error

GitClean performs a git clean in the repository.

func (*Repository) GitReset

func (r *Repository) GitReset(mode git.ResetMode) error

GitReset performs a git reset in the repository.

func (*Repository) GitStatus

func (r *Repository) GitStatus() (git.Status, error)

GitStatus returns the git status of the repository.

func (*Repository) HasChanges

func (r *Repository) HasChanges() (bool, error)

HasChanges returns true if there are any unstaged, staged, or untracked changes. It returns false only if the working tree is completely clean.

func (*Repository) IsDefaultBranch

func (r *Repository) IsDefaultBranch() (bool, error)

IsDefaultBranch returns true if we are on the default branch.

func (*Repository) LatestRelease

func (r *Repository) LatestRelease(ctx context.Context) (*github.RepositoryRelease, error)

func (*Repository) LatestReleaseVersion

func (r *Repository) LatestReleaseVersion(ctx context.Context) (*semver.Version, error)

func (*Repository) Name

func (r *Repository) Name() string

Name returns the name of the repository.

func (*Repository) Owner

func (r *Repository) Owner() string

Owner returns the owner of the repository, which may either be a user or an organization.

func (*Repository) Private

func (r *Repository) Private() bool

Private reports whether the repository is private on GitHub.

A repository GitHub has told us nothing about counts as private: treating an unknown repository as public is the answer that leaks, so the safe default is the one that holds back.

func (*Repository) Pull

func (r *Repository) Pull(ctx context.Context) error

Pull incorporates changes from a remote repository into the current branch.

func (*Repository) Push

func (r *Repository) Push(ctx context.Context) error

Push pushes to the default remote.

func (*Repository) SetDescription

func (r *Repository) SetDescription(ctx context.Context, descr string) error

SetDescription changes the repository description on GitHub.

func (*Repository) SetTopics

func (r *Repository) SetTopics(ctx context.Context, topics []string) error

SetTopics sets the repository topics on GitHub.

func (*Repository) String

func (r *Repository) String() string

func (*Repository) Topics

func (r *Repository) Topics() []string

Topics returns the GitHub topics of the repository.

func (*Repository) UploadReleaseBinary

func (r *Repository) UploadReleaseBinary(ctx context.Context, relID int,
	path string, info fs.FileInfo, suffix string,
) error

UploadReleaseBinary zips a binary file and uploads it as a release asset to a GitHub release. It also computes a SHA-256 checksum during the upload and uploads a separate checksum file.

The binary is placed inside a zip archive with a single entry. The name of the file inside the zip is the repository name with an optional suffix (e.g., ".exe" for Windows binaries).

type Service

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

func NewService

func NewService(ctx context.Context, githubToken string, opts ...Option) *Service

func (*Service) NewRepository

func (s *Service) NewRepository(ctx context.Context, owner, name string, opts ...Option) (*Repository, error)

NewRepository opens or initializes a repository at the given path.

func (*Service) PrefetchOrgRepositories

func (s *Service) PrefetchOrgRepositories(ctx context.Context, org string) error

PrefetchOrgRepositories fetches all repositories by the given organization and caches them. This is useful to avoid hitting the GitHub API rate limits when creating multiple repositories.

func (*Service) PrefetchUserRepositories

func (s *Service) PrefetchUserRepositories(ctx context.Context, user string) error

PrefetchUserRepositories fetches all repositories by the given user and caches them. This is useful to avoid hitting the GitHub API rate limits when creating multiple repositories.