vcs

package
v0.0.0-...-a6d3b49 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2015 License: BSD-3-Clause Imports: 5 Imported by: 0

Documentation

Overview

Package vcs provides an interface for reading and manipulating repositories in version control systems.

The vcs package must be used in conjunction with VCS implementation packages. The subpackages git, gitcmd, hg, and hgcmd provide implementations of Git and Mercurial (in both native-Go/Cgo and shell-command variants).

Package vcs is a generated protocol buffer package.

It is generated from these files:

vcs.proto

It has these top-level messages:

Commit
Signature
Branch
BehindAhead
BranchesOptions
Tag
SearchOptions
SearchResult
Committer

Index

Constants

View Source
const (
	// FixedQuery is a value for SearchOptions.QueryType that
	// indicates the query is a fixed string, not a regex.
	FixedQuery = "fixed"
)
View Source
const ModeSubmodule = 0160000

ModeSubmodule is an os.FileMode mask indicating that the file is a VCS submodule (e.g., a git submodule).

Variables

View Source
var (
	ErrRefNotFound      = errors.New("ref not found")
	ErrBranchNotFound   = errors.New("branch not found")
	ErrCommitNotFound   = errors.New("commit not found")
	ErrRevisionNotFound = errors.New("revision not found")
	ErrTagNotFound      = errors.New("tag not found")
)

Functions

func RegisterCloner

func RegisterCloner(vcs string, f Cloner)

RegisterCloner registers a func to clone VCS repositories of a specific type.

Library users should import the VCS implementation packages (using underscore-import if necessary) to register their cloners. Afterwards, they may call Clone to clone repositories of that type.

An implementation of a VCS should call RegisterCloner in an init func.

It is not safe in general to call RegisterCloner concurrently or at any time after init. Its internal storage is not protected by a mutex.

If a cloner for the VCS is already registered, RegisterCloner overwrites it with f. If vcs is empty or f is nil, it also panics.

func RegisterOpener

func RegisterOpener(vcs string, f Opener)

RegisterOpener registers a func to open VCS repositories of a specific type.

Library users should import the VCS implementation packages (using underscore-import if necessary) to register their openers. Afterwards, they may call Open to open repositories of that type.

An implementation of a VCS should call RegisterOpener in an init func.

It is not safe in general to call RegisterOpener concurrently or at any time after init. Its internal storage is not protected by a mutex.

If an opener for the VCS is already registered, RegisterOpener overwrites it with f. If vcs is empty or f is nil, it also panics.

Types

type BehindAhead

type BehindAhead struct {
	Behind uint32 `protobuf:"varint,1,opt,name=behind,proto3" json:"behind,omitempty"`
	Ahead  uint32 `protobuf:"varint,2,opt,name=ahead,proto3" json:"ahead,omitempty"`
}

BehindAhead is a set of behind/ahead counts.

func (*BehindAhead) ProtoMessage

func (*BehindAhead) ProtoMessage()

func (*BehindAhead) Reset

func (m *BehindAhead) Reset()

func (*BehindAhead) String

func (m *BehindAhead) String() string

type BlameOptions

type BlameOptions struct {
	NewestCommit CommitID `json:",omitempty" url:",omitempty"`
	OldestCommit CommitID `json:",omitempty" url:",omitempty"` // or "" for the root commit

	StartLine int `json:",omitempty" url:",omitempty"` // 1-indexed start byte (or 0 for beginning of file)
	EndLine   int `json:",omitempty" url:",omitempty"` // 1-indexed end byte (or 0 for end of file)
}

BlameOptions configures a blame.

type Blamer

type Blamer interface {
	BlameFile(path string, opt *BlameOptions) ([]*Hunk, error)
}

A Blamer is a repository that can blame portions of a file.

type Branch

type Branch struct {
	// Name is the name of this branch.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// Head is the commit ID of this branch's head commit.
	Head CommitID `protobuf:"bytes,2,opt,name=head,proto3,customtype=CommitID" json:"head,omitempty"`
	// Commit optionally contains commit information for this branch's head commit.
	// It is populated if IncludeCommit option is set.
	Commit *Commit `protobuf:"bytes,4,opt,name=commit" json:"commit,omitempty"`
	// Counts optionally contains the commit counts relative to specified branch.
	Counts *BehindAhead `protobuf:"bytes,3,opt,name=counts" json:"counts,omitempty"`
}

