gitiles

package
v0.0.0-...-3c454ca Latest Latest
Warning

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

 Go to latest Published: Dec 27, 2024 License: BSD-3-Clause Imports: 20 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	// CommitURL is the format of the URL used to retrieve a commit.
	CommitURL = "%s/+show/%s"
	// CommitURLJSON is the format of the URL used to retrieve a commit as JSON.
	CommitURLJSON = CommitURL + "?format=JSON"

	// DownloadURL is the format of the URL used to download a file.
	DownloadURL = "%s/+show/%s/%s?format=TEXT"
	// LogURL is the format of the URL used to view the git log.
	LogURL = "%s/+log/%s?format=JSON"
	// RefsURL is the format of the URL used to retrieve refs.
	RefsURL = "%s/+refs%%2Fheads?format=JSON"
	// TagsURL is the format of the URL used to retrieve tags.
	TagsURL = "%s/+refs%%2Ftags?format=JSON"

	// ModeHeader is an HTTP header which indicates the file mode.
	ModeHeader = "X-Gitiles-Path-Mode"
	// TypeHeader is an HTTP header which indicates the object type.
	TypeHeader = "X-Gitiles-Object-Type"
)

Variables

View Source 
var (
	// ErrStopIteration is an error returned from a helper function passed to
	// LogFn which indicates that iteration over commits should stop.
	ErrStopIteration = errors.New("stop iteration")
)

Functions

func LogOptionsToQuery 

func LogOptionsToQuery(opts []LogOption) (string, string, int, error)

LogOptionsToQuery converts the given LogOptions to a URL sub-path and query string. Returns the URL sub-path and query string and the maximum number of commits to return from a Log query (or zero if none is provided, indicating no limit), or any error which occurred.

func ParseURL 

func ParseURL(u string) (string, string, string, error)

ParseURL breaks a gitiles URL into the repo URL, ref, and sub-path. Note that this is inherently error-prone due to the way that Gitiles URLs are structured: it is impossible to distinguish between the ref name and a path within the repo since both are separated by slashes with no other distinction. This function assumes that the ref name has a single component, eg. "refs/heads/main", or simply, "main".

Types

type Author 

type Author struct {
	Name  string `json:"name"`
	Email string `json:"email"`
	Time  string `json:"time"`
}

Author represents the author of a Commit.

type Commit 

type Commit struct {
	Commit    string      `json:"commit"`
	Parents   []string    `json:"parents"`
	Author    *Author     `json:"author"`
	Committer *Author     `json:"committer"`
	Message   string      `json:"message"`
	TreeDiffs []*TreeDiff `json:"tree_diff"`
}

Commit contains information about one Git commit.

func LongCommitToCommit 

func LongCommitToCommit(details *vcsinfo.LongCommit) (*Commit, error)

LongCommitToCommit converts the given LongCommit to a Commit. Intended for use in tests.

type GitilesRepo 

