git

README

go-git

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 srcd.works/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
• Variables
• func References(c *object.Commit, path string) ([]*object.Commit, error)
• type BlameResult
  • func Blame(c *object.Commit, path string) (*BlameResult, error)
• type CloneOptions
  • func (o *CloneOptions) Validate() error
• type FetchOptions
  • func (o *FetchOptions) Validate() error
• type FileStatus
• type Line
• type PullOptions
  • func (o *PullOptions) Validate() error
• type PushOptions
  • func (o *PushOptions) Validate() error
• type Remote
  • func (r *Remote) Config() *config.RemoteConfig
  • func (r *Remote) Fetch(o *FetchOptions) error
  • func (r *Remote) Push(o *PushOptions) (err error)
  • func (r *Remote) String() string
• type Repository
  • func Clone(s Storer, worktree billy.Filesystem, o *CloneOptions) (*Repository, error)
  • func Init(s Storer, worktree billy.Filesystem) (*Repository, error)
  • func Open(s Storer, worktree billy.Filesystem) (*Repository, error)
  • func PlainClone(path string, isBare bool, o *CloneOptions) (*Repository, error)
  • func PlainInit(path string, isBare bool) (*Repository, error)
  • func PlainOpen(path string) (*Repository, error)
  • func (r *Repository) Blob(h plumbing.Hash) (*object.Blob, error)
  • func (r *Repository) Blobs() (*object.BlobIter, error)
  • func (r *Repository) Commit(h plumbing.Hash) (*object.Commit, error)
  • func (r *Repository) Commits() (*object.CommitIter, error)
  • func (r *Repository) Config() (*config.Config, error)
  • func (r *Repository) CreateRemote(c *config.RemoteConfig) (*Remote, error)
  • func (r *Repository) DeleteRemote(name string) error
  • func (r *Repository) Fetch(o *FetchOptions) error
  • func (r *Repository) Head() (*plumbing.Reference, error)
  • func (r *Repository) Object(t plumbing.ObjectType, h plumbing.Hash) (object.Object, error)
  • func (r *Repository) Objects() (*object.ObjectIter, error)
  • func (r *Repository) Pull(o *PullOptions) error
  • func (r *Repository) Push(o *PushOptions) error
  • func (r *Repository) Reference(name plumbing.ReferenceName, resolved bool) (*plumbing.Reference, error)
  • func (r *Repository) References() (storer.ReferenceIter, error)
  • func (r *Repository) Remote(name string) (*Remote, error)
  • func (r *Repository) Remotes() ([]*Remote, error)
  • func (r *Repository) Tag(h plumbing.Hash) (*object.Tag, error)
  • func (r *Repository) Tags() (*object.TagIter, error)
  • func (r *Repository) Tree(h plumbing.Hash) (*object.Tree, error)
  • func (r *Repository) Trees() (*object.TreeIter, error)
  • func (r *Repository) Worktree() (*Worktree, error)
• type Status
  • func (s Status) File(filename string) *FileStatus
  • func (s Status) IsClean() bool
  • func (s Status) String() string
• type StatusCode
  • func (c StatusCode) String() string
• type Storer
• type Worktree
  • func (w *Worktree) Checkout(commit plumbing.Hash) error
  • func (w *Worktree) Status() (Status, error)

Constants

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

Variables

var (
	ErrMissingURL     = errors.New("URL field is required")
	ErrInvalidRefSpec = errors.New("invalid refspec")
)

var (
	ErrObjectNotFound          = errors.New("object not found")
	ErrInvalidReference        = errors.New("invalid reference, should be a tag or a branch")
	ErrRepositoryNotExists     = errors.New("repository not exists")
	ErrRepositoryAlreadyExists = errors.New("repository already exists")
	ErrRemoteNotFound          = errors.New("remote not found")
	ErrRemoteExists            = errors.New("remote already exists")
	ErrWorktreeNotProvided     = errors.New("worktree should be provided")
	ErrIsBareRepository        = errors.New("worktree not available in a bare repository")
)