A Branch is a VCS branch.

func (*Branch) GetCommit

func (m *Branch) GetCommit() *Commit

func (*Branch) GetCounts

func (m *Branch) GetCounts() *BehindAhead

func (*Branch) ProtoMessage

func (*Branch) ProtoMessage()

func (*Branch) Reset

func (m *Branch) Reset()

func (*Branch) String

func (m *Branch) String() string

type Branches

type Branches []*Branch

func (Branches) Len

func (p Branches) Len() int

func (Branches) Less

func (p Branches) Less(i, j int) bool

func (Branches) Swap

func (p Branches) Swap(i, j int)

type BranchesOptions

type BranchesOptions struct {
	// MergedInto will cause the returned list to be restricted to only
	// branches that were merged into this branch name.
	MergedInto string `protobuf:"bytes,4,opt,name=merged_into,proto3" json:"merged_into,omitempty" url:",omitempty"`
	// IncludeCommit controls whether complete commit information is included.
	IncludeCommit bool `protobuf:"varint,2,opt,name=include_commit,proto3" json:"include_commit,omitempty" url:",omitempty"`
	// BehindAheadBranch specifies a branch name. If set to something other than blank
	// string, then each returned branch will include a behind/ahead commit counts
	// information against the specified base branch. If left blank, then branches will
	// not include that information and their Counts will be nil.
	BehindAheadBranch string `protobuf:"bytes,1,opt,name=behind_ahead_branch,proto3" json:"behind_ahead_branch,omitempty" url:",omitempty"`
	// ContainsCommit filters the list of branches to only those that
	// contain a specific commit ID (if set).
	ContainsCommit string `protobuf:"bytes,3,opt,name=contains_commit,proto3" json:"contains_commit,omitempty" url:",omitempty"`
}

BranchesOptions specifies options for the list of branches returned by (Repository).Branches.

func (*BranchesOptions) ProtoMessage

func (*BranchesOptions) ProtoMessage()

func (*BranchesOptions) Reset

func (m *BranchesOptions) Reset()

func (*BranchesOptions) String

func (m *BranchesOptions) String() string

type ByAuthorDate

type ByAuthorDate []*Branch

ByAuthorDate sorts by author date. Requires full commit information to be included.

func (ByAuthorDate) Len

func (p ByAuthorDate) Len() int

func (ByAuthorDate) Less

func (p ByAuthorDate) Less(i, j int) bool

func (ByAuthorDate) Swap

func (p ByAuthorDate) Swap(i, j int)

type CloneOpt

type CloneOpt struct {
	Bare   bool // create a bare repo
	Mirror bool // create a mirror repo (`git clone --mirror`)

	RemoteOpts // configures communication with the remote repository

}

CloneOpt configures a clone operation.

type Cloner

type Cloner func(url, dir string, opt CloneOpt) (Repository, error)

A cloner is a function that clones a repository from a URL to dir in the filesystem.

type Commit

type Commit struct {
	ID        CommitID   `protobuf:"bytes,1,opt,name=id,proto3,customtype=CommitID" json:"id,omitempty"`
	Author    Signature  `protobuf:"bytes,2,opt,name=author" json:"author"`
	Committer *Signature `protobuf:"bytes,3,opt,name=committer" json:"committer,omitempty"`
	Message   string     `protobuf:"bytes,4,opt,name=message,proto3" json:"message,omitempty"`
	// Parents are the commit IDs of this commit's parent commits.
	Parents []CommitID `protobuf:"bytes,5,rep,name=parents,customtype=CommitID" json:"parents,omitempty"`
}

func (*Commit) GetAuthor

func (m *Commit) GetAuthor() Signature

func (*Commit) GetCommitter

func (m *Commit) GetCommitter() *Signature

func (*Commit) ProtoMessage

