gitfs

Documentation

Overview

Package gitfs provides a read-only filesystem backed by a git repository.

This filesystem accesses the git state, and so for local repositories, files not committed to a branch (i.e. "dirty" or modified files) will not be visible.

This filesystem's behaviour complies with fstest.TestFS.

Usage

To use this filesystem, call New with a base URL. All reads from the filesystem are relative to this base URL. Valid schemes are 'git', 'file', 'http', 'https', 'ssh', and the same prefixed with 'git+' (e.g. 'git+ssh://example.com').

URL Format

The scheme, authority (with userinfo), path, and fragment are used by this filesystem.

Scheme may be one of:

- 'git': use the classic Git protocol, as served by 'git daemon'

- 'file': use the local filesystem (repo can be bare or not)

- 'http'/'https': use the Smart HTTP protocol

- 'ssh': use the SSH protocol

See https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols for more on these protocols.

Authority points to the remote git server hostname (and optional port, if applicable). The userinfo subcomponent (i.e. 'user:password@...') can be used for authenticated schemes like 'https' and 'ssh'.

Path is a composite of the path to the repository and the path to a directory referenced within. The '//' sequence (double forward-slash) is used to separate the repository from the path. If no '//' is present in the path, the filesystem will be rooted at the root directory of the repository.

Fragment is used to specify which branch or tag to reference. When not specified, the repository's default branch will be chosen. Branches are referenced by short name (such as '#main') or by the long form prefixed with '#refs/heads/'. Valid examples are '#develop', '#refs/heads/mybranch', etc... Tags are referenced by long form, prefixed with 'refs/tags/'. Valid examples are '#refs/tags/v1', '#refs/tags/mytag', etc...

Here are a few more examples of URLs valid for this filesystem:

git+https://github.com/hairyhenderson/gomplate//docs-src/content/functions
git+file:///repos/go-which
git+https://github.com/hairyhenderson/go-which//cmd/which#refs/tags/v0.1.0
git+ssh://git@github.com/hairyhenderson/go-which.git

Authentication

The authentication mechanisms used by gitfs are dependent on the URL scheme. A number of Authenticators are provided in this package. See the documentation for the Authenticator type for more information.

Environment Variables

The Authenticators in this package optionally support the use of environment variables to provide credentials. These are:

- GIT_HTTP_PASSWORD: the password to use for HTTP Basic Authentication

- GIT_HTTP_PASSWORD_FILE: the path to a file containing the password to use for HTTP Basic Authentication

- GIT_HTTP_TOKEN: the token to use for HTTP token authentication

- GIT_HTTP_TOKEN_FILE: the path to a file containing the token to use for HTTP token authentication

- GIT_SSH_KEY: the (optionally Base64-encoded) PEM-encoded private key to use for SSH public key authentication

- GIT_SSH_KEY_FILE: the path to a file containing the PEM-encoded private key to use for SSH public key authentication

Example

Using gitfs.New to create a filesystem based on a git repository on the local filesystem.

u, _ := url.Parse("file:///data/repo")
fsys, _ := New(u)

files, _ := fs.ReadDir(fsys, ".")
for _, name := range files {
	fmt.Printf("file: %s\n", name.Name())
}

Example (ExplicitAuth)

Using WithAuthenticator to configure authentication using the ssh-agent support.

u, _ := url.Parse("git+ssh://github.com/git-fixtures/basic//json#branch")

// create the FS and set SSH Agent authentication explicitly, setting the
// username to 'git', as GitHub requires.
fsys, _ := New(u)
fsys = WithAuthenticator(SSHAgentAuthenticator("git"), fsys)

files, _ := fs.ReadDir(fsys, ".")
for _, name := range files {
	fmt.Printf("file: %s\n", name.Name())
}

Index

• Variables
• func New(u *url.URL) (fs.FS, error)
• func WithAuthenticator(auth Authenticator, fsys fs.FS) fs.FS
• type AuthMethod
• type Authenticator
  • func AutoAuthenticator() Authenticator
  • func BasicAuthenticator(username, password string) Authenticator
  • func NoopAuthenticator() Authenticator
  • func PublicKeyAuthenticator(username string, privKey []byte, keyPass string) Authenticator
  • func SSHAgentAuthenticator(username string) Authenticator
  • func TokenAuthenticator(token string) Authenticator

Examples

• Package
• Package (ExplicitAuth)
• AutoAuthenticator
• BasicAuthenticator
• BasicAuthenticator (Unauthenticated)

Variables

var FS = fsimpl.FSProviderFunc(New, "git", "git+file", "git+http", "git+https", "git+ssh")

FS is used to register this filesystem with an fsimpl.FSMux

Functions

func New

func New(u *url.URL) (fs.FS, error)

New provides a filesystem (an fs.FS) for the git repository indicated by the given URL. Valid schemes are "git", "file", "http", "https", "ssh", and the same prefixed with "git+" (e.g. "git+ssh://...")

A context can be given by using WithContextFS.

func WithAuthenticator

func WithAuthenticator(auth Authenticator, fsys fs.FS) fs.FS

WithAuthenticator configures the given FS to authenticate with auth, if the filesystem supports it.

Types

type AuthMethod

