Merge branch 'master' of github.com:src-d/go-git into mccurdyc/Issue#969/fix-flaky-ssh-test

Author: mccurdyc

CONTRIBUTING.md

@@ -21,7 +21,8 @@ This can be done easily using the [`-s`](https://github.com/git/git/blob/b2c150d
 
 The official support channels, for both users and contributors, are:
 
-- GitHub [issues](https://github.com/src-d/go-git/issues)*
+- [StackOverflow go-git tag](https://stackoverflow.com/questions/tagged/go-git) for user questions.
+- GitHub [Issues](https://github.com/src-d/go-git/issues)* for bug reports and feature requests.
 - Slack: #go-git room in the [source{d} Slack](https://join.slack.com/t/sourced-community/shared_invite/enQtMjc4Njk5MzEyNzM2LTFjNzY4NjEwZGEwMzRiNTM4MzRlMzQ4MmIzZjkwZmZlM2NjODUxZmJjNDI1OTcxNDAyMmZlNmFjODZlNTg0YWM)
 
 *Before opening a new issue or submitting a new pull request, it's helpful to

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2017 Sourced Technologies, S.L.
+   Copyright 2018 Sourced Technologies, S.L.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

README.md

@@ -5,14 +5,14 @@
 
 It can be used to manipulate git repositories at low level *(plumbing)* or high level *(porcelain)*, through an idiomatic Go API. It also supports several types of storage, such as in-memory filesystems, or custom implementations thanks to the [`Storer`](https://godoc.org/gopkg.in/src-d/go-git.v4/plumbing/storer) interface.
 
-It's being actively develop since 2015 and is being use extensively by [source{d}](https://sourced.tech/) and [Keybase](https://keybase.io/blog/encrypted-git-for-everyone), and by many other libraries and tools.
+It's being actively developed since 2015 and is being used extensively by [source{d}](https://sourced.tech/) and [Keybase](https://keybase.io/blog/encrypted-git-for-everyone), and by many other libraries and tools.
 
 Comparison with git
 -------------------
 
 *go-git* aims to be fully compatible with [git](https://github.com/git/git), all the *porcelain* operations are implemented to work exactly as *git* does.
 
-*git* is a humongous project with years of development by thousands of contributors, making it challenging for *go-git* implement all the features. You can find a comparison of *go-git* vs *git* in the [compatibility documentation](COMPATIBILITY.md).
+*git* is a humongous project with years of development by thousands of contributors, making it challenging for *go-git* to implement all the features. You can find a comparison of *go-git* vs *git* in the [compatibility documentation](COMPATIBILITY.md).
 
 
 Installation
@@ -24,12 +24,12 @@ The recommended way to install *go-git* is:
 go get -u gopkg.in/src-d/go-git.v4/...
 ```
 
-> We use [gopkg.in](http://labix.org/gopkg.in) for having a versioned API, this means that when `go get` clones the package, is the latest tag matching `v4.*` cloned and not the master branch.
+> We use [gopkg.in](http://labix.org/gopkg.in) to version the API, this means that when `go get` clones the package, it's the latest tag matching `v4.*` that is cloned and not the master branch.
 
 Examples
 --------
 
-> Please note that the functions `CheckIfError` and `Info` used in the examples are from the [examples package](https://github.com/src-d/go-git/blob/master/_examples/common.go#L17) just to be used in the examples.
+> Please note that the `CheckIfError` and `Info` functions  used in the examples are from the [examples package](https://github.com/src-d/go-git/blob/master/_examples/common.go#L17) just to be used in the examples.
 
 
 ### Basic example
@@ -71,7 +71,7 @@ r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{
 
 CheckIfError(err)
 
-// Gets the HEAD history from HEAD, just like does:
+// Gets the HEAD history from HEAD, just like this command:
 Info("git log")
 
 // ... retrieves the branch pointed by HEAD
@@ -110,7 +110,7 @@ Date:   Fri Nov 11 13:23:22 2016 +0100
 ...
 ```
 
-You can find this [example](_examples/log/main.go) and many others at the [examples](_examples) folder
+You can find this [example](_examples/log/main.go) and many others in the [examples](_examples) folder.
 
 Contribute
 ----------

_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/checkout/main.go

@@ -38,8 +38,8 @@ func main() {
 	})
 	CheckIfError(err)
 
-	// ... retrieving the commit being pointed by HEAD, it's shows that the
-	// repository is poiting to the giving commit in detached mode
+	// ... retrieving the commit being pointed by HEAD, it shows that the
+	// repository is pointing to the giving commit in detached mode
 	Info("git show-ref --head HEAD")
 	ref, err = r.Head()
 	CheckIfError(err)

_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)
+}

_examples/commit/main.go

@@ -12,13 +12,13 @@ import (
 	"gopkg.in/src-d/go-git.v4/plumbing/object"
 )
 
-// Basic example of how to commit changes to the current branch to an existent
+// Basic example of how to commit changes to the current branch to an existing
 // repository.
 func main() {
 	CheckArgs("<directory>")
 	directory := os.Args[1]
 
-	// Opens an already existent repository.
+	// Opens an already existing repository.
 	r, err := git.PlainOpen(directory)
 	CheckIfError(err)
 
@@ -44,7 +44,7 @@ func main() {
 
 	fmt.Println(status)
 
-	// Commits the current staging are to the repository, with the new file
+	// Commits the current staging area to the repository, with the new file
 	// just created. We should provide the object.Signature of Author of the
 	// commit.
 	Info("git commit -m \"example go-git commit\"")

_examples/log/main.go

@@ -23,7 +23,7 @@ func main() {
 	})
 	CheckIfError(err)
 
-	// Gets the HEAD history from HEAD, just like does:
+	// Gets the HEAD history from HEAD, just like this command:
 	Info("git log")
 
 	// ... retrieves the branch pointed by HEAD

_examples/open/main.go

@@ -14,7 +14,7 @@ func main() {
 	CheckArgs("<path>")
 	path := os.Args[1]
 
-	// We instance a new repository targeting the given path (the .git folder)
+	// We instanciate a new repository targeting the given path (the .git folder)
 	r, err := git.PlainOpen(path)
 	CheckIfError(err)
 

_examples/pull/main.go

@@ -13,7 +13,7 @@ func main() {
 	CheckArgs("<path>")
 	path := os.Args[1]
 
-	// We instance a new repository targeting the given path (the .git folder)
+	// We instance\iate a new repository targeting the given path (the .git folder)
 	r, err := git.PlainOpen(path)
 	CheckIfError(err)
 

_examples/showcase/main.go

@@ -16,7 +16,7 @@ import (
 // - Get the HEAD reference
 // - Using the HEAD reference, obtain the commit this reference is pointing to
 // - Print the commit content
-// - Using the commit, iterate all its files and print them
+// - Using the commit, iterate over all its files and print them
 // - Print all the commit history with commit messages, short hash and the
 // first line of the commit message
 func main() {

_examples/storage/README.md

@@ -6,7 +6,7 @@
 
 
 ### and what this means ...
-*git* has as very well defined storage system, the `.git` directory, present on any repository. This is the place where `git` stores al the [`objects`](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects), [`references`](https://git-scm.com/book/es/v2/Git-Internals-Git-References) and [`configuration`](https://git-scm.com/docs/git-config#_configuration_file). This information is stored in plain files.
+*git* has a very well defined storage system, the `.git` directory, present on any repository. This is the place where `git` stores all the [`objects`](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects), [`references`](https://git-scm.com/book/es/v2/Git-Internals-Git-References) and [`configuration`](https://git-scm.com/docs/git-config#_configuration_file). This information is stored in plain files.
 
 Our original **go-git** version was designed to work in memory, some time after we added support to read the `.git`, and now we have added support for fully customized [storages](https://godoc.org/gopkg.in/src-d/go-git.v4/storage#Storer).
 

_examples/tag/main.go

@@ -15,7 +15,7 @@ func main() {
 	CheckArgs("<path>")
 	path := os.Args[1]
 
-	// We instance a new repository targeting the given path (the .git folder)
+	// We instanciate a new repository targeting the given path (the .git folder)
 	r, err := git.PlainOpen(path)
 	CheckIfError(err)
 

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",

go.mod

@@ -16,7 +16,7 @@ require (
 	github.com/pkg/errors v0.8.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/sergi/go-diff v1.0.0
-	github.com/src-d/gcfg v1.3.0
+	github.com/src-d/gcfg v1.4.0
 	github.com/stretchr/testify v1.2.2 // indirect
 	github.com/xanzy/ssh-agent v0.2.0
 	golang.org/x/crypto v0.0.0-20180904163835-0709b304e793

go.sum

@@ -35,6 +35,8 @@ github.com/sergi/go-diff v1.0.0 h1:Kpca3qRNrduNnOQeazBd0ysaKrUJiIuISHxogkT9RPQ=
 github.com/sergi/go-diff v1.0.0/go.mod h1:0CfEIISq7TuYL3j771MWULgwwjU+GofnZX9QAmXWZgo=
 github.com/src-d/gcfg v1.3.0 h1:2BEDr8r0I0b8h/fOqwtxCEiq2HJu8n2JGZJQFGXWLjg=
 github.com/src-d/gcfg v1.3.0/go.mod h1:p/UMsR43ujA89BJY9duynAwIpvqEujIH/jFlfL7jWoI=
+github.com/src-d/gcfg v1.4.0 h1:xXbNR5AlLSA315x2UO+fTSSAXCDf+Ar38/6oyGbDKQ4=
+github.com/src-d/gcfg v1.4.0/go.mod h1:p/UMsR43ujA89BJY9duynAwIpvqEujIH/jFlfL7jWoI=
 github.com/stretchr/testify v1.2.2 h1:bSDNvY7ZPG5RlJ8otE/7V6gMiyenm9RtJ7IUVIAoJ1w=
 github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
 github.com/xanzy/ssh-agent v0.2.0 h1:Adglfbi5p9Z0BmK2oKU9nTG+zKfniSfnaMYB+ULd+Ro=

plumbing/reference.go

@@ -55,6 +55,36 @@ func (r ReferenceType) String() string {
 // ReferenceName reference name's
 type ReferenceName string
 
+// NewBranchReferenceName returns a reference name describing a branch based on
+// his short name.
+func NewBranchReferenceName(name string) ReferenceName {
+	return ReferenceName(refHeadPrefix + name)
+}
+
+// NewNoteReferenceName returns a reference name describing a note based on his
+// short name.
+func NewNoteReferenceName(name string) ReferenceName {
+	return ReferenceName(refNotePrefix + name)
+}
+
+// NewRemoteReferenceName returns a reference name describing a remote branch
+// based on his short name and the remote name.
+func NewRemoteReferenceName(remote, name string) ReferenceName {
+	return ReferenceName(refRemotePrefix + fmt.Sprintf("%s/%s", remote, name))
+}
+
+// NewRemoteHEADReferenceName returns a reference name describing a the HEAD
+// branch of a remote.
+func NewRemoteHEADReferenceName(remote string) ReferenceName {
+	return ReferenceName(refRemotePrefix + fmt.Sprintf("%s/%s", remote, HEAD))
+}
+
+// NewTagReferenceName returns a reference name describing a tag based on short
+// his name.
+func NewTagReferenceName(name string) ReferenceName {
+	return ReferenceName(refTagPrefix + name)
+}
+
 // IsBranch check if a reference is a branch
 func (r ReferenceName) IsBranch() bool {
 	return strings.HasPrefix(string(r), refHeadPrefix)