var ErrWorktreeNotClean = errors.New("worktree is not clean")

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
	// 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
}

CloneOptions describes how a clone should be performed

func (*CloneOptions) Validate

func (o *CloneOptions) Validate() error

Validate validates the fields and sets 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
	// 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
}

FetchOptions describes how a fetch should be performed

func (*FetchOptions) Validate

func (o *FetchOptions) Validate() error

Validate validates the fields and sets the default values

type FileStatus

type FileStatus struct {
	Staging  StatusCode
	Worktree StatusCode
	Extra    string
}

FileStatus status of a file in the Worktree

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
	// 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
}

PullOptions describes how a pull should be performed

func (*PullOptions) Validate

func (o *PullOptions) Validate() error

Validate validates the fields and sets 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 describes how a push should be performed

func (*PushOptions) Validate

func (o *PushOptions) Validate() error

Validate validates the fields and sets 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. TODO: Sideband support

func (*Remote) String

func (r *Remote) String() string

type Repository

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

Repository giturl string, auth common.AuthMethod repository struct

func Clone

func Clone(s Storer, worktree billy.Filesystem, o *CloneOptions) (*Repository, error)

Clone a repository into the given Storer and worktree Filesystem with the given options, if worktree is nil a bare repository is created. If the given storer is not empty ErrRepositoryAlreadyExists is returned

func Init

func Init(s Storer, worktree billy.Filesystem) (*Repository, error)

Init creates an empty git repository, based on the given Storer and worktree. The worktree Filesystem is optional, if nil a bare repository is created. If the given storer is not empty ErrRepositoryAlreadyExists is returned

func Open

func Open(s Storer, worktree billy.Filesystem) (*Repository, error)

Open opens a git repository using the given Storer and worktree filesystem, if the given storer is complete empty ErrRepositoryNotExists is returned. The worktree can be nil when the repository being opened is bare, if the repository is a normal one (not bare) and worktree is nil the err ErrWorktreeNotProvided is returned

func PlainClone

func PlainClone(path string, isBare bool, o *CloneOptions) (*Repository, error)

PlainClone a repository into the path with the given options, isBare defines if the new repository will be bare or normal. If the path is not empty ErrRepositoryAlreadyExists is returned

func PlainInit

func PlainInit(path string, isBare bool) (*Repository, error)

PlainInit create an empty git repository at the given path. isBare defines if the repository will have worktree (non-bare) or not (bare), if the path is not empty ErrRepositoryAlreadyExists is returned

func PlainOpen

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

PlainOpen opens a git repository from the given path. It detects is the repository is bare or a normal one. If the path doesn't contain a valid repository ErrRepositoryNotExists is returned

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

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

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

func (*Repository) Worktree

func (r *Repository) Worktree() (*Worktree, error)

Worktree returns a worktree based on the given fs, if nil the default worktree will be used.

type Status

type Status map[string]*FileStatus

Status current status of a Worktree

func (Status) File

func (s Status) File(filename string) *FileStatus

func (Status) IsClean

func (s Status) IsClean() bool

func (Status) String

func (s Status) String() string

type StatusCode

type StatusCode int8

StatusCode status code of a file in the Worktree

const (
	Unmodified StatusCode = iota
	Untracked
	Modified
	Added
	Deleted
	Renamed
	Copied
	UpdatedButUnmerged
)

func (StatusCode) String

func (c StatusCode) String() string

type Storer

type Storer interface {
	storer.EncodedObjectStorer
	storer.ReferenceStorer
	storer.ShallowStorer
	storer.IndexStorer
	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 a system directory (such as `.git`) and others implementations are in memory being ephemeral

type Worktree

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

func (*Worktree) Checkout

func (w *Worktree) Checkout(commit plumbing.Hash) error

func (*Worktree) Status

func (w *Worktree) Status() (Status, error)