git

package module
v4.0.0-rc7+incompatible Latest Latest
Warning

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

Go to latest
Published: Jan 19, 2017 License: MIT Imports: 24 Imported by: 0

README

go-git GoDoc Build Status codecov.io codebeat badge

A low level and highly extensible git implementation in pure Go.

go-git aims to reach the completeness of libgit2 or jgit, nowadays covers the majority of the plumbing read operations and some of the main write operations, but lacks the main porcelain operations such as merges.

It is highly extensible, we have been following the open/close principle in its design to facilitate extensions, mainly focusing the efforts on the persistence of the objects.

... is this production ready?

The master branch represents the v4 of the library, it is currently under active development and is planned to be released in early 2017.

If you are looking for a production ready version, please take a look to the v3 which is being used in production at source{d} since August 2015 to analyze all GitHub public repositories (i.e. 16M repositories).

We recommend the use of v4 to develop new projects since it includes much new functionality and provides a more idiomatic git API

Installation

The recommended way to install go-git is:

go get -u gopkg.in/src-d/go-git.v4/...

Examples

Cloning a repository and printing the history of HEAD, just like git log does

Please note that the functions CheckIfError and Info used in the examples are from the examples package just to be used in the examples.

// Instances an in-memory git repository
r := git.NewMemoryRepository()

// Clones the given repository, creating the remote, the local branches
// and fetching the objects, exactly as:
Info("git clone https://github.com/src-d/go-siva")

err := r.Clone(&git.CloneOptions{URL: "https://github.com/src-d/go-siva"})
CheckIfError(err)

// Gets the HEAD history from HEAD, just like does:
Info("git log")

// ... retrieves the branch pointed by HEAD
ref, err := r.Head()
CheckIfError(err)

// ... retrieves the commit object
commit, err := r.Commit(ref.Hash())
CheckIfError(err)

// ... retrieves the commit history
history, err := commit.History()
CheckIfError(err)

// ... just iterates over the commits, printing it
for _, c := range history {
    fmt.Println(c)
}

Outputs:

commit ded8054fd0c3994453e9c8aacaf48d118d42991e
Author: Santiago M. Mola <santi@mola.io>
Date:   Sat Nov 12 21:18:41 2016 +0100

    index: ReadFrom/WriteTo returns IndexReadError/IndexWriteError. (#9)

commit df707095626f384ce2dc1a83b30f9a21d69b9dfc
Author: Santiago M. Mola <santi@mola.io>
Date:   Fri Nov 11 13:23:22 2016 +0100

    readwriter: fix bug when writing index. (#10)

    When using ReadWriter on an existing siva file, absolute offset for
    index entries was not being calculated correctly.
...

You can find this example and many other at the examples folder

Contribute

If you are interested on contributing to go-git, open an issue explaining which missing functionality you want to work in, and we will guide you through the implementation.

License

MIT, see LICENSE

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 := git.NewMemoryRepository()
     o := &git.CloneOptions{
         URL: "https://github.com/src-d/go-git",
     }
     if err := r.Clone(o); err != nil {
         panic(err)
     }

     iter, err := r.Commits()
     if err != nil {
         panic(err)
     }
     defer iter.Close()

     for {
         commit, err := iter.Next()
         if err != nil {
             if err == io.EOF {
                 break
             }
             panic(err)
         }

         fmt.Println(commit)
     }
}

Index

Constants

View Source
const (
	// DefaultRemoteName name of the default Remote, just like git command
	DefaultRemoteName = "origin"
)

Variables

View Source
var (
	ErrMissingURL     = errors.New("URL field is required")
	ErrInvalidRefSpec = errors.New("invalid refspec")
)
View Source
var (
	ErrObjectNotFound     = errors.New("object not found")
	ErrInvalidReference   = errors.New("invalid reference, should be a tag or a branch")
	ErrRepositoryNonEmpty = errors.New("repository non empty")
	ErrRemoteNotFound     = errors.New("remote not found")
	ErrRemoteExists       = errors.New("remote already exists")
)
View Source
var NoErrAlreadyUpToDate = errors.New("already up-to-date")

Functions

func References

func References(c *object.Commit, path string) ([]*object.Commit, error)

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).

Types

type BlameResult

type BlameResult struct {
	Path  string
	Rev   plumbing.Hash
	Lines []*Line
}

func Blame

func Blame(c *object.Commit, path string) (*BlameResult, error)

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.

type CloneOptions

type CloneOptions struct {
	// The (possibly remote) repository URL to clone from
	URL string
	// Auth credentials, if required, to use with the remote repository
	Auth transport.AuthMethod
	// Name of the remote to be added, by default `origin`
	RemoteName string
	// Remote branch to clone
	ReferenceName plumbing.ReferenceName
	// Fetch only ReferenceName if true
	SingleBranch bool
	// Limit fetching to the specified number of commits
	Depth int
}

