examples & documentation: PlainClone with Basic Authentication (Password & Access Token) (#990)

examples: PlainClone with Basic Authentication (Password & Access Token)

Author: Colton J. McCurdy

_examples/README.md

@@ -6,6 +6,10 @@ Here you can find a list of annotated _go-git_ examples:
 - [showcase](showcase/main.go) - A small showcase of the capabilities of _go-git_
 - [open](open/main.go) - Opening a existing repository cloned by _git_
 - [clone](clone/main.go) - Cloning a repository
+    - [username and password](clone/auth/basic/username_password/main.go) - Cloning a repository
+      using a username and password
+    - [personal access token](clone/auth/basic/access_token/main.go) - Cloning
+      a repository using a GitHub personal access token
 - [commit](commit/main.go) - Commit changes to the current branch to an existent repository
 - [push](push/main.go) - Push repository to default remote (origin)
 - [pull](pull/main.go) - Pull changes from a remote repository

_examples/clone/auth/basic/access_token/main.go

@@ -0,0 +1,40 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	git "gopkg.in/src-d/go-git.v4"
+	. "gopkg.in/src-d/go-git.v4/_examples"
+	"gopkg.in/src-d/go-git.v4/plumbing/transport/http"
+)
+
+func main() {
+	CheckArgs("<url>", "<directory>", "<github_access_token>")
+	url, directory, token := os.Args[1], os.Args[2], os.Args[3]
+
+	// Clone the given repository to the given directory
+	Info("git clone %s %s", url, directory)
+
+	r, err := git.PlainClone(directory, false, &git.CloneOptions{
+		// The intended use of a GitHub personal access token is in replace of your password
+		// because access tokens can easily be revoked.
+		// https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/
+		Auth: &http.BasicAuth{
+			Username: "abc123", // yes, this can be anything except an empty string
+			Password: token,
+		},
+		URL:      url,
+		Progress: os.Stdout,
+	})
+	CheckIfError(err)
+
+	// ... retrieving the branch being pointed by HEAD
+	ref, err := r.Head()
+	CheckIfError(err)
+	// ... retrieving the commit object
+	commit, err := r.CommitObject(ref.Hash())
+	CheckIfError(err)
+
+	fmt.Println(commit)
+}

_examples/clone/auth/basic/username_password/main.go

@@ -0,0 +1,37 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	git "gopkg.in/src-d/go-git.v4"
+	. "gopkg.in/src-d/go-git.v4/_examples"
+	"gopkg.in/src-d/go-git.v4/plumbing/transport/http"
+)
+
+func main() {
+	CheckArgs("<url>", "<directory>", "<github_username>", "<github_password>")
+	url, directory, username, password := os.Args[1], os.Args[2], os.Args[3], os.Args[4]
+
+	// Clone the given repository to the given directory
+	Info("git clone %s %s", url, directory)
+
+	r, err := git.PlainClone(directory, false, &git.CloneOptions{
+		Auth: &http.BasicAuth{
+			Username: username,
+			Password: password,
+		},
+		URL:      url,
+		Progress: os.Stdout,
+	})
+	CheckIfError(err)
+
+	// ... retrieving the branch being pointed by HEAD
+	ref, err := r.Head()
+	CheckIfError(err)
+	// ... retrieving the commit object
+	commit, err := r.CommitObject(ref.Hash())
+	CheckIfError(err)
+
+	fmt.Println(commit)
+}

example_test.go

@@ -11,6 +11,7 @@ import (
 	"gopkg.in/src-d/go-git.v4"
 	"gopkg.in/src-d/go-git.v4/config"
 	"gopkg.in/src-d/go-git.v4/plumbing"
+	"gopkg.in/src-d/go-git.v4/plumbing/transport/http"
 	"gopkg.in/src-d/go-git.v4/storage/memory"
 
 	"gopkg.in/src-d/go-billy.v4/memfs"
@@ -69,6 +70,52 @@ func ExamplePlainClone() {
 	// Output: Initial changelog
 }
 
+func ExamplePlainClone_usernamePassword() {
+	// Tempdir to clone the repository
+	dir, err := ioutil.TempDir("", "clone-example")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	defer os.RemoveAll(dir) // clean up
+
+	// Clones the repository into the given dir, just as a normal git clone does
+	_, err = git.PlainClone(dir, false, &git.CloneOptions{
+		URL: "https://github.com/git-fixtures/basic.git",
+		Auth: &http.BasicAuth{
+			Username: "username",
+			Password: "password",
+		},
+	})
+
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExamplePlainClone_accessToken() {
+	// Tempdir to clone the repository
+	dir, err := ioutil.TempDir("", "clone-example")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	defer os.RemoveAll(dir) // clean up
+
+	// Clones the repository into the given dir, just as a normal git clone does
+	_, err = git.PlainClone(dir, false, &git.CloneOptions{
+		URL: "https://github.com/git-fixtures/basic.git",
+		Auth: &http.BasicAuth{
+			Username: "abc123", // anything except an empty string
+			Password: "github_access_token",
+		},
+	})
+
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+
 func ExampleRepository_References() {
 	r, _ := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{
 		URL: "https://github.com/git-fixtures/basic.git",