func (*Commit) ProtoMessage()

func (*Commit) Reset

func (m *Commit) Reset()

func (*Commit) String

func (m *Commit) String() string

type CommitID

type CommitID string

func (CommitID) Marshal

func (c CommitID) Marshal() ([]byte, error)

Marshal implements proto.Marshaler.

func (*CommitID) Unmarshal

func (c *CommitID) Unmarshal(data []byte) error

Unmarshal implements proto.Unmarshaler.

type CommitsOptions

type CommitsOptions struct {
	Head CommitID // include all commits reachable from this commit (required)
	Base CommitID // exlude all commits reachable from this commit (optional, like `git log Base..Head`)

	N    uint // limit the number of returned commits to this many (0 means no limit)
	Skip uint // skip this many commits at the beginning

	Path string // only commits modifying the given path are selected (optional)

	NoTotal bool // avoid counting the total number of commits
}

CommitsOptions specifies limits on the list of commits returned by (Repository).Commits.

type Committer

type Committer struct {
	Name    string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	Email   string `protobuf:"bytes,2,opt,name=email,proto3" json:"email,omitempty"`
	Commits int32  `protobuf:"varint,3,opt,name=commits,proto3" json:"commits,omitempty"`
}

A Committer is a contributor to a repository.

func (*Committer) ProtoMessage

func (*Committer) ProtoMessage()

func (*Committer) Reset

func (m *Committer) Reset()

func (*Committer) String

func (m *Committer) String() string

type CommittersOptions

type CommittersOptions struct {
	N int // limit the number of returned committers, ordered by decreasing number of commits (0 means no limit)

	Rev string // the rev for which committer stats will be fetched ("" means use the current revision)
}

CommittersOptions specifies limits on the list of committers returned by (Repository).Committers.

type CrossRepoDiffer

type CrossRepoDiffer interface {
	// CrossRepoDiff shows changes between two commits in different
	// repositories. If base or head do not exist, an error is
	// returned.
	CrossRepoDiff(base CommitID, headRepo Repository, head CommitID, opt *DiffOptions) (*Diff, error)
}

A CrossRepoDiffer is a repository that can compute diffs with respect to a commit in a different repository.

type CrossRepoMerger

type CrossRepoMerger interface {
	// CrossRepoMergeBase returns the merge base commit for the
	// specified commits (aka greatest common ancestor commit for hg).
	//
	// The commit specified by `b` must exist in repoB but does not
	// need to exist in the repository that CrossRepoMergeBase is
	// called on. Likewise, the commit specified by `a` need not exist
	// in repoB.
	CrossRepoMergeBase(a CommitID, repoB Repository, b CommitID) (CommitID, error)
}

A CrossRepoMerger is a repository that can perform merge-related actions across separate repositories.

type Diff

type Diff struct {
	Raw string // the raw diff output
}

A Diff represents changes between two commits.

type DiffOptions

type DiffOptions struct {
	Paths                 []string // constrain diff to these pathspecs
	DetectRenames         bool
	OrigPrefix, NewPrefix string // prefixes for orig and new filenames (e.g., "a/", "b/")

	ExcludeReachableFromBoth bool // like "<rev1>...<rev2>" (see `git rev-parse --help`)
}

DiffOptions configures a diff.

type Differ

type Differ interface {
	// Diff shows changes between two commits. If base or head do not
	// exist, an error is returned.
	Diff(base, head CommitID, opt *DiffOptions) (*Diff, error)
}

A Differ is a repository that can compute diffs between two commits.

type Hunk

type Hunk struct {
	StartLine int // 1-indexed start line number
	EndLine   int // 1-indexed end line number
	StartByte int // 0-indexed start byte position (inclusive)
	EndByte   int // 0-indexed end byte position (exclusive)
	CommitID
	Author Signature
}

A Hunk is a contiguous portion of a file associated with a commit.

type Merger

type Merger interface {
	// MergeBase returns the merge base commit for the specified
	// commits (aka greatest common ancestor commit for hg).
	MergeBase(CommitID, CommitID) (CommitID, error)
}

A Merger is a repository that can perform actions related to merging.