CloneOptions describe how a clone should be perform

func (*CloneOptions) Validate

func (o *CloneOptions) Validate() error

Validate validate the fields and set the default values

type FetchOptions

type FetchOptions struct {
	// Name of the remote to fetch from. Defaults to origin.
	RemoteName string
	RefSpecs   []config.RefSpec
	// Depth limit fetching to the specified number of commits from the tip of
	// each remote branch history.
	Depth int
	// Auth credentials, if required, to use with the remote repository
	Auth transport.AuthMethod
}

FetchOptions describe how a fetch should be perform

func (*FetchOptions) Validate

func (o *FetchOptions) Validate() error

Validate validate the fields and set the default values

type Line

type Line struct {
	Author string // email address of the author of the line.
	Text   string // original text of the line.
}

Line values represent the contents and author of a line in BlamedResult values.

type PullOptions

type PullOptions struct {
	// Name of the remote to be pulled. If empty, uses the default.
	RemoteName string
	// Remote branch to clone.  If empty, uses HEAD.
	ReferenceName plumbing.ReferenceName
	// Fetch only ReferenceName if true.
	SingleBranch bool
	// Limit fetching to the specified number of commits.
	Depth int
	// Auth credentials, if required, to use with the remote repository
	Auth transport.AuthMethod
}

PullOptions describe how a pull should be perform.

func (*PullOptions) Validate

func (o *PullOptions) Validate() error

Validate validate the fields and set the default values.

type PushOptions

type PushOptions struct {
	// RemoteName is the name of the remote to be pushed to.
	RemoteName string
	// RefSpecs specify what destination ref to update with what source
	// object. A refspec with empty src can be used to delete a reference.
	RefSpecs []config.RefSpec
	// Auth credentials, if required, to use with the remote repository
	Auth transport.AuthMethod
}

PushOptions describe how a push should be performed.

func (*PushOptions) Validate

func (o *PushOptions) Validate() error

Validate validate the fields and set the default values

type Remote

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

Remote represents a connection to a remote repository

func (*Remote) Config

func (r *Remote) Config() *config.RemoteConfig

Config return the config

func (*Remote) Fetch

func (r *Remote) Fetch(o *FetchOptions) error

Fetch fetches references from the remote to the local repository. Returns nil if the operation is successful, NoErrAlreadyUpToDate if there are no changes to be fetched, or an error.

func (*Remote) Push

func (r *Remote) Push(o *PushOptions) (err error)

Push performs a push to the remote. Returns NoErrAlreadyUpToDate if the remote was already up-to-date.

TODO: Support deletes. TODO: Support pushing tags. TODO: Check if force update is given, otherwise reject non-fast forward.

func (*Remote) String

func (r *Remote) String() string

type Repository

type Repository struct {

	// Progress is where the human readable information sent by the server is
	// stored, if nil nothing is stored and the capability (if supported)
	// no-progress, is sent to the server to avoid send this information
	Progress sideband.Progress
	// contains filtered or unexported fields
}

Repository giturl string, auth common.AuthMethod repository struct

func NewFilesystemRepository

func NewFilesystemRepository(path string) (*Repository, error)

NewFilesystemRepository creates a new repository, backed by a filesystem.Storage based on a fs.OS, if you want to use a custom one you need to use the function NewRepository and build you filesystem.Storage

func NewMemoryRepository

func NewMemoryRepository() *Repository

NewMemoryRepository creates a new repository, backed by a memory.Storage

func NewRepository

func NewRepository(s Storer) (*Repository, error)

NewRepository creates a new repository with the given Storage

func (*Repository) Blob

func (r *Repository) Blob(h plumbing.Hash) (*object.Blob, error)

Blob returns the blob with the given hash

func (*Repository) Blobs

func (r *Repository) Blobs() (*object.BlobIter, error)

Blobs decodes the objects into blobs

func (*Repository) Clone

func (r *Repository) Clone(o *CloneOptions) error

Clone clones a remote repository

func (*Repository) Commit

func (r *Repository) Commit(h plumbing.Hash) (*object.Commit, error)

object.Commit return the commit with the given hash

func (*Repository) Commits

func (r *Repository) Commits() (*object.CommitIter, error)

Commits decode the objects into commits

func (*Repository) Config

func (r *Repository) Config() (*config.Config, error)

Config return the repository config

func (*Repository) CreateRemote

func (r *Repository) CreateRemote(c *config.RemoteConfig) (*Remote, error)

CreateRemote creates a new remote

func (*Repository) DeleteRemote

func (r *Repository) DeleteRemote(name string) error

DeleteRemote delete a remote from the repository and delete the config

func (*Repository) Fetch

func (r *Repository) Fetch(o *FetchOptions) error

