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: 1

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 

func (r *Repository) Object(t plumbing.ObjectType, h plumbing.Hash) (object.Object, error)

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 

type Storer interface {
	storer.EncodedObjectStorer
	storer.ReferenceStorer
	storer.ShallowStorer
	config.ConfigStorer
}

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

Source Files

View all Source files

Directories

Path Synopsis
cli
go-git
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
clone
custom_http
log
open
progress
push
remotes
showcase
storage
storage/aerospike
package plumbing implement the core interfaces and structs used by go-git
 package plumbing implement the core interfaces and structs used by go-git
difftree
difftree/internal/merkletrie
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/objfile
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.
object
protocol/packp
protocol/packp/capability
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.
storer
transport
Package transport includes the implementation for different transport protocols.
 Package transport includes the implementation for different transport protocols.
transport/client
transport/file
transport/git
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/ssh
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
test
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.
ioutil

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.