vcs

package module
v1.13.3 Latest Latest
Warning

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

 Go to latest Published: Mar 31, 2022 License: MIT Imports: 16 Imported by: 909

README

VCS Repository Management for Go

Manage repos in varying version control systems with ease through a common interface.

Linux Tests Go Report Card Windows Tests Docs

Note: Module names are case sensitive. Please be sure to use github.com/Masterminds/vcs with the capital M.

Quick Usage

Quick usage:

remote := "https://github.com/Masterminds/vcs"
local, _ := ioutil.TempDir("", "go-vcs")
repo, err := NewRepo(remote, local)

In this case NewRepo will detect the VCS is Git and return a GitRepo. All of the repos implement the Repo interface with a common set of features between them.

Supported VCS

Git, SVN, Bazaar (Bzr), and Mercurial (Hg) are currently supported. They each have their own type (e.g., GitRepo) that follow a simple naming pattern. Each type implements the Repo interface and has a constructor (e.g., NewGitRepo). The constructors have the same signature as NewRepo.

Features

  • Clone or checkout a repository depending on the version control system.
  • Pull updates to a repository.
  • Get the currently checked out commit id.
  • Checkout a commit id, branch, or tag (depending on the availability in the VCS).
  • Get a list of tags and branches in the VCS.
  • Check if a string value is a valid reference within the VCS.
  • More...

For more details see the documentation.

Motivation

The package golang.org/x/tools/go/vcs provides some valuable functionality for working with packages in repositories in varying source control management systems. That package, while useful and well tested, is designed with a specific purpose in mind. Our uses went beyond the scope of that package. To implement our scope we built a package that went beyond the functionality and scope of golang.org/x/tools/go/vcs.

Documentation

Overview

Package vcs provides the ability to work with varying version control systems (VCS), also known as source control systems (SCM) though the same interface.

This package includes a function that attempts to detect the repo type from the remote URL and return the proper type. For example, 

remote := "https://github.com/Masterminds/vcs"
local, _ := ioutil.TempDir("", "go-vcs")
repo, err := NewRepo(remote, local)

In this case repo will be a GitRepo instance. NewRepo can detect the VCS for numerous popular VCS and from the URL. For example, a URL ending in .git that's not from one of the popular VCS will be detected as a Git repo and the correct type will be returned.

If you know the repository type and would like to create an instance of a specific type you can use one of constructors for a type. They are NewGitRepo, NewSvnRepo, NewBzrRepo, and NewHgRepo. The definition and usage is the same as NewRepo.

Once you have an object implementing the Repo interface the operations are the same no matter which VCS you're using. There are some caveats. For example, each VCS has its own version formats that need to be respected and checkout out branches, if a branch is being worked with, is different in each VCS.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrWrongVCS is returned when an action is tried on the wrong VCS.
	ErrWrongVCS = errors.New("Wrong VCS detected")

	// ErrCannotDetectVCS is returned when VCS cannot be detected from URI string.
	ErrCannotDetectVCS = errors.New("Cannot detect VCS")

	// ErrWrongRemote occurs when the passed in remote does not match the VCS
	// configured endpoint.
	ErrWrongRemote = errors.New("The Remote does not match the VCS endpoint")

	// ErrRevisionUnavailable happens when commit revision information is
	// unavailable.
	ErrRevisionUnavailable = errors.New("Revision unavailable")
)
View Source 
var Logger *log.Logger

Logger is where you can provide a logger, implementing the log.Logger interface, where verbose output from each VCS will be written. The default logger does not log data. To log data supply your own logger or change the output location of the provided logger.

Functions

func EscapePathSeparator added in v1.11.1 

func EscapePathSeparator(path string) string

EscapePathSeparator escapes the path separator by replacing it with several. Note: this is harmless on Unix, and needed on Windows.

func NewLocalError 

func NewLocalError(msg string, err error, out string) error

NewLocalError constructs a LocalError

func NewRemoteError 

func NewRemoteError(msg string, err error, out string) error

NewRemoteError constructs a RemoteError

Types

type BzrRepo 

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

BzrRepo implements the Repo interface for the Bzr source control.

func NewBzrRepo 

func NewBzrRepo(remote, local string) (*BzrRepo, error)

NewBzrRepo creates a new instance of BzrRepo. The remote and local directories need to be passed in.

func (*BzrRepo) Branches 

func (s *BzrRepo) Branches() ([]string, error)

Branches returns a list of available branches on the repository. In Bazaar (Bzr) clones and branches are the same. A different branch will have a different URL location which we cannot detect from the repo. This is a little different from other VCS.