Fetch fetches changes from a remote repository. Returns nil if the operation is successful, NoErrAlreadyUpToDate if there are no changes to be fetched, or an error.

func (*Repository) Head

func (r *Repository) Head() (*plumbing.Reference, error)

Head returns the reference where HEAD is pointing to.

func (*Repository) IsEmpty

func (r *Repository) IsEmpty() (bool, error)

IsEmpty returns true if the repository is empty

func (*Repository) Object

Object returns an object with the given hash.

func (*Repository) Objects

func (r *Repository) Objects() (*object.ObjectIter, error)

Objects returns an object.ObjectIter that can step through all of the annotated tags in the repository.

func (*Repository) Pull

func (r *Repository) Pull(o *PullOptions) error

Pull incorporates changes from a remote repository into the current branch. Returns nil if the operation is successful, NoErrAlreadyUpToDate if there are no changes to be fetched, or an error.

func (*Repository) Push

func (r *Repository) Push(o *PushOptions) error

Push pushes changes to a remote.

func (*Repository) Reference

func (r *Repository) Reference(name plumbing.ReferenceName, resolved bool) (
	*plumbing.Reference, error)

Reference returns the reference for a given reference name. If resolved is true, any symbolic reference will be resolved.

func (*Repository) References

func (r *Repository) References() (storer.ReferenceIter, error)

References returns a ReferenceIter for all references.

func (*Repository) Remote

func (r *Repository) Remote(name string) (*Remote, error)

Remote return a remote if exists

func (*Repository) Remotes

func (r *Repository) Remotes() ([]*Remote, error)

Remotes return all the remotes

func (*Repository) Tag

func (r *Repository) Tag(h plumbing.Hash) (*object.Tag, error)

Tag returns a tag with the given hash.

func (*Repository) Tags

func (r *Repository) Tags() (*object.TagIter, error)

Tags returns a object.TagIter that can step through all of the annotated tags in the repository.

func (*Repository) Tree

func (r *Repository) Tree(h plumbing.Hash) (*object.Tree, error)

Tree return the tree with the given hash

func (*Repository) Trees

func (r *Repository) Trees() (*object.TreeIter, error)

Trees decodes the objects into trees

type Storer

Storer is a generic storage of objects, references and any information related to a particular repository. Some Storer implementations persist the information in an system directory (such as `.git`) and others implementations are in memmory being ephemeral

Directories

Path Synopsis
cli
Package config storage is the implementation of git config for go-git
Package config storage is the implementation of git config for go-git
+build ignore +build ignore +build ignore +build ignore +build ignore +build ignore +build ignore +build ignore +build ignore
+build ignore +build ignore +build ignore +build ignore +build ignore +build ignore +build ignore +build ignore +build ignore
log
package plumbing implement the core interfaces and structs used by go-git
package plumbing implement the core interfaces and structs used by go-git
format/config
Package config implements decoding/encoding of git config files.
Package config implements decoding/encoding of git config files.
format/idxfile
Package idxfile implements a encoder/decoder of idx files
Package idxfile implements a encoder/decoder of idx files
format/index
Package index implements a encoder/decoder of index format files
Package index implements a encoder/decoder of index format files
format/packfile
Package packfile implements a encoder/decoder of packfile format
Package packfile implements a encoder/decoder of packfile format
format/pktline
Package pktline implements reading payloads form pkt-lines and encoding pkt-lines from payloads.
Package pktline implements reading payloads form pkt-lines and encoding pkt-lines from payloads.
protocol/packp/sideband
Package sideband implements a sideband mutiplex/demultiplexer
Package sideband implements a sideband mutiplex/demultiplexer
revlist
Package revlist implements functions to walk the objects referenced by a commit history.
Package revlist implements functions to walk the objects referenced by a commit history.
transport
Package transport includes the implementation for different transport protocols.
Package transport includes the implementation for different transport protocols.
transport/http
Package http implements a HTTP client for go-git.
Package http implements a HTTP client for go-git.
transport/internal/common
Package common implements the git pack protocol with a pluggable transport.
Package common implements the git pack protocol with a pluggable transport.
transport/server
Package server implements the git server protocol.
Package server implements the git server protocol.
transport/test
Package test implements common test suite for different transport implementations.
Package test implements common test suite for different transport implementations.
storage
filesystem
Package filesystem is a storage backend base on filesystems
Package filesystem is a storage backend base on filesystems
filesystem/internal/dotgit
https://github.com/git/git/blob/master/Documentation/gitrepository-layout.txt
https://github.com/git/git/blob/master/Documentation/gitrepository-layout.txt
memory
Package memory is a storage backend base on memory
Package memory is a storage backend base on memory
utils
binary
Package binary implements sintax-sugar functions on top of the standard library binary package
Package binary implements sintax-sugar functions on top of the standard library binary package
diff
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.

Jump to

Keyboard shortcuts

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