type Opener

type Opener func(dir string) (Repository, error)

An Opener is a function that opens a repository rooted at dir in the filesystem. An Opener should fail if there exists no repository rooted at dir.

type RemoteOpts

type RemoteOpts struct {
	SSH *SSHConfig // ssh configuration for communication with the remote
}

RemoteOpts configures interactions with a remote repository.

type RemoteUpdater

type RemoteUpdater interface {
	// UpdateEverything updates all branches, tags, etc., to match the
	// default remote repository. The implementation is VCS-dependent.
	UpdateEverything(RemoteOpts) error
}

A RemoteUpdater is a repository that can fetch updates to itself from a remote repository.

type Repository

type Repository interface {
	// ResolveRevision returns the revision that the given revision
	// specifier resolves to, or a non-nil error if there is no such
	// revision.
	//
	// Implementations may choose to return ErrRevisionNotFound in all
	// cases where the revision is not found, or more specific errors
	// (such as ErrCommitNotFound) if spec can be partially resolved
	// or determined to be a certain kind of revision specifier.
	ResolveRevision(spec string) (CommitID, error)

	// ResolveTag returns the tag with the given name, or
	// ErrTagNotFound if no such tag exists.
	ResolveTag(name string) (CommitID, error)

	// ResolveBranch returns the branch with the given name, or
	// ErrBranchNotFound if no such branch exists.
	ResolveBranch(name string) (CommitID, error)

	// Branches returns a list of all branches in the repository.
	Branches(BranchesOptions) ([]*Branch, error)

	// Tags returns a list of all tags in the repository.
	Tags() ([]*Tag, error)

	// GetCommit returns the commit with the given commit ID, or
	// ErrCommitNotFound if no such commit exists.
	GetCommit(CommitID) (*Commit, error)

	// Commits returns all commits matching the options, as well as
	// the total number of commits (the count of which is not subject
	// to the N/Skip options).
	//
	// Optionally, the caller can request the total not to be computed,
	// as this can be expensive for large branches.
	Commits(CommitsOptions) (commits []*Commit, total uint, err error)

	// Committers returns the per-author commit statistics of the repo.
	Committers(CommittersOptions) ([]*Committer, error)

	// FileSystem opens the repository file tree at a given commit ID.
	//
	// Implementations may choose to check that the commit exists
	// before FileSystem returns or to defer the check until
	// operations are performed on the filesystem. (For example, an
	// implementation proxying a remote filesystem may not want to
	// incur the round-trip to check that the commit exists.)
	FileSystem(at CommitID) (vfs.FileSystem, error)
}

A Repository is a VCS repository.

func Clone

func Clone(vcs, url, dir string, opt CloneOpt) (Repository, error)

Clone clones a repository rooted at dir. A cloner for its VCS must be registered (typically by importing a subpackage of go-vcs that calls RegisterCloner, using underscore-import if necessary).

func Open

func Open(vcs, dir string) (Repository, error)

Open opens a repository rooted at dir. An opener for its VCS must be registered (typically by importing a subpackage of go-vcs that calls RegisterOpener, using underscore-import if necessary). Open will fail if there is no vcs repository at rooted dir.

type SSHConfig

type SSHConfig struct {
	User       string `json:",omitempty"` // ssh user (if empty, inferred from URL)
	PublicKey  []byte `json:",omitempty"` // ssh public key (if nil, inferred from PrivateKey)
	PrivateKey []byte // ssh private key, usually passed to ssh.ParsePrivateKey (passphrases currently unsupported)
}

type SearchOptions

type SearchOptions struct {
	// the query string
	Query string `protobuf:"bytes,1,opt,name=query,proto3" json:"query,omitempty"`
	// currently only FixedQuery ("fixed") is supported
	QueryType string `protobuf:"bytes,2,opt,name=query_type,proto3" json:"query_type,omitempty"`
	// the number of lines before and after each hit to display
	ContextLines int32 `protobuf:"varint,3,opt,name=context_lines,proto3" json:"context_lines,omitempty"`
	// max number of matches to return
	N int32 `protobuf:"varint,4,opt,name=n,proto3" json:"n,omitempty"`
	// starting offset for matches (use with N for pagination)
	Offset int32 `protobuf:"varint,5,opt,name=offset,proto3" json:"offset,omitempty"`
}

