aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAntonio Navarro Perez <antnavper@gmail.com>2017-03-03 16:51:19 +0100
committerGitHub <noreply@github.com>2017-03-03 16:51:19 +0100
commit199317f082082fb8f168ad40a5cae134acfe4a16 (patch)
tree7a03fc0b2fd57416ae118f2692cb3b2df72304d8
parent047a795df6d5a0d5dd0782297cea918e4a4a6e10 (diff)
parente408162066eddd16434adf1ec87aaa74aaff294a (diff)
downloadgo-git-199317f082082fb8f168ad40a5cae134acfe4a16.tar.gz
Merge pull request #295 from ajnavarro/improvement/package-git-doc
improve git package documentation (fix #231)
-rw-r--r--blame.go76
-rw-r--r--references.go14
-rw-r--r--remote.go4
3 files changed, 52 insertions, 42 deletions
diff --git a/blame.go b/blame.go
index d16cf25..a88627f 100644
--- a/blame.go
+++ b/blame.go
@@ -13,44 +13,43 @@ import (
"srcd.works/go-git.v4/utils/diff"
)
+// BlameResult represents the result of a Blame operation.
type BlameResult struct {
- Path string
- Rev plumbing.Hash
+ // Path is the path of the File that we're blaming.
+ Path string
+ // Rev (Revision) is the hash of the specified Commit used to generate this result.
+ Rev plumbing.Hash
+ // Lines contains every line with its authorship.
Lines []*Line
}
-// 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.
+// Blame returns a BlameResult with the information about the last author of
+// each line from file `path` at commit `c`.
func Blame(c *object.Commit, path string) (*BlameResult, error) {
+ // The file to blame is identified by the input arguments:
+ // commit and path. commit is a Commit object obtained from a Repository. Path
+ // represents a path to a specific file contained into the repository.
+ //
+ // 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 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
@@ -84,6 +83,11 @@ func Blame(c *object.Commit, path string) (*BlameResult, error) {
return nil, err
}
+ // 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.
lines, err := newLines(finalLines, b.sliceGraph(len(b.graph)-1))
if err != nil {
return nil, err
@@ -98,8 +102,10 @@ func Blame(c *object.Commit, path string) (*BlameResult, error) {
// Line values represent the contents and author of a line in BlamedResult values.
type Line struct {
- Author string // email address of the author of the line.
- Text string // original text of the line.
+ // Author is the email address of the last author that modified the line.
+ Author string
+ // Text is the original text of the line.
+ Text string
}
func newLine(author, text string) *Line {
diff --git a/references.go b/references.go
index fe1d12b..68a54a6 100644
--- a/references.go
+++ b/references.go
@@ -10,15 +10,19 @@ import (
"github.com/sergi/go-diff/diffmatchpatch"
)
-// 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.
+// References returns a slice of Commits for the file at "path", starting from
+// the commit provided that contains the file from the provided path. The last
+// commit into the returned slice is the commit where the file was created.
+// If the provided commit does not contains the specified path, a nil slice is
+// returned. The commits are sorted in commit order, newer to older.
//
// 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).
+// therefore can appear repeated in the list. (see git path-id for hints on how
+// to fix this).
func References(c *object.Commit, path string) ([]*object.Commit, error) {
var result []*object.Commit
seen := make(map[plumbing.Hash]struct{}, 0)
diff --git a/remote.go b/remote.go
index fe7993c..580e6b0 100644
--- a/remote.go
+++ b/remote.go
@@ -22,7 +22,7 @@ import (
var NoErrAlreadyUpToDate = errors.New("already up-to-date")
-// Remote represents a connection to a remote repository
+// Remote represents a connection to a remote repository.
type Remote struct {
c *config.RemoteConfig
s storage.Storer
@@ -32,7 +32,7 @@ func newRemote(s storage.Storer, c *config.RemoteConfig) *Remote {
return &Remote{s: s, c: c}
}
-// Config return the config
+// Config returns the RemoteConfig object used to instantiate this Remote.
func (r *Remote) Config() *config.RemoteConfig {
return r.c
}