type GitilesRepo interface {
	// Details returns a vcsinfo.LongCommit for the given commit.
	Details(ctx context.Context, ref string) (*vcsinfo.LongCommit, error)
	// ReadObject reads the given object at the given ref, returning its contents
	// and FileInfo.
	ReadObject(ctx context.Context, path, ref string) (os.FileInfo, []byte, error)
	// ReadFileAtRef reads the given file at the given ref.
	ReadFileAtRef(ctx context.Context, srcPath, ref string) ([]byte, error)
	// ReadFile reads the current version of the given file from the main branch
	// of the Repo.
	ReadFile(ctx context.Context, srcPath string) ([]byte, error)
	// DownloadFile downloads the current version of the given file from the main
	// branch of the Repo.
	DownloadFile(ctx context.Context, srcPath, dstPath string) error
	// DownloadFileAtRef downloads the given file at the given ref.
	DownloadFileAtRef(ctx context.Context, srcPath, ref, dstPath string) error
	// ListDirAtRef reads the given directory at the given ref. Returns a slice of
	// file names and a slice of dir names, relative to the given directory, or any
	// error which occurred.
	ListDirAtRef(ctx context.Context, dir, ref string) ([]os.FileInfo, error)
	// ListDir reads the given directory on the main branch. Returns a slice of
	// file names and a slice of dir names, relative to the given directory, or any
	// error which occurred.
	ListDir(ctx context.Context, dir string) ([]os.FileInfo, error)
	// ResolveRef resolves the given ref to a commit hash.
	ResolveRef(ctx context.Context, ref string) (string, error)
	// ListFilesRecursiveAtRef returns a list of all file paths, relative to the
	// given directory, under the given directory at the given ref.
	ListFilesRecursiveAtRef(ctx context.Context, topDir, ref string) ([]string, error)
	// ListFilesRecursive returns a list of all file paths, relative to the given
	// directory, under the given directory on the main branch.
	ListFilesRecursive(ctx context.Context, dir string) ([]string, error)
	// Log returns Gitiles' equivalent to "git log" for the given expression.
	Log(ctx context.Context, logExpr string, opts ...LogOption) ([]*vcsinfo.LongCommit, error)
	// LogFirstParent is equivalent to "git log --first-parent A..B", ie. it
	// only returns commits which are reachable from A by following the first parent
	// (the "main" branch) but not from B. LogFirstParent is incompatible with
	// LogPath.
	LogFirstParent(ctx context.Context, from, to string, opts ...LogOption) ([]*vcsinfo.LongCommit, error)
	// LogLinear is equivalent to "git log --first-parent --ancestry-path from..to",
	// ie. it only returns commits which are on the direct path from A to B, and
	// only on the "main" branch. This is as opposed to "git log from..to" which
	// returns all commits which are ancestors of 'to' but not 'from'. LogLinear is
	// incompatible with LogPath.
	LogLinear(ctx context.Context, from, to string, opts ...LogOption) ([]*vcsinfo.LongCommit, error)
	// LogFn runs the given function for each commit in the log for the given
	// expression. It stops when ErrStopIteration is returned.
	LogFn(ctx context.Context, logExpr string, fn func(context.Context, *vcsinfo.LongCommit) error, opts ...LogOption) error
	// LogFnBatch is the same as LogFn but it runs the given function over batches
	// of commits.
	LogFnBatch(ctx context.Context, logExpr string, fn func(context.Context, []*vcsinfo.LongCommit) error, opts ...LogOption) error
	// Branches returns the list of branches in the repo.
	Branches(ctx context.Context) ([]*git.Branch, error)
	// Tags returns the list of tags in the repo. The returned map has tag names as
	// keys and commit hashes as values.
	Tags(ctx context.Context) (map[string]string, error)
	// URL returns the repo URL.
	URL() string
}

GitilesRepo is an interface to Gitiles.

type Log 

type Log struct {
	Log  []*Commit `json:"log"`
	Next string    `json:"next"`
}

Log represents a series of Commits in the git log.

type LogOption 

type LogOption interface {
	Key() string
	Value() string
	Path() string
}

LogOption represents an optional parameter to a Log function. Either Key() AND Value() OR Path() must return non-empty strings. Only one LogOption in a given set may return a non-empty value for Path().

func LogBatchSize 

func LogBatchSize(n int) LogOption

LogBatchSize is a LogOption which indicates the number of commits which should be included in each batch of commits returned by Log.

func LogLimit 

func LogLimit(n int) LogOption

LogLimit is a LogOption which makes Log return at most N commits.

func LogPath 

func LogPath(path string) LogOption

LogPath is a LogOption which limits the git log to the given path. LogPath is incompatible with any Log queries which also limit the returned commits, eg. LogLinear and LogFirstParent.

func LogReverse 

func LogReverse() LogOption

LogReverse is a LogOption which indicates that the commits in the Log should be returned in reverse order from the typical "git log" ordering, ie. each commit's parents appear before the commit itself.

func LogStartCommit 

func LogStartCommit(startCommit string) LogOption

LogStartCommit is a LogOption which makes Log return commits starting from startCommit.

type Ref 

type Ref struct {
	Value string `json:"value"`
}

Ref represents a single ref, as returned by the API.

type RefsMap 

type RefsMap map[string]Ref

RefsMap is the result of a request to REFS_URL.

type Repo 

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

Repo is an object used for interacting with a single Git repo using Gitiles.

func NewRepo 

func NewRepo(url string, c *http.Client) *Repo

NewRepo creates and returns a new Repo object.

func (*Repo) Branches 

func (r *Repo) Branches(ctx context.Context) ([]*git.Branch, error)

Branches returns the list of branches in the repo.

func (*Repo) Details 

func (r *Repo) Details(ctx context.Context, ref string) (*vcsinfo.LongCommit, error)

Details returns a vcsinfo.LongCommit for the given commit.

func (*Repo) DownloadFile 

func (r *Repo) DownloadFile(ctx context.Context, srcPath, dstPath string) error

DownloadFile downloads the current version of the given file from the main branch of the Repo.

func (*Repo) DownloadFileAtRef 