func (*BzrRepo) CheckLocal 

func (s *BzrRepo) CheckLocal() bool

CheckLocal verifies the local location is a Bzr repo.

func (*BzrRepo) CmdFromDir added in v1.11.0 

func (b *BzrRepo) CmdFromDir(cmd string, args ...string) *exec.Cmd

func (*BzrRepo) CommitInfo 

func (s *BzrRepo) CommitInfo(id string) (*CommitInfo, error)

CommitInfo retrieves metadata about a commit.

func (*BzrRepo) Current 

func (s *BzrRepo) Current() (string, error)

Current returns the current version-ish. This means: * -1 if on the tip of the branch (this is the Bzr value for HEAD) * A tag if on a tag * Otherwise a revision

func (*BzrRepo) Date 

func (s *BzrRepo) Date() (time.Time, error)

Date retrieves the date on the latest commit.

func (*BzrRepo) ExportDir 

func (s *BzrRepo) ExportDir(dir string) error

ExportDir exports the current revision to the passed in directory.

func (*BzrRepo) Get 

func (s *BzrRepo) Get() error

Get is used to perform an initial clone of a repository.

func (*BzrRepo) Init 

func (s *BzrRepo) Init() error

Init initializes a bazaar repository at local location.

func (*BzrRepo) IsDirty 

func (s *BzrRepo) IsDirty() bool

IsDirty returns if the checkout has been modified from the checked out reference.

func (*BzrRepo) IsReference 

func (s *BzrRepo) IsReference(r string) bool

IsReference returns if a string is a reference. A reference can be a commit id or tag.

func (*BzrRepo) LocalPath 

func (b *BzrRepo) LocalPath() string

LocalPath retrieves the local file system location for a repo.

func (*BzrRepo) Ping 

func (s *BzrRepo) Ping() bool

Ping returns if remote location is accessible.

func (*BzrRepo) Remote 

func (b *BzrRepo) Remote() string

Remote retrieves the remote location for a repo.

func (*BzrRepo) RunFromDir 

func (b *BzrRepo) RunFromDir(cmd string, args ...string) ([]byte, error)

func (*BzrRepo) Tags 

func (s *BzrRepo) Tags() ([]string, error)

Tags returns a list of available tags on the repository.

func (*BzrRepo) TagsFromCommit 

func (s *BzrRepo) TagsFromCommit(id string) ([]string, error)

TagsFromCommit retrieves tags from a commit id.

func (*BzrRepo) Update 

func (s *BzrRepo) Update() error

Update performs a Bzr pull and update to an existing checkout.

func (*BzrRepo) UpdateVersion 

func (s *BzrRepo) UpdateVersion(version string) error

UpdateVersion sets the version of a package currently checked out via Bzr.

func (BzrRepo) Vcs 

func (s BzrRepo) Vcs() Type

Vcs retrieves the underlying VCS being implemented.

func (*BzrRepo) Version 

func (s *BzrRepo) Version() (string, error)

Version retrieves the current version.

type CommitInfo 

type CommitInfo struct {
	// The commit id
	Commit string

	// Who authored the commit
	Author string

	// Date of the commit
	Date time.Time

	// Commit message
	Message string
}

CommitInfo contains metadata about a commit.

type GitRepo 

type GitRepo struct {
	RemoteLocation string
	// contains filtered or unexported fields
}

GitRepo implements the Repo interface for the Git source control.

func NewGitRepo 

func NewGitRepo(remote, local string) (*GitRepo, error)

NewGitRepo creates a new instance of GitRepo. The remote and local directories need to be passed in.

func (*GitRepo) Branches 

func (s *GitRepo) Branches() ([]string, error)

Branches returns a list of available branches on the RemoteLocation

func (*GitRepo) CheckLocal 

func (s *GitRepo) CheckLocal() bool

CheckLocal verifies the local location is a Git repo.

func (*GitRepo) CmdFromDir added in v1.11.0 

func (b *GitRepo) CmdFromDir(cmd string, args ...string) *exec.Cmd

func (*GitRepo) CommitInfo 

func (s *GitRepo) CommitInfo(id string) (*CommitInfo, error)

CommitInfo retrieves metadata about a commit.

func (*GitRepo) Current 

func (s *GitRepo) Current() (string, error)

Current returns the current version-ish. This means: * Branch name if on the tip of the branch * Tag if on a tag * Otherwise a revision id

func (*GitRepo) Date 

func (s *GitRepo) Date() (time.Time, error)

Date retrieves the date on the latest commit.

func (*GitRepo) ExportDir 

func (s *GitRepo) ExportDir(dir string) error