SearchOptions specifies options for a repository search.

func (*SearchOptions) ProtoMessage

func (*SearchOptions) ProtoMessage()

func (*SearchOptions) Reset

func (m *SearchOptions) Reset()

func (*SearchOptions) String

func (m *SearchOptions) String() string

type SearchResult

type SearchResult struct {
	// File is the file that contains this match.
	File string `protobuf:"bytes,1,opt,name=file,proto3" json:"file,omitempty"`
	// The byte range [start,end) of the match.
	StartByte uint32 `protobuf:"varint,2,opt,name=start_byte,proto3" json:"start_byte,omitempty"`
	EndByte   uint32 `protobuf:"varint,3,opt,name=end_byte,proto3" json:"end_byte,omitempty"`
	// The line range [start,end] of the match.
	StartLine uint32 `protobuf:"varint,4,opt,name=start_line,proto3" json:"start_line,omitempty"`
	EndLine   uint32 `protobuf:"varint,5,opt,name=end_line,proto3" json:"end_line,omitempty"`
	// Match is the matching portion of the file from [StartByte,
	// EndByte).
	Match []byte `protobuf:"bytes,6,opt,name=match,proto3" json:"match,omitempty"`
}

A SearchResult is a match returned by a search.

func (*SearchResult) ProtoMessage

func (*SearchResult) ProtoMessage()

func (*SearchResult) Reset

func (m *SearchResult) Reset()

func (*SearchResult) String

func (m *SearchResult) String() string

type Searcher

type Searcher interface {
	// Search searches the text of a repository at the given commit
	// ID.
	Search(CommitID, SearchOptions) ([]*SearchResult, error)
}

type Signature

type Signature struct {
	Name  string            `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	Email string            `protobuf:"bytes,2,opt,name=email,proto3" json:"email,omitempty"`
	Date  pbtypes.Timestamp `protobuf:"bytes,3,opt,name=date" json:"date"`
}

func (*Signature) GetDate

func (m *Signature) GetDate() pbtypes.Timestamp

func (*Signature) ProtoMessage

func (*Signature) ProtoMessage()

func (*Signature) Reset

func (m *Signature) Reset()

func (*Signature) String

func (m *Signature) String() string

type SubmoduleInfo

type SubmoduleInfo struct {
	// URL is the submodule repository origin URL.
	URL string

	// CommitID is the pinned commit ID of the submodule (in the
	// submodule repository's commit ID space).
	CommitID
}

SubmoduleInfo holds information about a VCS submodule and is returned in the FileInfo's Sys field by Stat/Lstat/ReadDir calls.

type SymlinkInfo

type SymlinkInfo struct {
	// Dest is the path that the symlink points to.
	Dest string
}

SymlinkInfo holds information about a symlink and is returned in the FileInfo's Sys field by Stat/Lstat/ReadDir calls.

type Tag

type Tag struct {
	Name     string   `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	CommitID CommitID `protobuf:"bytes,2,opt,name=commit_id,proto3,customtype=CommitID" json:"commit_id,omitempty"`
}

A Tag is a VCS tag.

func (*Tag) ProtoMessage

func (*Tag) ProtoMessage()

func (*Tag) Reset

func (m *Tag) Reset()

func (*Tag) String

func (m *Tag) String() string

type Tags

type Tags []*Tag

func (Tags) Len

func (p Tags) Len() int

func (Tags) Less

func (p Tags) Less(i, j int) bool

func (Tags) Swap

func (p Tags) Swap(i, j int)

type UnsupportedVCSError

type UnsupportedVCSError struct {
	VCS string // the VCS type that was attempted to be used
	// contains filtered or unexported fields
}

UnsupportedVCSError is when Open is called to open a repository of a VCS type that doesn't have an Opener registered.

func (*UnsupportedVCSError) Error

func (e *UnsupportedVCSError) Error() string

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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