Documentation ¶
Overview ¶
Package git is a low level and highly extensible git client library for reading repositories from git servers. It is written in Go from scratch, without any C dependencies.
We have been following the open/close principle in its design to facilitate extensions.
Small example extracting the commits from a repository:
func ExampleBasic_printCommits() { r, err := git.NewRepository("https://github.com/src-d/go-git", nil) if err != nil { panic(err) } if err := r.Pull("origin", "refs/heads/master"); err != nil { panic(err) } iter := r.Commits() defer iter.Close() for { commit, err := iter.Next() if err != nil { if err == io.EOF { break } panic(err) } fmt.Println(commit) } }
Index ¶
- Constants
- Variables
- func SortCommits(l []*Commit)
- type Action
- type Blame
- type Blob
- type Change
- type Changes
- type Commit
- func (c *Commit) Blame(path string) (*Blame, error)
- func (c *Commit) Decode(o core.Object) (err error)
- func (c *Commit) File(path string) (file *File, err error)
- func (c *Commit) ID() core.Hash
- func (c *Commit) NumParents() int
- func (c *Commit) Parents() *CommitIter
- func (c *Commit) References(path string) ([]*Commit, error)
- func (c *Commit) String() string
- func (c *Commit) Tree() *Tree
- func (c *Commit) Type() core.ObjectType
- type CommitIter
- type File
- type FileIter
- type Hash
- type Object
- type Remote
- func (r *Remote) Capabilities() *common.Capabilities
- func (r *Remote) Connect() error
- func (r *Remote) DefaultBranch() string
- func (r *Remote) Fetch(req *common.GitUploadPackRequest) (io.ReadCloser, error)
- func (r *Remote) FetchDefaultBranch() (io.ReadCloser, error)
- func (r *Remote) Head() (core.Hash, error)
- func (r *Remote) Info() *common.GitUploadPackInfo
- func (r *Remote) Ref(refName string) (core.Hash, error)
- func (r *Remote) Refs() map[string]core.Hash
- type Repository
- func (r *Repository) Blob(h core.Hash) (*Blob, error)
- func (r *Repository) Commit(h core.Hash) (*Commit, error)
- func (r *Repository) Commits() (*CommitIter, error)
- func (r *Repository) Head(remote string) (core.Hash, error)
- func (r *Repository) Object(h core.Hash) (Object, error)
- func (r *Repository) Pull(remoteName, branch string) (err error)
- func (r *Repository) PullDefault() (err error)
- func (r *Repository) Tag(h core.Hash) (*Tag, error)
- func (r *Repository) Tags() (*TagIter, error)
- func (r *Repository) Tree(h core.Hash) (*Tree, error)
- type Signature
- type Tag
- type TagIter
- type Tree
- type TreeEntry
- type TreeIter
- type TreeWalker
Constants ¶
const (
// DefaultRemoteName name of the default Remote, just like git command
DefaultRemoteName = "origin"
)
Variables ¶
var ( ErrMaxTreeDepth = errors.New("maximum tree depth exceeded") ErrFileNotFound = errors.New("file not found") )
New errors defined by this package.
var ( // ErrObjectNotFound object not found ErrObjectNotFound = errors.New("object not found") )
ErrUnsupportedObject trigger when a non-supported object is being decoded.
Functions ¶
Types ¶
type Blob ¶
Blob is used to store file data - it is generally a file.
func (*Blob) Decode ¶
Decode transforms a core.Object into a Blob struct.
func (*Blob) ID ¶
ID returns the object ID of the blob. The returned value will always match the current value of Blob.Hash.
ID is present to fulfill the Object interface.
func (*Blob) Reader ¶
func (b *Blob) Reader() (core.ObjectReader, error)
Reader returns a reader allow the access to the content of the blob
func (*Blob) Type ¶
func (b *Blob) Type() core.ObjectType
Type returns the type of object. It always returns core.BlobObject.
Type is present to fulfill the Object interface.
type Change ¶
type Commit ¶
type Commit struct { Hash core.Hash Author Signature Committer Signature Message string // contains filtered or unexported fields }
Commit points to a single tree, marking it as what the project looked like at a certain point in time. It contains meta-information about that point in time, such as a timestamp, the author of the changes since the last commit, a pointer to the previous commit(s), etc. http://schacon.github.io/gitbook/1_the_git_object_model.html
func (*Commit) Blame ¶
Blame returns the last commit that modified each line of a file in a repository.
The file to blame is identified by the input arguments: repo, commit and path. The output is a slice of commits, one for each line in the file.
Blaming a file is a two step process:
1. Create a linear history of the commits affecting a file. We use revlist.New for that.
2. Then build a graph with a node for every line in every file in the history of the file.
Each node (line) holds the commit where it was introduced or last modified. To achieve that we use the FORWARD algorithm described in Zimmermann, et al. "Mining Version Archives for Co-changed Lines", in proceedings of the Mining Software Repositories workshop, Shanghai, May 22-23, 2006.
Each node is assigned a commit: Start by the nodes in the first commit. Assign that commit as the creator of all its lines.
Then jump to the nodes in the next commit, and calculate the diff between the two files. Newly created lines get assigned the new commit as its origin. Modified lines also get this new commit. Untouched lines retain the old commit.
All this work is done in the assignOrigin function which holds all the internal relevant data in a "blame" struct, that is not exported.
TODO: ways to improve the efficiency of this function:
1. Improve revlist
2. Improve how to traverse the history (example a backward traversal will be much more efficient)
TODO: ways to improve the function in general:
1. Add memoization between revlist and assign.
2. It is using much more memory than needed, see the TODOs below.
func (*Commit) Decode ¶
Decode transforms a core.Object into a Commit struct.
func (*Commit) File ¶
File returns the file with the specified "path" in the commit and a nil error if the file exists. If the file does not exist, it returns a nil file and the ErrFileNotFound error.
func (*Commit) ID ¶
ID returns the object ID of the commit. The returned value will always match the current value of Commit.Hash.
ID is present to fulfill the Object interface.
func (*Commit) NumParents ¶
NumParents returns the number of parents in a commit.
func (*Commit) Parents ¶
func (c *Commit) Parents() *CommitIter
Parents return a CommitIter to the parent Commits
func (*Commit) References ¶
References returns a References for the file at "path", the commits are sorted in commit order. It stops searching a branch for a file upon reaching the commit were the file was created.
Caveats:
- Moves and copies are not currently supported.
- Cherry-picks are not detected unless there are no commits between them and therefore can appear repeated in the list. (see git path-id for hints on how to fix this).
func (*Commit) Type ¶
func (c *Commit) Type() core.ObjectType
Type returns the type of object. It always returns core.CommitObject.
Type is present to fulfill the Object interface.
type CommitIter ¶
type CommitIter struct { core.ObjectIter // contains filtered or unexported fields }
CommitIter provides an iterator for a set of commits.
func NewCommitIter ¶
func NewCommitIter(r *Repository, iter core.ObjectIter) *CommitIter
NewCommitIter returns a CommitIter for the given repository and underlying object iterator.
The returned CommitIter will automatically skip over non-commit objects.
func (*CommitIter) Next ¶
func (iter *CommitIter) Next() (*Commit, error)
Next moves the iterator to the next commit and returns a pointer to it. If it has reached the end of the set it will return io.EOF.
type File ¶
File represents git file objects.
func (*File) Contents ¶
Contents returns the contents of a file as a string.
type FileIter ¶
type FileIter struct {
// contains filtered or unexported fields
}
func NewFileIter ¶
func NewFileIter(r *Repository, t *Tree) *FileIter
type Object ¶
Object is a generic representation of any git object. It is implemented by Commit, Tree, Blob and Tag, and includes the functions that are common to them.
Object is returned when an object could of any type. It is frequently used with a type cast to acquire the specific type of object:
func process(obj Object) { switch o := obj.(type) { case *Commit: // o is a Commit case *Tree: // o is a Tree case *Blob: // o is a Blob case *Tag: // o is a Tag } }
This interface is intentionally different from core.Object, which is a lower level interface used by storage implementations to read and write objects.
type Remote ¶
type Remote struct { Endpoint common.Endpoint Auth common.AuthMethod // contains filtered or unexported fields }
Remote represents a connection to a remote repository
func NewAuthenticatedRemote ¶
func NewAuthenticatedRemote(url string, auth common.AuthMethod) (*Remote, error)
NewAuthenticatedRemote returns a new Remote using the given AuthMethod, using as client http.DefaultClient
func NewRemote ¶
NewRemote returns a new Remote, using as client http.DefaultClient
func (*Remote) Capabilities ¶
func (r *Remote) Capabilities() *common.Capabilities
Capabilities returns the remote capabilities
func (*Remote) DefaultBranch ¶
DefaultBranch returns the name of the remote's default branch
func (*Remote) Fetch ¶
func (r *Remote) Fetch(req *common.GitUploadPackRequest) (io.ReadCloser, error)
Fetch returns a reader using the request
func (*Remote) FetchDefaultBranch ¶
func (r *Remote) FetchDefaultBranch() (io.ReadCloser, error)
FetchDefaultBranch returns a reader for the default branch
func (*Remote) Info ¶
func (r *Remote) Info() *common.GitUploadPackInfo
Info returns the git-upload-pack info
func (*Remote) Ref ¶
Ref returns the Hash pointing the given refName
type Repository ¶
type Repository struct { Remotes map[string]*Remote Storage core.ObjectStorage }
Repository git repository struct
func NewPlainRepository ¶
func NewPlainRepository() *Repository
NewPlainRepository creates a new repository without remotes
func NewRepository ¶
func NewRepository(url string, auth common.AuthMethod) (*Repository, error)
NewRepository creates a new repository setting remote as default remote
func NewRepositoryFromFS ¶
func NewRepositoryFromFS(fs fs.FS, path string) (*Repository, error)
NewRepositoryFromFS creates a new repository from an standard git repository on disk.
Repositories created like this don't hold a local copy of the original repository objects, instead all queries are resolved by looking at the original repository packfile. This is very cheap in terms of memory and allows to process repositories bigger than your memory.
To be able to use git repositories this way, you must run "git gc" on them beforehand.
func (*Repository) Blob ¶
func (r *Repository) Blob(h core.Hash) (*Blob, error)
Blob returns the blob with the given hash
func (*Repository) Commit ¶
func (r *Repository) Commit(h core.Hash) (*Commit, error)
Commit return the commit with the given hash
func (*Repository) Commits ¶
func (r *Repository) Commits() (*CommitIter, error)
Commits decode the objects into commits
func (*Repository) Head ¶
func (r *Repository) Head(remote string) (core.Hash, error)
Head returns the hash of the HEAD of the repository or the head of a remote, if one is passed.
func (*Repository) Object ¶
func (r *Repository) Object(h core.Hash) (Object, error)
Object returns an object with the given hash.
func (*Repository) Pull ¶
func (r *Repository) Pull(remoteName, branch string) (err error)
Pull connect and fetch the given branch from the given remote, the branch should be provided with the full path not only the abbreviation, eg.: "refs/heads/master"
func (*Repository) PullDefault ¶
func (r *Repository) PullDefault() (err error)
PullDefault like Pull but retrieve the default branch from the default remote
func (*Repository) Tag ¶
func (r *Repository) Tag(h core.Hash) (*Tag, error)
Tag returns a tag with the given hash.
func (*Repository) Tags ¶
func (r *Repository) Tags() (*TagIter, error)
Tags returns a TagIter that can step through all of the annotated tags in the repository.
type Signature ¶
Signature represents an action signed by a person
func (*Signature) Decode ¶
Decode decodes a byte slice into a signature
type Tag ¶
type Tag struct { Hash core.Hash Name string Tagger Signature Message string TargetType core.ObjectType Target core.Hash // contains filtered or unexported fields }
Tag represents an annotated tag object. It points to a single git object of any type, but tags typically are applied to commit or blob objects. It provides a reference that associates the target with a tag name. It also contains meta-information about the tag, including the tagger, tag date and message.
https://git-scm.com/book/en/v2/Git-Internals-Git-References#Tags
func (*Tag) Blob ¶
Blob returns the blob pointed to by the tag. If the tag points to a different type of object ErrUnsupportedObject will be returned.
func (*Tag) Commit ¶
Commit returns the commit pointed to by the tag. If the tag points to a different type of object ErrUnsupportedObject will be returned.
func (*Tag) Decode ¶
Decode transforms a core.Object into a Tag struct.
func (*Tag) ID ¶
ID returns the object ID of the tag, not the object that the tag references. The returned value will always match the current value of Tag.Hash.
ID is present to fulfill the Object interface.
func (*Tag) Object ¶
Object returns the object pointed to by the tag.
func (*Tag) String ¶
String returns the meta information contained in the tag as a formatted string.
func (*Tag) Tree ¶
Tree returns the tree pointed to by the tag. If the tag points to a commit object the tree of that commit will be returned. If the tag does not point to a commit or tree object ErrUnsupportedObject will be returned.
func (*Tag) Type ¶
func (t *Tag) Type() core.ObjectType
Type returns the type of object. It always returns core.TagObject.
Type is present to fulfill the Object interface.
type TagIter ¶
type TagIter struct { core.ObjectIter // contains filtered or unexported fields }
TagIter provides an iterator for a set of tags.
func NewTagIter ¶
func NewTagIter(r *Repository, iter core.ObjectIter) *TagIter
NewTagIter returns a TagIter for the given repository and underlying object iterator.
The returned TagIter will automatically skip over non-tag objects.
type Tree ¶
Tree is basically like a directory - it references a bunch of other trees and/or blobs (i.e. files and sub-directories)
func (*Tree) Decode ¶
Decode transform an core.Object into a Tree struct
func (*Tree) File ¶
File returns the hash of the file identified by the `path` argument. The path is interpreted as relative to the tree receiver.
func (*Tree) Files ¶
Files returns a FileIter allowing to iterate over the Tree
func (*Tree) ID ¶
ID returns the object ID of the tree. The returned value will always match the current value of Tree.Hash.
ID is present to fulfill the Object interface.
func (*Tree) Type ¶
func (t *Tree) Type() core.ObjectType
Type returns the type of object. It always returns core.TreeObject.
type TreeEntry ¶
TreeEntry represents a file
type TreeIter ¶
type TreeIter struct {
// contains filtered or unexported fields
}
TreeEntryIter facilitates iterating through the descendent subtrees of a Tree.
func NewTreeIter ¶
func NewTreeIter(r *Repository, t *Tree) *TreeIter
NewTreeIter returns a new TreeIter instance
type TreeWalker ¶
type TreeWalker struct {
// contains filtered or unexported fields
}
TreeWalker provides a means of walking through all of the entries in a Tree.
func NewTreeWalker ¶
func NewTreeWalker(r *Repository, t *Tree) *TreeWalker
NewTreeWalker returns a new TreeWalker for the given repository and tree.
It is the caller's responsibility to call Close() when finished with the tree walker.
func (*TreeWalker) Close ¶
func (w *TreeWalker) Close()
Close releases any resources used by the TreeWalker.
func (*TreeWalker) Next ¶
func (w *TreeWalker) Next() (name string, entry TreeEntry, obj Object, err error)
Next returns the next object from the tree. Objects are returned in order and subtrees are included. After the last object has been returned further calls to Next() will return io.EOF.
In the current implementation any objects which cannot be found in the underlying repository will be skipped automatically. It is possible that this may change in future versions.
func (*TreeWalker) Tree ¶
func (w *TreeWalker) Tree() *Tree
Tree returns the tree that the tree walker most recently operated on.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Go-git needs the packfile and the refs of the repo.
|
Go-git needs the packfile and the refs of the repo. |
common
Package common contains utils used by the clients
|
Package common contains utils used by the clients |
http
Package http implements a HTTP client for go-git.
|
Package http implements a HTTP client for go-git. |
ssh
Package ssh implements a ssh client for go-git.
|
Package ssh implements a ssh client for go-git. |
common
module
|
|
Package core implement the core interfaces and structs used by go-git
|
Package core implement the core interfaces and structs used by go-git |
+build ignore
|
+build ignore |
Package diff implements line oriented diffs, similar to the ancient Unix diff command.
|
Package diff implements line oriented diffs, similar to the ancient Unix diff command. |
examples
|
|
formats
|
|
idxfile
== Original (version 1) pack-*.idx files have the following format:
|
== Original (version 1) pack-*.idx files have the following format: |
packfile
Package packfile documentation:
|
Package packfile documentation: |
storage
|
|
utils
|
|