func (r *Repo) DownloadFileAtRef(ctx context.Context, srcPath, ref, dstPath string) error

DownloadFileAtRef downloads the given file at the given ref.

func (*Repo) GetTreeDiffs 

func (r *Repo) GetTreeDiffs(ctx context.Context, ref string) ([]*TreeDiff, error)

GetTreeDiffs returns a slice of TreeDiffs for the given commit.

func (*Repo) ListDir 

func (r *Repo) ListDir(ctx context.Context, dir string) ([]os.FileInfo, error)

ListDir reads the given directory on the main branch. Returns a slice of file names and a slice of dir names, relative to the given directory, or any error which occurred.

func (*Repo) ListDirAtRef 

func (r *Repo) ListDirAtRef(ctx context.Context, dir, ref string) ([]os.FileInfo, error)

ListDirAtRef reads the given directory at the given ref. Returns a slice of file names and a slice of dir names, relative to the given directory, or any error which occurred.

func (*Repo) ListFilesRecursive 

func (r *Repo) ListFilesRecursive(ctx context.Context, dir string) ([]string, error)

ListFilesRecursive returns a list of all file paths, relative to the given directory, under the given directory on the main branch.

func (*Repo) ListFilesRecursiveAtRef 

func (r *Repo) ListFilesRecursiveAtRef(ctx context.Context, topDir, ref string) ([]string, error)

ListFilesRecursiveAtRef returns a list of all file paths, relative to the given directory, under the given directory at the given ref.

func (*Repo) Log 

func (r *Repo) Log(ctx context.Context, logExpr string, opts ...LogOption) ([]*vcsinfo.LongCommit, error)

Log returns Gitiles' equivalent to "git log" for the given expression.

func (*Repo) LogFirstParent 

func (r *Repo) LogFirstParent(ctx context.Context, from, to string, opts ...LogOption) ([]*vcsinfo.LongCommit, error)

LogFirstParent is equivalent to "git log --first-parent A..B", ie. it only returns commits which are reachable from A by following the first parent (the "main" branch) but not from B. LogFirstParent is incompatible with LogPath.

func (*Repo) LogFn 

func (r *Repo) LogFn(ctx context.Context, logExpr string, fn func(context.Context, *vcsinfo.LongCommit) error, opts ...LogOption) error

LogFn runs the given function for each commit in the log for the given expression. It stops when ErrStopIteration is returned.

func (*Repo) LogFnBatch 

func (r *Repo) LogFnBatch(ctx context.Context, logExpr string, fn func(context.Context, []*vcsinfo.LongCommit) error, opts ...LogOption) error

LogFnBatch is the same as LogFn but it runs the given function over batches of commits.

func (*Repo) LogLinear 

func (r *Repo) LogLinear(ctx context.Context, from, to string, opts ...LogOption) ([]*vcsinfo.LongCommit, error)

LogLinear is equivalent to "git log --first-parent --ancestry-path from..to", ie. it only returns commits which are on the direct path from A to B, and only on the "main" branch. This is as opposed to "git log from..to" which returns all commits which are ancestors of 'to' but not 'from'. LogLinear is incompatible with LogPath.

func (*Repo) ReadFile 

func (r *Repo) ReadFile(ctx context.Context, srcPath string) ([]byte, error)

ReadFile reads the current version of the given file from the main branch of the Repo.

func (*Repo) ReadFileAtRef 

func (r *Repo) ReadFileAtRef(ctx context.Context, srcPath, ref string) ([]byte, error)

ReadFileAtRef reads the given file at the given ref.

func (*Repo) ReadObject 

func (r *Repo) ReadObject(ctx context.Context, path, ref string) (os.FileInfo, []byte, error)

ReadObject reads the given object at the given ref, returning its contents and FileInfo.

func (*Repo) ResolveRef 

func (r *Repo) ResolveRef(ctx context.Context, ref string) (string, error)

ResolveRef resolves the given ref to a commit hash.

func (*Repo) Tags 

func (r *Repo) Tags(ctx context.Context) (map[string]string, error)

Tags returns the list of tags in the repo. The returned map has tag names as keys and commit hashes as values.

func (*Repo) URL 

func (r *Repo) URL() string

URL returns the repo URL.

type TreeDiff 

type TreeDiff struct {
	// Type can be one of Copy, Rename, Add, Delete, Modify.
	Type string `json:"type"`
	// Previous location of the changed file.
	OldPath string `json:"old_path"`
	// New location of the changed file.
	NewPath string `json:"new_path"`
}

TreeDiff represents a change to a file in a Commit.

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.