type AuthMethod interface {
	fmt.Stringer
	Name() string
}

AuthMethod is an HTTP or SSH authentication method that can be used to authenticate to a git repository. See the github.com/go-git/go-git module for details.

type Authenticator

type Authenticator interface {
	Authenticate(u *url.URL) (AuthMethod, error)
}

Authenticator provides an AuthMethod for a given URL. If the URL is not appropriate for the given AuthMethod, an error will be returned.

func AutoAuthenticator

func AutoAuthenticator() Authenticator

AutoAuthenticator is an Authenticator that chooses the first available authenticator based on the given URL (when appropriate) and the environment variables, in this order of precedence:

BasicAuthenticator
TokenAuthenticator
PublicKeyAuthenticator
SSHAgentAuthenticator
NoopAuthenticator

Example

u, _ := url.Parse("https://github.com/git-fixtures/basic//json/")

fsys, _ := New(u)

// AutoAuthenticator is the default, so this is redundant, but left here for
// documentation purposes.
fsys = WithAuthenticator(AutoAuthenticator(), fsys)

// this will use authenticated access if set in the environment, or default
// to unauthenticated access.
fi, _ := fs.Stat(fsys, "short.json")
fmt.Printf("file size: %d\n", fi.Size())

func BasicAuthenticator

func BasicAuthenticator(username, password string) Authenticator

BasicAuthenticator is an Authenticator that provides HTTP Basic Authentication. Use only with HTTP/HTTPS repositories.

A username or password provided in the URL will override the credentials provided here. If password is omitted, the environment variable GIT_HTTP_PASSWORD will be used. If GIT_HTTP_PASSWORD_FILE is set, the password will be read from the referenced file on the local filesystem.

For authenticating with GitHub, Bitbucket, GitLab, and other popular git hosts, use this with a personal access token, with username 'git'.

Example

Using Basic Auth:

u, _ := url.Parse("https://mysite.com/myrepo.git")

fsys, _ := New(u)
fsys = WithAuthenticator(BasicAuthenticator("me", "mypassword"), fsys)

// this will use authenticated access
fi, _ := fs.Stat(fsys, "short.json")
fmt.Printf("file size: %d\n", fi.Size())

// or we can set user/password in the URL:
u, _ = url.Parse("https://me:mypassword@mysite.com/myrepo.git")

fsys, _ = New(u)
// no need to provide user/pass to the authenticator, but if we did, the URL
// values would override.
fsys = WithAuthenticator(BasicAuthenticator("", ""), fsys)

fi, _ = fs.Stat(fsys, "short.json")
fmt.Printf("file size: %d\n", fi.Size())

Example (Unauthenticated)

Using Basic Auth with a public (unauthenticated) repo:

u, _ := url.Parse("https://github.com/git-fixtures/basic//json/")

fsys, _ := New(u)

// Use BasicAuthenticator with no user/pass to get unauthenticated access.
// See also NoopAuthenticator to prevent authentication from URL.
fsys = WithAuthenticator(BasicAuthenticator("", ""), fsys)

fi, _ := fs.Stat(fsys, "short.json")
fmt.Printf("file size: %d\n", fi.Size())

func NoopAuthenticator

func NoopAuthenticator() Authenticator

NoopAuthenticator is an Authenticator that will not attempt any authentication methods. Can only be used with 'git', 'file', 'http', and 'https' schemes.

Useful when desiring no authentication at all (e.g. for local repositories, or to ensure that target repositories are public).

func PublicKeyAuthenticator

func PublicKeyAuthenticator(username string, privKey []byte, keyPass string) Authenticator

PublicKeyAuthenticator provides an an Authenticator that uses SSH public key authentication. Use only with SSH repositories.

The privkey is a PEM-encoded private key. Set keyPass if privKey is a password-encrypted PEM block, otherwise leave it empty.

If privKey is omitted, the GIT_SSH_KEY environment variable will be used. For ease of use, the variable may optionally be base64-encoded. If GIT_SSH_KEY_FILE is set, the key will be read from the referenced file on the local filesystem.

Supports PKCS#1 (RSA), PKCS#8 (RSA, ECDSA, ed25519), SEC 1 (ECDSA), DSA (OpenSSL), and OpenSSH private keys.

func SSHAgentAuthenticator

func SSHAgentAuthenticator(username string) Authenticator

SSHAgentAuthenticator is an Authenticator that uses the ssh-agent protocol. Use only with SSH repositories.

If username is not provided or present in the URL, the user will be the same as the current user.

This method depends on the SSH_AUTH_SOCK environment variable being correctly configured by the SSH agent. See ssh-agent(1) for details.

func TokenAuthenticator

func TokenAuthenticator(token string) Authenticator

TokenAuthenticator is an Authenticator that uses HTTP token authentication (also known as bearer authentication).

If token is omitted, the environment variable GIT_HTTP_TOKEN will be used. If GIT_HTTP_TOKEN_FILE is set, the token will be read from the referenced file on the local filesystem.

Note: If you are looking to use OAuth tokens with popular servers (e.g. GitHub, Bitbucket, GitLab), use BasicAuthenticator instead. These servers use HTTP Basic Authentication, with the OAuth token as user or password.