ghru

README

GHRU - Github Release Updater for Go

GHRU is a golang package that allows self-updating in your application by downloading the latest semantic (semver) directly from your github releases (release assets), replacing the running version.

By default it will skip pre-releases, either defined by "This is a pre-release" option on Github, or by the semverion git tag (eg: 1.2.3-beta1), however this can be disabled by defining ghru.AllowPrereleases = true in your software.

The binaries must be attached to your Github releases (assets), compressed with bzip2 (bz2), and named accordingly: <name>_<semver>_<os>_<arch>.bz2, eg:

myapp_1.2.3_linux_amd64.bz2
myapp_1.2.3_linux_386.bz2
myapp_1.2.3_darwin_386.bz2
myapp_1.2.3_darwin_amd64.bz2
myapp_1.2.3_windows_amd64.exe.bz2
myapp_1.2.3_windows_386.exe.bz2

Install

go get -u github.com/axllent/ghru

Example usage

The update command is ghru.Update("myuser/myapp", "myapp", appVersion), where:

• myuser/myapp (string) is the github name (handle) and the repository
• myapp (string) is the name of your binary (without semversion, os, architecture or extension)
• appVersion (string) is the current version of the running application

How you define your current running version is entirely up to you, but you must provide it otherwise GHRU will always indicate that there is an update.

package main

import (
	"flag"
	"fmt"
	"os"

	"github.com/axllent/ghru"
)

var appVersion = "0.1.2" // current app version

func main() {

	ghru.AllowPrereleases = true // optional, default false

	update := flag.Bool("u", false, "updater to latest release")
	showVersion := flag.Bool("v", false, "show current version")

	flag.Parse()

	if *showVersion {
		fmt.Println(fmt.Sprintf("Version: %s", appVersion))
		latest, _, _, err := ghru.Latest("myuser/myapp", "myapp")
		if err == nil && ghru.GreaterThan(latest, appVersion) {
			fmt.Printf("Update available: %s\nRun `%s -u` to update.\n", latest, os.Args[0])
		}
		os.Exit(0)
	}

	if *update {
		rel, err := ghru.Update("myuser/myapp", "myapp", appVersion)
		if err != nil {
			panic(err)
		}
		fmt.Printf("Updated %s to version %s\n", os.Args[0], rel)
		os.Exit(0)
	}

	// ... rest of app
}

Documentation

Index

• Variables
• func DownloadToFile(url, filepath string) error
• func GreaterThan(toVer, fromVer string) bool
• func Latest(repo, name string) (string, string, string, error)
• func ReplaceFile(dst, src string) error
• func Update(repo, appName, currentVersion string) (string, error)
• type Release
• type Releases

Variables

var AllowPrereleases = false

AllowPrereleases defines whether pre-releases may be included

Functions

func DownloadToFile

func DownloadToFile(url, filepath string) error

DownloadToFile downloads a URL to a file

func GreaterThan

func GreaterThan(toVer, fromVer string) bool

GreaterThan compares the current version to a different version returning < 1 not upgradeable

func Latest

func Latest(repo, name string) (string, string, string, error)

Latest fetches the latest release info & returns release tag, filename & download url

func ReplaceFile

func ReplaceFile(dst, src string) error

ReplaceFile replaces one file with another. Running files cannot be overwritten, so it has to be moved and the new binary saved to the original path. This requires read & write permissions to both the original file and directory. Note, on Windows it is not possible to delete a running program, so the old exe is renamed and moved to os.TempDir()

func Update

func Update(repo, appName, currentVersion string) (string, error)

Update the running binary with the latest release binary from Github

Types

type Release

type Release struct {
	Name string
	Tag  string
	URL  string
	Size int64
}

Release struct contains the file data for downloadable release

type Releases

type Releases []struct {
	Name       string `json:"name"`       // release name
	Tag        string `json:"tag_name"`   // release tag
	Prerelease bool   `json:"prerelease"` // Github pre-release
	Assets     []struct {
		BrowserDownloadURL string `json:"browser_download_url"`
		ID                 int64  `json:"id"`
		Name               string `json:"name"`
		Size               int64  `json:"size"`
	} `json:"assets"`
}

Releases struct for Github releases json