ExportDir exports the current revision to the passed in directory.

func (*GitRepo) Get 

func (s *GitRepo) Get() error

Get is used to perform an initial clone of a repository.

func (*GitRepo) Init 

func (s *GitRepo) Init() error

Init initializes a git repository at local location.

func (*GitRepo) IsDirty 

func (s *GitRepo) IsDirty() bool

IsDirty returns if the checkout has been modified from the checked out reference.

func (*GitRepo) IsReference 

func (s *GitRepo) IsReference(r string) bool

IsReference returns if a string is a reference. A reference can be a commit id, branch, or tag.

func (*GitRepo) LocalPath 

func (b *GitRepo) LocalPath() string

LocalPath retrieves the local file system location for a repo.

func (*GitRepo) Ping 

func (s *GitRepo) Ping() bool

Ping returns if remote location is accessible.

func (*GitRepo) Remote 

func (b *GitRepo) Remote() string

Remote retrieves the remote location for a repo.

func (*GitRepo) RunFromDir 

func (b *GitRepo) RunFromDir(cmd string, args ...string) ([]byte, error)

func (*GitRepo) Tags 

func (s *GitRepo) Tags() ([]string, error)

Tags returns a list of available tags on the RemoteLocation

func (*GitRepo) TagsFromCommit 

func (s *GitRepo) TagsFromCommit(id string) ([]string, error)

TagsFromCommit retrieves tags from a commit id.

func (*GitRepo) Update 

func (s *GitRepo) Update() error

Update performs an Git fetch and pull to an existing checkout.

func (*GitRepo) UpdateVersion 

func (s *GitRepo) UpdateVersion(version string) error

UpdateVersion sets the version of a package currently checked out via Git.

func (GitRepo) Vcs 

func (s GitRepo) Vcs() Type

Vcs retrieves the underlying VCS being implemented.

func (*GitRepo) Version 

func (s *GitRepo) Version() (string, error)

Version retrieves the current version.

type HgRepo 

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

HgRepo implements the Repo interface for the Mercurial source control.

func NewHgRepo 

func NewHgRepo(remote, local string) (*HgRepo, error)

NewHgRepo creates a new instance of HgRepo. The remote and local directories need to be passed in.

func (*HgRepo) Branches 

func (s *HgRepo) Branches() ([]string, error)

Branches returns a list of available branches

func (*HgRepo) CheckLocal 

func (s *HgRepo) CheckLocal() bool

CheckLocal verifies the local location is a Git repo.

func (*HgRepo) CmdFromDir added in v1.11.0 

func (b *HgRepo) CmdFromDir(cmd string, args ...string) *exec.Cmd

func (*HgRepo) CommitInfo 

func (s *HgRepo) CommitInfo(id string) (*CommitInfo, error)

CommitInfo retrieves metadata about a commit.

func (*HgRepo) Current 

func (s *HgRepo) Current() (string, error)

Current returns the current version-ish. This means: * Branch name if on the tip of the branch * Tag if on a tag * Otherwise a revision id

func (*HgRepo) Date 

func (s *HgRepo) Date() (time.Time, error)

Date retrieves the date on the latest commit.

func (*HgRepo) ExportDir 

func (s *HgRepo) ExportDir(dir string) error

ExportDir exports the current revision to the passed in directory.

func (*HgRepo) Get 

func (s *HgRepo) Get() error

Get is used to perform an initial clone of a repository.

func (*HgRepo) Init 

func (s *HgRepo) Init() error

Init will initialize a mercurial repository at local location.

func (*HgRepo) IsDirty 

func (s *HgRepo) IsDirty() bool

IsDirty returns if the checkout has been modified from the checked out reference.

func (*HgRepo) IsReference 

func (s *HgRepo) IsReference(r string) bool

IsReference returns if a string is a reference. A reference can be a commit id, branch, or tag.

func (*HgRepo) LocalPath 

func (b *HgRepo) LocalPath() string

LocalPath retrieves the local file system location for a repo.

func (*HgRepo) Ping 

func (s *HgRepo) Ping() bool

Ping returns if remote location is accessible.

func (*HgRepo) Remote 

func (b *HgRepo) Remote() string

Remote retrieves the remote location for a repo.

func (*HgRepo) RunFromDir 

func (b *HgRepo) RunFromDir(cmd string, args ...string) ([]byte, error)

func (*HgRepo) Tags 

func (s *HgRepo) Tags() ([]string, error)

Tags returns a list of available tags

func (*HgRepo) TagsFromCommit 

func (s *HgRepo) TagsFromCommit(id string) ([]string, error)

