git

README

go-git

Documentation

Overview

Package blame contains blaming functionality for files in the repo.

Blaming a file is finding what commit was the last to modify each of the lines in the file, therefore the output of a blaming operation is usualy a slice of commits, one commit per line in the file.

This package also provides a pretty print function to output the results of a blame in a similar format to the git-blame command.

Package revlist allows to create the revision history of a file, this is, the list of commits in the past that affect the file.

The general idea is to traverse the git commit graph backward, flattening the graph into a linear history, and skipping commits that are irrelevant for the particular file.

There is no single answer for this operation. The git command "git-revlist" returns different histories depending on its arguments and some internal heuristics.

The current implementation tries to get something similar to what you whould get using git-revlist. See the failing tests for some insight about how the current implementation and git-revlist differs.

Another way to get the revision history for a file is: git log --follow -p -- file

Index

• Constants
• Variables
• func SortCommits(l []*Commit)
• type Blame
• type Blob
  • func (b *Blob) Decode(o core.Object) error
  • func (b *Blob) Reader() io.Reader
• type Commit
  • func (c *Commit) Blame(path string) (*Blame, error)
  • func (c *Commit) Decode(o core.Object) error
  • func (c *Commit) File(path string) (file *File, err error)
  • 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
• type CommitIter
  • func NewCommitIter(r *Repository) *CommitIter
  • func (i *CommitIter) Add(o core.Object)
  • func (i *CommitIter) Close()
  • func (i *CommitIter) Next() (*Commit, error)
• type File
  • func (f *File) Contents() string
  • func (f *File) Lines() []string
• type Hash
• type Remote
  • func NewAuthenticatedRemote(url string, auth common.AuthMethod) (*Remote, error)
  • func NewRemote(url string) (*Remote, error)
  • 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) Info() *common.GitUploadPackInfo
  • func (r *Remote) Ref(refName string) (core.Hash, error)
  • func (r *Remote) Refs() map[string]core.Hash
• type Repository
  • func NewPlainRepository() *Repository
  • func NewRepository(url string, auth common.AuthMethod) (*Repository, error)
  • func (r *Repository) Commit(h core.Hash) (*Commit, error)
  • func (r *Repository) Commits() *CommitIter
  • func (r *Repository) Pull(remoteName, branch string) (err error)
  • func (r *Repository) Tree(h core.Hash) (*Tree, error)
• type Signature
  • func (s *Signature) Decode(b []byte)
  • func (s *Signature) String() string
• type Tree
  • func (t *Tree) Decode(o core.Object) error
  • func (t *Tree) File(path string) (*File, error)
  • func (t *Tree) Files() chan *File
• type TreeEntry
• type TreeIter
  • func NewTreeIter(r *Repository) *TreeIter
  • func (i *TreeIter) Add(o core.Object)
  • func (i *TreeIter) Close()
  • func (i *TreeIter) Next() (*Tree, error)

Constants

const (
	DefaultRemoteName = "origin"
)

Variables

var ErrFileNotFound = errors.New("file not found")

New errors defined by this package.

var (
	ObjectNotFoundErr = errors.New("object not found")
)

Functions

func SortCommits

func SortCommits(l []*Commit)

SortCommits sort a commit list by commit date, from older to newer.

Types

type Blame

type Blame struct {
	Path  string
	Rev   core.Hash
	Lines []*line
}

type Blob

type Blob struct {
	Hash core.Hash
	Size int64
	// contains filtered or unexported fields
}

Blob is used to store file data - it is generally a file.

func (*Blob) Decode

func (b *Blob) Decode(o core.Object) error

Decode transform an core.Object into a Blob struct

func (*Blob) Reader

func (b *Blob) Reader() io.Reader

Reader returns a reader allow the access to the content of the blob

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

func (c *Commit) Blame(path string) (*Blame, 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 asigned 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

func (c *Commit) Decode(o core.Object) error

Decode transform an core.Object into a Blob struct

func (*Commit) File

func (c *Commit) File(path string) (file *File, err error)

File returns the file with the specified "path" in the commit and a nil error if the file exists. If the file does not exists, it returns a nil file and the ErrFileNotFound error.

func (*Commit) NumParents

func (c *Commit) NumParents() int

NumParents returns the number of parents in a commit.

func (*Commit) Parents

func (c *Commit) Parents() *CommitIter

func (*Commit) References

func (c *Commit) References(path string) ([]*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).

func (*Commit) String

func (c *Commit) String() string

func (*Commit) Tree

func (c *Commit) Tree() *Tree

type CommitIter

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

func NewCommitIter

func NewCommitIter(r *Repository) *CommitIter

func (*CommitIter) Add

func (i *CommitIter) Add(o core.Object)

func (*CommitIter) Close

func (i *CommitIter) Close()

func (*CommitIter) Next

func (i *CommitIter) Next() (*Commit, error)

type File

type File struct {
	Name string
	io.Reader
	Hash core.Hash
}

File represents git file objects.

func (*File) Contents

func (f *File) Contents() string

Contents returns the contents of a file as a string.

func (*File) Lines

func (f *File) Lines() []string

Lines returns a slice of lines from the contents of a file, stripping all end of line characters. If the last line is empty (does not end in an end of line), it is also stripped.

type Hash

type Hash core.Hash

type Remote

type Remote struct {
	Endpoint common.Endpoint
	Auth     common.AuthMethod
	// contains filtered or unexported fields
}

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

func NewRemote(url string) (*Remote, error)

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

func (r *Remote) Connect() error

Connect with the endpoint

func (*Remote) DefaultBranch

func (r *Remote) DefaultBranch() string

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

func (r *Remote) Ref(refName string) (core.Hash, error)

Ref returns the Hash pointing the given refName

func (*Remote) Refs

func (r *Remote) Refs() map[string]core.Hash

Refs returns the Hash pointing the given refName

type Repository

type Repository struct {
	Remotes map[string]*Remote
	Storage *core.RAWObjectStorage
	URL     string
}

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 (*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

Commits decode the objects into commits

func (*Repository) Pull

func (r *Repository) Pull(remoteName, branch string) (err error)

func (*Repository) Tree

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

Tree return the tree with the given hash

type Signature

type Signature struct {
	Name  string
	Email string
	When  time.Time
}

Signature represents an action signed by a person

func (*Signature) Decode

func (s *Signature) Decode(b []byte)

Decode decodes a byte slice into a signature

func (*Signature) String

func (s *Signature) String() string

type Tree

type Tree struct {
	Entries map[string]TreeEntry
	Hash    core.Hash
	// contains filtered or unexported fields
}

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

func (t *Tree) Decode(o core.Object) error

Decode transform an core.Object into a Tree struct

func (*Tree) File

func (t *Tree) File(path string) (*File, error)

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

func (t *Tree) Files() chan *File

type TreeEntry

type TreeEntry struct {
	Name string
	Mode os.FileMode
	Hash core.Hash
}

TreeEntry represents a file

type TreeIter

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

func NewTreeIter

func NewTreeIter(r *Repository) *TreeIter

func (*TreeIter) Add

func (i *TreeIter) Add(o core.Object)

func (*TreeIter) Close

func (i *TreeIter) Close()

func (*TreeIter) Next

func (i *TreeIter) Next() (*Tree, error)