vcslocator

A library to work with SPDX VCS locator that parses and downloads data references by locator URIs.

Intro

This library lets go programs work with SPDX VCS locators. These are specially crafted URI that point to content hosted in Version Control Systems.

For reference see table 19 in the SPDX standard documentation.

Features:

At the moment the focus of this module is parsing the locator strings and downloading data from repositories as referenced by the URIs.

Parsing

The library includes a parser that returns the components of the VCS locator:

// Create a new locator:
l = vcslocator.Locator("git+https://github.com/example/test@v1#filename.txt")

// Parse the locator:
components, err = l.Parse()
if err != nil {
    fmt.Fprintf(os.Stderr, "Error copying file data: %s\n", err.Error())
    os.Exit(1)
}

fmt.Printf("%+v\n",  components)

/*
{
    Tool      "git"
	Transport "https"
	Hostname  "github.com"
	RepoPath  "/example/test"
	RefString "v1"
	Commit    "
	Tag       "v1"
	Branch    ""
	SubPath   "filename.txt"
}
*/

Support for Short GitHub Repository "Slugs"

While not part of the specification, short repository slugs in the form of owner/repository are supported as VCS locators. For now we default the hostname of the vcs locator to github.com and the locator schema to git+https.

For example this short slug:

myorg/myrepo

Is equivalente to this VCS locator:

git+https://github.com/myorg/myrepo

Refrence strings and subpaths are fully supported in short slugs too.

Download and Copy

The library also supports copying and downloading the data referenced by the VCS locator:

// This VCS locator points to the readme file of Kubernetes at the latest commit:
var filelocator = "git+https://https://github.com/kubernetes/kubernetes#README.md"

// Copy the README data to STDOUT:
if err := vcslocator.CopyFile(filelocator, Stdout); err != nil {
    fmt.Fprintf(os.Stderr, "Error copying file data: %s\n", err.Error())
    os.Exit(1)
}

// This VCS locator points to the go/predicates directory in the in-toto/attestation
// repository in GitHub at commit 159ab7123302f32caeae1b8ac99a2e465ae733f8:
var dirlocator = "git+https://github.com/in-toto/attestation@159ab7123302f32caeae1b8ac99a2e465ae733f8#go/predicates"

// Mirror the contents of the directory to mydir:
if err := vcslocator.Download(dirlocator, "mydir/"); err != nil {
    fmt.Fprintf(os.Stderr, "Error downloading data: %s\n", err.Error())
    os.Exit(1)
}

Install

To install simply go get the module into your project:

go get github.com/carabiner-dev/vcslocator

Copyright

This module is released under the Apache 2.0 license and copyright by Carabiner Systems, Inc. Feel free to open issues, send pull requests to improve the module os simply let us know how you are using it. We love feedback!