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

Source Files

View all Source files

Directories

Path Synopsis

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.