githubfs

README

githubfs

A simple to use go fs.FS based github filesystem.

Resulting Directory Structure

org_or_user/                    // org or username
└── repository                  // repository
    ├── git                     // fixed name 'git'
    │   └── main                // the branch name
    │       └── README.md       // the files in the repo
    └── releases                // fixed name 'releases'
        └── v0.0.1              // release version
            └── description.md  // the description of the release and other files from the release

Example Usage

package githubfs

import (
	"context"
	"fmt"
	"io/fs"
	"os"

	"github.com/schmidtw/githubfs"
	"golang.org/x/oauth2"
)

func main() {
	src := oauth2.StaticTokenSource(
		&oauth2.Token{AccessToken: os.Getenv("GITHUB_TOKEN")},
	)
	httpClient := oauth2.NewClient(context.Background(), src)

	gfs := githubfs.New(
		githubfs.WithHttpClient(httpClient),
		githubfs.WithRepo("schmidtw", "githubfs"),
	)

	err := fs.WalkDir(gfs, "schmidtw/githubfs/git/main/.reuse",
		func(path string, d fs.DirEntry, err error) error {
			fmt.Printf("%s\n", path)
			if err != nil || d.IsDir() {
				return err
			}

			return nil
		})
	if err != nil {
		panic(err)
	}
}

Limitations

• Symlinks are only supported for files fetched for small repos (where the fetch occurs via a tarball).
• Packages are not supported by the github graphql API, so they aren't supported here.
• Gists are not supported presently.

Documentation

Overview

Package githubfs is a handy filesystem approach to interacting with assets that github provides.

Githubfs provides an easy way to grab a few random files or release objects for many repositories at once without needing to interact with the github API directly.

The performance for depends on how you are using it.

Example

package main

import (
	"context"
	"fmt"
	"io/fs"
	"os"

	"github.com/schmidtw/githubfs"
	"golang.org/x/oauth2"
)

func main() {
	token := os.Getenv("GITHUB_TOKEN")

	// Github requires credentials to use the v4 API.  Bypass this in the
	// tests to prevent false failures, but enable folks to easily try out
	// the feature.
	if len(token) == 0 {
		fmt.Println("schmidtw/githubfs/git/main/.reuse")
		fmt.Println("schmidtw/githubfs/git/main/.reuse/dep5")
		return
	}

	src := oauth2.StaticTokenSource(
		&oauth2.Token{AccessToken: token},
	)
	httpClient := oauth2.NewClient(context.Background(), src)

	gfs := githubfs.New(
		githubfs.WithHttpClient(httpClient),
		githubfs.WithRepo("schmidtw", "githubfs"),
	)

	err := fs.WalkDir(gfs, "schmidtw/githubfs/git/main/.reuse",
		func(path string, d fs.DirEntry, err error) error {
			fmt.Printf("%s\n", path)
			if err != nil || d.IsDir() {
				return err
			}

			return nil
		})
	if err != nil {
		panic(err)
	}

}

Output:

schmidtw/githubfs/git/main/.reuse
schmidtw/githubfs/git/main/.reuse/dep5

Index

• type FS
  • func New(opts ...Option) *FS
  • func (gfs *FS) Open(name string) (fs.File, error)
• type Option
  • func WithGithubEnterprise(baseURL, version string) Option
  • func WithHttpClient(c *http.Client) Option
  • func WithOrg(org string, allowArchivedrepos ...bool) Option
  • func WithRepo(org string, repo string, branches ...string) Option
  • func WithSlug(slug string, allowArchivedrepos ...bool) Option
  • func WithSlugs(slugs ...string) Option
  • func WithThresholdInKB(max int) Option

Examples

• Package

Types

type FS

type FS struct {
	// contains filtered or unexported fields
}

FS provides the githubfs

func New

func New(opts ...Option) *FS

New creates a new githubfs.FS object with the specified configuration.

func (*FS) Open

func (gfs *FS) Open(name string) (fs.File, error)

Open opens the named file.

type Option

type Option func(gfs *FS)

Option is the type used for options.

func WithGithubEnterprise

func WithGithubEnterprise(baseURL, version string) Option

WithGithubEnterprise specifies the API version to support for backwards compatibility. The version value should be "3.3", "3.4", "3.5", "3.6", etc. The baseURL passed in should look like this:

http://github.company.com

The needed paths will be added to the baseURL.

GHEC should not use this option as it uses the public API and hosting.

func WithHttpClient

func WithHttpClient(c *http.Client) Option

WithHttpClient provides a way to set the HTTP client to use.

func WithOrg

func WithOrg(org string, allowArchivedrepos ...bool) Option

WithOrg instructs the filesystem to include all the repositories owned by an organization or user and the default branches of each repo.

Repos marked as archived are filtered unless allowArchivedrepos is set to true.

func WithRepo

func WithRepo(org string, repo string, branches ...string) Option

WithRepo configures a specific owner, repository and branches to include. If no branch is specified the default branch is selected. Multiple branches may be specified in one call.

func WithSlug

func WithSlug(slug string, allowArchivedrepos ...bool) Option

WithSlug provides a way to easily configure a set of repos, or unique repo based on the slug string.

slug = "org" (the entire organization with default branch) slug = "org/repo" (the exact repository with default branch) slug = "org/repo:branch" (the exact repository with specific branch)

Repos marked as archived are filtered unless allowArchivedrepos is set to true.

func WithSlugs

func WithSlugs(slugs ...string) Option

WithSlugs provides a way to pass in an array of slugs and it will take care of the rest. Works like WithSlug() except no option for archived repos.

func WithThresholdInKB

func WithThresholdInKB(max int) Option

WithThresholdInKB sets the maximum size to download the entire repository vs. downloading the individual files.

Defaults to downloading a repo snapshot if the repo is less than 10MB.