TagsFromCommit retrieves tags from a commit id.

func (*HgRepo) Update 

func (s *HgRepo) Update() error

Update performs a Mercurial pull to an existing checkout.

func (*HgRepo) UpdateVersion 

func (s *HgRepo) UpdateVersion(version string) error

UpdateVersion sets the version of a package currently checked out via Hg.

func (HgRepo) Vcs 

func (s HgRepo) Vcs() Type

Vcs retrieves the underlying VCS being implemented.

func (*HgRepo) Version 

func (s *HgRepo) Version() (string, error)

Version retrieves the current version.

type LocalError 

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

LocalError is returned when a local operation has an error

func (*LocalError) Error 

func (e *LocalError) Error() string

Error implements the Error interface

func (*LocalError) Original 

func (e *LocalError) Original() error

Original retrieves the underlying implementation specific error.

func (*LocalError) Out 

func (e *LocalError) Out() string

Out retrieves the output of the original command that was run.

type RemoteError 

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

RemoteError is returned when an operation fails against a remote repo

func (*RemoteError) Error 

func (e *RemoteError) Error() string

Error implements the Error interface

func (*RemoteError) Original 

func (e *RemoteError) Original() error

Original retrieves the underlying implementation specific error.

func (*RemoteError) Out 

func (e *RemoteError) Out() string

Out retrieves the output of the original command that was run.

type Repo 

type Repo interface {

	// Vcs retrieves the underlying VCS being implemented.
	Vcs() Type

	// Remote retrieves the remote location for a repo.
	Remote() string

	// LocalPath retrieves the local file system location for a repo.
	LocalPath() string

	// Get is used to perform an initial clone/checkout of a repository.
	Get() error

	// Initializes a new repository locally.
	Init() error

	// Update performs an update to an existing checkout of a repository.
	Update() error

	// UpdateVersion sets the version of a package of a repository.
	UpdateVersion(string) error

	// Version retrieves the current version.
	Version() (string, error)

	// Current retrieves the current version-ish. This is different from the
	// Version method. The output could be a branch name if on the tip of a
	// branch (git), a tag if on a tag, a revision if on a specific revision
	// that's not the tip of the branch. The values here vary based on the VCS.
	Current() (string, error)

	// Date retrieves the date on the latest commit.
	Date() (time.Time, error)

	// CheckLocal verifies the local location is of the correct VCS type
	CheckLocal() bool

	// Branches returns a list of available branches on the repository.
	Branches() ([]string, error)

	// Tags returns a list of available tags on the repository.
	Tags() ([]string, error)

	// IsReference returns if a string is a reference. A reference can be a
	// commit id, branch, or tag.
	IsReference(string) bool

	// IsDirty returns if the checkout has been modified from the checked
	// out reference.
	IsDirty() bool

	// CommitInfo retrieves metadata about a commit.
	CommitInfo(string) (*CommitInfo, error)

	// TagsFromCommit retrieves tags from a commit id.
	TagsFromCommit(string) ([]string, error)

	// Ping returns if remote location is accessible.
	Ping() bool

	// RunFromDir executes a command from repo's directory.
	RunFromDir(cmd string, args ...string) ([]byte, error)

	// CmdFromDir creates a new command that will be executed from repo's
	// directory.
	CmdFromDir(cmd string, args ...string) *exec.Cmd

	// ExportDir exports the current revision to the passed in directory.
	ExportDir(string) error
}

Repo provides an interface to work with repositories using different source control systems such as Git, Bzr, Mercurial, and SVN. For implementations of this interface see BzrRepo, GitRepo, HgRepo, and SvnRepo.

func NewRepo 

func NewRepo(remote, local string) (Repo, error)

NewRepo returns a Repo based on trying to detect the source control from the remote and local locations. The appropriate implementation will be returned or an ErrCannotDetectVCS if the VCS type cannot be detected. Note, this function may make calls to the Internet to determind help determine the VCS.

Example 
remote := "https://github.com/Masterminds/vcs"
local, _ := ioutil.TempDir("", "go-vcs")
repo, _ := NewRepo(remote, local)
// Returns: instance of GitRepo

repo.Vcs()
// Returns Git as this is a Git repo

err := repo.Get()
// Pulls down a repo, or a checkout in the case of SVN, and returns an
// error if that didn't happen successfully.
if err != nil {
	fmt.Println(err)
}

err = repo.UpdateVersion("master")
// Checkouts out a specific version. In most cases this can be a commit id,
// branch, or tag.
if err != nil {
	fmt.Println(err)
}

Output:

type SvnRepo 

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

