Doc puller code, fix build and use go-git Commit() function directly

src/git/git.go

@@ -4,11 +4,8 @@ import (
 	"io/ioutil"
 	"os"
 	"strings"
-	"time"
 
 	gogit "gopkg.in/src-d/go-git.v4"
-	"gopkg.in/src-d/go-git.v4/plumbing"
-	"gopkg.in/src-d/go-git.v4/plumbing/object"
 
 	"golang.org/x/crypto/ssh"
 	gitssh "gopkg.in/src-d/go-git.v4/plumbing/transport/ssh"
@@ -94,16 +91,6 @@ func dirExists(path string) (bool, error) {
 	return true, err
 }
 
-func Commit(message string, w *gogit.Worktree) (plumbing.Hash, error) {
-	return w.Commit(message, &gogit.CommitOptions{
-		Author: &object.Signature{
-			Name:  "Grafana Dashboard Manager",
-			Email: "grafana@cozycloud.cc",
-			When:  time.Now(),
-		},
-	})
-}
-
 func Push(r *gogit.Repository, keyPath string) error {
 	auth, err := getAuth(keyPath)
 	if err != nil {

src/puller/main.go

@@ -40,7 +40,7 @@ func main() {
 	}
 
 	client := grafana.NewClient(*grafanaURL, *grafanaAPIKey)
-	if err := Pull(client); err != nil {
+	if err := PullGrafanaAndCommit(client); err != nil {
 		panic(err)
 	}
 }

src/puller/puller.go

@@ -12,12 +12,16 @@ import (
 	gogit "gopkg.in/src-d/go-git.v4"
 )
 
+// diffVersion represents a dashboard version diff.
 type diffVersion struct {
 	oldVersion int
 	newVersion int
 }
 
-func Pull(client *grafana.Client) error {
+// PullGrafanaAndCommit pulls all the dashboards from Grafana then commits each
+// of them to Git except for those that have a newer or equal version number
+// already versionned in the repo
+func PullGrafanaAndCommit(client *grafana.Client) error {
 	dv := make(map[string]diffVersion)
 
 	dbVersions, err := getDashboardsVersions()
@@ -48,11 +52,14 @@ func Pull(client *grafana.Client) error {
 
 		version, ok := dbVersions[dashboard.Slug]
 		if !ok || dashboard.Version > version {
-			if err = addDashboardChangesToRepo(
-				dashboard, version, w, &dv,
-			); err != nil {
+			if err = addDashboardChangesToRepo(dashboard, w); err != nil {
 				return err
 			}
+
+			dv[dashboard.Slug] = diffVersion{
+				oldVersion: version,
+				newVersion: dashboard.Version,
+			}
 		}
 	}
 
@@ -74,9 +81,11 @@ func Pull(client *grafana.Client) error {
 	return nil
 }
 
+// addDashboardChangesToRepo writes a dashboard content in a file, then adds the
+// file to the git index so it can be comitted afterwards.
+// Returns an error if there was an issue with either of the steps.
 func addDashboardChangesToRepo(
-	dashboard *grafana.Dashboard, oldVersion int, worktree *gogit.Worktree,
-	dv *map[string]diffVersion,
+	dashboard *grafana.Dashboard, worktree *gogit.Worktree,
 ) error {
 	slugExt := dashboard.Slug + ".json"
 	if err := rewriteFile(
@@ -90,14 +99,17 @@ func addDashboardChangesToRepo(
 		return err
 	}
 
-	(*dv)[dashboard.Slug] = diffVersion{
-		oldVersion: oldVersion,
-		newVersion: dashboard.Version,
-	}
-
 	return nil
 }
 
+// rewriteFile removes a given file and re-creates it with a new content. The
+// content is provided as JSON, and is then indented before being written down.
+// We need the whole "remove then recreate" thing because, if the file already
+// exists, ioutil.WriteFile will append the content to it. However, we want to
+// replace the oldest version with another (so git can diff it), so we re-create
+// the file with the changed content.
+// Returns an error if there was an issue when removing or writing the file, or
+// indenting the JSON content.
 func rewriteFile(filename string, content []byte) error {
 	if err := os.Remove(filename); err != nil {
 		pe, ok := err.(*os.PathError)
@@ -114,6 +126,10 @@ func rewriteFile(filename string, content []byte) error {
 	return ioutil.WriteFile(filename, indentedContent, 0644)
 }
 
+// indent indents a given JSON content with tabs.
+// We need to indent the content as the Grafana API returns a one-lined JSON
+// string, which isn't great to work with.
+// Returns an error if there was an issue with the process.
 func indent(srcJSON []byte) (indentedJSON []byte, err error) {
 	buf := bytes.NewBuffer(nil)
 	if err = json.Indent(buf, srcJSON, "", "\t"); err != nil {

src/puller/versions.go

@@ -5,12 +5,17 @@ import (
 	"fmt"
 	"io/ioutil"
 	"os"
-
-	"git"
+	"time"
 
 	gogit "gopkg.in/src-d/go-git.v4"
+	"gopkg.in/src-d/go-git.v4/plumbing/object"
 )
 
+// getDashboardsVersions reads the "versions.json" file at the root of the git
+// repository and returns its content as a map.
+// If the file doesn't exist, returns an empty map.
+// Return an error if there was an issue looking for the file (except when the
+// file doesn't exist), reading it or formatting its content into a map.
 func getDashboardsVersions() (versions map[string]int, err error) {
 	versions = make(map[string]int)
 
@@ -30,6 +35,14 @@ func getDashboardsVersions() (versions map[string]int, err error) {
 	return
 }
 
+// writeVersions updates or creates the "versions.json" file at the root of the
+// git repository. It takes as parameter a map of versions computed by
+// getDashboardsVersions and a map linking a dashboard slug to an instance of
+// diffVersion instance, and uses them both to compute an updated map of
+// versions that it will convert to JSON, indent and write down into the
+// "versions.json" file.
+// Returns an error if there was an issue when conerting to JSON, indenting or
+// writing on disk.
 func writeVersions(versions map[string]int, dv map[string]diffVersion) (err error) {
 	for slug, diff := range dv {
 		versions[slug] = diff.newVersion
@@ -49,6 +62,11 @@ func writeVersions(versions map[string]int, dv map[string]diffVersion) (err erro
 	return rewriteFile(filename, indentedJSON)
 }
 
+// commitNewVersions creates a git commit from updated dashboard files (that
+// have previously been added to the git index) and an updated "versions.json"
+// file that it creates (with writeVersions) and add to the index.
+// Returns an error if there was an issue when creating the "versions.json"
+// file, adding it to the index or creating the commit.
 func commitNewVersions(
 	versions map[string]int, dv map[string]diffVersion, worktree *gogit.Worktree,
 ) (err error) {
@@ -60,15 +78,26 @@ func commitNewVersions(
 		return err
 	}
 
-	_, err = git.Commit(getCommitMessage(dv), worktree)
+	_, err = worktree.Commit(getCommitMessage(dv), &gogit.CommitOptions{
+		Author: &object.Signature{
+			Name:  "Grafana Dashboard Manager",
+			Email: "grafana@cozycloud.cc",
+			When:  time.Now(),
+		},
+	})
+
 	return
 }
 
+// getCommitMessage creates a commit message that summarises the version updates
+// included in the commit.
 func getCommitMessage(dv map[string]diffVersion) string {
 	message := "Updated dashboards\n"
 
 	for slug, diff := range dv {
-		message += fmt.Sprintf("%s: %d => %d\n", slug, diff.oldVersion, diff.newVersion)
+		message += fmt.Sprintf(
+			"%s: %d => %d\n", slug, diff.oldVersion, diff.newVersion,
+		)
 	}
 
 	return message