Comment the new code in the Git package

src/git/git.go

@@ -17,13 +17,23 @@ import (
 	gitssh "gopkg.in/src-d/go-git.v4/plumbing/transport/ssh"
 )
 
+// Repository represents a Git repository, as an abstraction layer above the
+// go-git library in order to also store the current configuration and the
+// authentication data needed to talk to the Git remote.
 type Repository struct {
 	Repo *gogit.Repository
 	cfg  config.GitSettings
 	auth *gitssh.PublicKeys
 }
 
+// NewRepository creates a new instance of the Repository structure and fills
+// it accordingly to the current configuration.
+// Returns a boolean if the clone path doesn't contain a valid Git repository
+// and needs the repository to be cloned from remote before it is usable.
+// Returns an error if there was an issue opening the clone path or loading
+// authentication data.
 func NewRepository(cfg config.GitSettings) (r *Repository, invalidRepo bool, err error) {
+	// Load the repository.
 	repo, err := gogit.PlainOpen(cfg.ClonePath)
 	if err != nil {
 		if err == gogit.ErrRepositoryNotExists {
@@ -33,11 +43,14 @@ func NewRepository(cfg config.GitSettings) (r *Repository, invalidRepo bool, err
 		}
 	}
 
+	// Fill the structure instance with the gogit.Repository instance and the
+	// configuration.
 	r = &Repository{
 		Repo: repo,
 		cfg:  cfg,
 	}
 
+	// Load authentication data in the structure instance.
 	err = r.getAuth()
 	return
 }
@@ -52,13 +65,13 @@ func NewRepository(cfg config.GitSettings) (r *Repository, invalidRepo bool, err
 // whether the clone path already exists, or synchronising the repo with the
 // remote.
 func (r *Repository) Sync(dontClone bool) (err error) {
-	// Check whether the clone path already exists
+	// Check whether the clone path already exists.
 	exists, err := dirExists(r.cfg.ClonePath)
 	if err != nil {
 		return
 	}
 
-	// Check whether the clone path is a Git repository
+	// Check whether the clone path is a Git repository.
 	var isRepo bool
 	if isRepo, err = dirExists(r.cfg.ClonePath + "/.git"); err != nil {
 		return
@@ -99,11 +112,11 @@ func (r *Repository) Push() (err error) {
 		"clone_path": r.cfg.ClonePath,
 	}).Info("Pushing to the remote")
 
-	// Push to remote
+	// Push to remote.
 	if err = r.Repo.Push(&gogit.PushOptions{
 		Auth: r.auth,
 	}); err != nil {
-		// Check error against known non-errors
+		// Check error against known non-errors.
 		err = checkRemoteErrors(err, logrus.Fields{
 			"repo":       r.cfg.User + "@" + r.cfg.URL,
 			"clone_path": r.cfg.ClonePath,
@@ -114,22 +127,31 @@ func (r *Repository) Push() (err error) {
 	return err
 }
 
+// GetLatestCommit retrieves the latest commit from the local Git repository and
+// returns it.
+// Returns an error if there was an issue fetching the references or loading the
+// latest one.
 func (r *Repository) GetLatestCommit() (*object.Commit, error) {
-	// Retrieve latest hash
+	// Retrieve the list of references from the repository.
 	refs, err := r.Repo.References()
 	if err != nil {
 		return nil, err
 	}
 
+	// Extract the latest reference.
 	ref, err := refs.Next()
 	if err != nil {
 		return nil, err
 	}
 
+	// Load the commit matching the reference's hash and return it.
 	hash := ref.Hash()
 	return r.Repo.CommitObject(hash)
 }
 
+// Log loads the Git repository's log, with the most recent commit having the
+// given hash.
+// Returns an error if the log couldn't be loaded.
 func (r *Repository) Log(fromHash string) (object.CommitIter, error) {
 	hash := plumbing.NewHash(fromHash)
 
@@ -138,9 +160,20 @@ func (r *Repository) Log(fromHash string) (object.CommitIter, error) {
 	})
 }
 
+// GetModifiedAndRemovedFiles takes to commits and returns the name of files
+// that were added, modified or removed between these two commits. Note that
+// the added/modified files and the removed files are returned in two separated
+// slices, mainly because some features using this function need to load the
+// files' contents afterwards, and this is done differently depending on whether
+// the file was removed or not.
+// "from" refers to the oldest commit of both, and "to" to the latest one.
+// Returns empty slices and no error if both commits have the same hash.
+// Returns an error if there was an issue loading the repository's log, the
+// commits' stats, or retrieving a file from the repository.
 func (r *Repository) GetModifiedAndRemovedFiles(
 	from *object.Commit, to *object.Commit,
 ) (modified []string, removed []string, err error) {
+	// Initialise the slices.
 	modified = make([]string, 0)
 	removed = make([]string, 0)
 
@@ -153,26 +186,35 @@ func (r *Repository) GetModifiedAndRemovedFiles(
 		return
 	}
 
+	// Iterate over the commits contained in the commit's log.
 	err = iter.ForEach(func(commit *object.Commit) error {
+		// If the commit was done by the manager, go to the next iteration.
 		if commit.Author.Email == r.cfg.CommitsAuthor.Email {
 			return nil
 		}
 
+		// If the current commit is the oldest one requested, break the loop.
 		if commit.Hash.String() == from.Hash.String() {
 			return storer.ErrStop
 		}
 
+		// Load stats from the current commit.
 		stats, err := commit.Stats()
 		if err != nil {
 			return err
 		}
 
+		// Iterate over the files contained in the commit's stats.
 		for _, stat := range stats {
+			// Try to access the file's content.
 			_, err := commit.File(stat.Name)
 			if err != nil && err != object.ErrFileNotFound {
 				return err
 			}
 
+			// If the content couldn't be retrieved, it means the file was
+			// removed in this commit, else it means that it was either added or
+			// modified.
 			if err == object.ErrFileNotFound {
 				removed = append(removed, stat.Name)
 			} else {
@@ -186,24 +228,34 @@ func (r *Repository) GetModifiedAndRemovedFiles(
 	return
 }
 
+// GetFilesContentsAtCommit retrieves the state of the repository at a given
+// commit, and returns a map contaning the contents of all files in the repository
+// at this time.
+// Returns an error if there was an issue loading the commit's tree, or loading
+// a file's content.
 func (r *Repository) GetFilesContentsAtCommit(commit *object.Commit) (map[string][]byte, error) {
 	var content string
 
+	// Load the commit's tree.
 	tree, err := commit.Tree()
 	if err != nil {
 		return nil, err
 	}
 
+	// Initialise the map that will be returned.
 	filesContents := make(map[string][]byte)
-
+	// Load the files from the tree.
 	files := tree.Files()
 
+	// Iterate over the files.
 	err = files.ForEach(func(file *object.File) error {
+		// Try to access the file's content at the given commit.
 		content, err = file.Contents()
 		if err != nil {
 			return err
 		}
 
+		// Append the content to the map.
 		filesContents[file.Name] = []byte(content)
 
 		return nil
@@ -217,11 +269,13 @@ func (r *Repository) GetFilesContentsAtCommit(commit *object.Commit) (map[string
 // Returns an error if there was an issue reading the private key file or
 // parsing it.
 func (r *Repository) getAuth() error {
+	// Load the private key.
 	privateKey, err := ioutil.ReadFile(r.cfg.PrivateKeyPath)
 	if err != nil {
 		return err
 	}
 
+	// Parse the private key.
 	signer, err := ssh.ParsePrivateKey(privateKey)
 	if err != nil {
 		return err
@@ -250,24 +304,24 @@ func (r *Repository) clone() (err error) {
 // tree or pulling from the remote. In the latter case, if the error is a known
 // non-error, doesn't return any error.
 func (r *Repository) pull() error {
-	// Open the repository
+	// Open the repository.
 	repo, err := gogit.PlainOpen(r.cfg.ClonePath)
 	if err != nil {
 		return err
 	}
 
-	// Get its worktree
+	// Get its worktree.
 	w, err := repo.Worktree()
 	if err != nil {
 		return err
 	}
 
-	// Pull from remote
+	// Pull from remote.
 	if err = w.Pull(&gogit.PullOptions{
 		RemoteName: "origin",
 		Auth:       r.auth,
 	}); err != nil {
-		// Check error against known non-errors
+		// Check error against known non-errors.
 		err = checkRemoteErrors(err, logrus.Fields{
 			"clone_path": r.cfg.ClonePath,
 			"error":      err,
@@ -301,7 +355,7 @@ func dirExists(path string) (bool, error) {
 func checkRemoteErrors(err error, logFields logrus.Fields) error {
 	var nonError bool
 
-	// Check against known non-errors
+	// Check against known non-errors.
 	switch err {
 	case gogit.NoErrAlreadyUpToDate:
 		nonError = true
@@ -314,7 +368,7 @@ func checkRemoteErrors(err error, logFields logrus.Fields) error {
 		break
 	}
 
-	// Log non-error
+	// Log non-error.
 	if nonError {
 		logrus.WithFields(logFields).Warn("Caught specific non-error")