SvnRepo implements the Repo interface for the Svn source control.

func NewSvnRepo 

func NewSvnRepo(remote, local string) (*SvnRepo, error)

NewSvnRepo creates a new instance of SvnRepo. The remote and local directories need to be passed in. The remote location should include the branch for SVN. For example, if the package is https://github.com/Masterminds/cookoo/ the remote should be https://github.com/Masterminds/cookoo/trunk for the trunk branch.

func (*SvnRepo) Branches 

func (s *SvnRepo) Branches() ([]string, error)

Branches returns []string{} as there are no formal branches in SVN. Branches are a convention. They are typically implemented as a copy of the trunk and placed in the /branches/[tag name] directory. Since this is a convention the expectation is to checkout a branch the correct subdirectory will be used as the path. For more information see: http://svnbook.red-bean.com/en/1.7/svn.branchmerge.using.html

func (*SvnRepo) CheckLocal 

func (s *SvnRepo) CheckLocal() bool

CheckLocal verifies the local location is an SVN repo.

func (*SvnRepo) CmdFromDir added in v1.11.0 

func (b *SvnRepo) CmdFromDir(cmd string, args ...string) *exec.Cmd

func (*SvnRepo) CommitInfo 

func (s *SvnRepo) CommitInfo(id string) (*CommitInfo, error)

CommitInfo retrieves metadata about a commit.

func (*SvnRepo) Current 

func (s *SvnRepo) Current() (string, error)

Current returns the current version-ish. This means: * HEAD if on the tip. * Otherwise a revision id

func (*SvnRepo) Date 

func (s *SvnRepo) Date() (time.Time, error)

Date retrieves the date on the latest commit.

func (*SvnRepo) ExportDir 

func (s *SvnRepo) ExportDir(dir string) error

ExportDir exports the current revision to the passed in directory.

func (*SvnRepo) Get 

func (s *SvnRepo) Get() error

Get is used to perform an initial checkout of a repository. Note, because SVN isn't distributed this is a checkout without a clone.

func (*SvnRepo) Init 

func (s *SvnRepo) Init() error

Init will create a svn repository at remote location.

func (*SvnRepo) IsDirty 

func (s *SvnRepo) IsDirty() bool

IsDirty returns if the checkout has been modified from the checked out reference.

func (*SvnRepo) IsReference 

func (s *SvnRepo) IsReference(r string) bool

IsReference returns if a string is a reference. A reference is a commit id. Branches and tags are part of the path.

func (*SvnRepo) LocalPath 

func (b *SvnRepo) LocalPath() string

LocalPath retrieves the local file system location for a repo.

func (*SvnRepo) Ping 

func (s *SvnRepo) Ping() bool

Ping returns if remote location is accessible.

func (*SvnRepo) Remote 

func (b *SvnRepo) Remote() string

Remote retrieves the remote location for a repo.

func (*SvnRepo) RunFromDir 

func (b *SvnRepo) RunFromDir(cmd string, args ...string) ([]byte, error)

func (*SvnRepo) Tags 

func (s *SvnRepo) Tags() ([]string, error)

Tags returns []string{} as there are no formal tags in SVN. Tags are a convention in SVN. They are typically implemented as a copy of the trunk and placed in the /tags/[tag name] directory. Since this is a convention the expectation is to checkout a tag the correct subdirectory will be used as the path. For more information see: http://svnbook.red-bean.com/en/1.7/svn.branchmerge.tags.html

func (*SvnRepo) TagsFromCommit 

func (s *SvnRepo) TagsFromCommit(id string) ([]string, error)

TagsFromCommit retrieves tags from a commit id.

func (*SvnRepo) Update 

func (s *SvnRepo) Update() error

Update performs an SVN update to an existing checkout.

func (*SvnRepo) UpdateVersion 

func (s *SvnRepo) UpdateVersion(version string) error

UpdateVersion sets the version of a package currently checked out via SVN.

func (SvnRepo) Vcs 

func (s SvnRepo) Vcs() Type

Vcs retrieves the underlying VCS being implemented.

func (*SvnRepo) Version 

func (s *SvnRepo) Version() (string, error)

Version retrieves the current version.

type Type 

type Type string

Type describes the type of VCS 

const (
	NoVCS Type = ""
	Git   Type = "git"
	Svn   Type = "svn"
	Bzr   Type = "bzr"
	Hg    Type = "hg"
)

VCS types

func DetectVcsFromFS 

func DetectVcsFromFS(vcsPath string) (Type, error)

DetectVcsFromFS detects the type from the local path. Is there a better way to do this?

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.