remote

Documentation

Overview

Package remote implements the git-annex external special remote protocol. It can be used to create an external special remote without detailed knowledge of the git-annex wire protocol. It supports the ASYNC and INFO protocol extensions.

For basic functionality, define a type implementing the RemoteV1 interface and pass an instance of it to the Run function. Optional messages in the protocol may be supported by having the type additionally implement the "Has*" interfaces.

See https://git-annex.branchable.com/design/external_special_remote_protocol/ for further information regarding the underlying protocol and the semantics of its operations.

Index

• Constants
• func Run(r RemoteV1)
• type Annex
• type ConfigSetting
• type HasCheckURL
• type HasClaimURL
• type HasExport
• type HasExtensions
• type HasGetAvailability
• type HasGetCost
• type HasGetInfo
• type HasListConfigs
• type HasRemoveExportDirectory
• type HasRenameExport
• type HasWhereIs
• type InfoField
• type RemoteV1
• type URLInfo

Constants

const (
	// ExtInfo is the keyword of the protocol extension for info messages.
	ExtInfo = "INFO"
	// ExtAsync is the keyword of the protocol extension for asynchronous jobs.
	ExtAsync = "ASYNC"
)

Functions

func Run

func Run(r RemoteV1)

Run executes an external special remote as git-annex expects, reading from stdin and writing to stdout.

Types

type Annex

type Annex interface {
	Progress(bytes int)
	DirHash(key string) string
	DirHashLower(key string) string
	SetConfig(setting, value string)
	GetConfig(setting string) string
	SetCreds(setting, user, password string)
	GetCreds(setting string) (string, string)
	GetUUID() string
	GetGitDir() string
	SetWanted(expression string)
	GetWanted() string
	SetState(setting, value string)
	GetState(setting string) string
	SetURLPresent(key, url string)
	SetURLMissing(key, url string)
	SetURIPresent(key, uri string)
	SetURIMissing(key, uri string)
	GetURLs(key, prefix string) []string
	Debug(message string)
	Debugf(fmt string, args ...interface{})
	Info(message string)
	Infof(fmt string, args ...interface{})
	Error(message string)
	Errorf(fmt string, args ...interface{})
}

Annex allows external special remote implementations to send requests to git-annex.

type ConfigSetting

type ConfigSetting struct {
	Name, Description string
}

ConfigSetting is one configuration setting that can be set for this remote. It is used for the LISTCONFIGS command.

type HasCheckURL

type HasCheckURL interface {
	CheckURL(a Annex, url string) ([]URLInfo, error)
}

HasCheckURL is the interface that a remote implementation must implement to support the CHECKURL command. If CheckURL returns a slice containing one element with an empty URL field, that translates into a CHECKURL-CONTENTS response; otherwise, CHECKURL-MULTI is used.

type HasClaimURL

type HasClaimURL interface {
	ClaimURL(a Annex, url string) bool
}

HasClaimURL is the interface that a remote implementation must implement to support the CLAIMURL command.

type HasExport

type HasExport interface {
	// Store associates the content of the given file with the given key in the remote.
	StoreExport(a Annex, name, key, file string) error
	// Retrieve places the content of the given key into the given file.
	RetrieveExport(a Annex, name, key, file string) error
	// Present checks whether the remote contains the data for the given key.
	PresentExport(a Annex, name, key string) (bool, error)
	// Remove removes the content of the given key from the remote.
	RemoveExport(a Annex, name, key string) error
}

HasExport is the interface that a remote implementation must implement to support the simple export interface.

type HasExtensions

type HasExtensions interface {
	Extensions(a Annex, e []string) []string
}

HasExtensions is the interface that a remote implementation must implement to support the EXTENSIONS command.

type HasGetAvailability

type HasGetAvailability interface {
	GetAvailability(a Annex) string
}

HasGetAvailability is the interface that a remote implementation must implement to support the GETAVAILABILITY command.

type HasGetCost

type HasGetCost interface {
	GetCost(a Annex) int
}

HasGetCost is the interface that a remote implementation must implement to support the GETCOST command.

type HasGetInfo

type HasGetInfo interface {
	GetInfo(a Annex) []InfoField
}

HasGetInfo is the interface that a remote implementation must implement to support the GETINFO command.

type HasListConfigs

type HasListConfigs interface {
	ListConfigs(a Annex) []ConfigSetting
}

HasListConfigs is the interface that a remote implementation must implement to support the LISTCONFIGS command.

type HasRemoveExportDirectory

type HasRemoveExportDirectory interface {
	RemoveExportDirectory(a Annex, directory string) error
}

HasRemoveExportDirectory is the interface that a remote implementation must implement to support the REMOVEEXPORTDIRECTORY command.

type HasRenameExport

type HasRenameExport interface {
	RenameExport(a Annex, name, key, newName string) error
}

HasRenameExport is the interface that a remote implementation must implement to support the RENAMEEXPORT command.

type HasWhereIs

type HasWhereIs interface {
	WhereIs(a Annex, url string) string
}

HasWhereIs is the interface that a remote implementation must implement to support the WHEREIS command.

type InfoField

type InfoField struct {
	Name, Value string
}

InfoField is one field to include in the output of `git annex info`. It is used for the GETINFO command.

type RemoteV1

type RemoteV1 interface {
	// Init performs one-time setup tasks required to use the remote. It is not called every time
	// git-annex interacts with the remote, but it may be called multiple times when the remote is
	// enabled in different repositories or when a configuration value is changed.
	Init(a Annex) error
	// Prepare prepares the remote to be used. It is called once each time the remote is run, before
	// any other methods that involve manipulating data in the remote.
	Prepare(a Annex) error
	// Store associates the content of the given file with the given key in the remote.
	Store(a Annex, key, file string) error
	// Retrieve places the content of the given key into the given file.
	Retrieve(a Annex, key, file string) error
	// Present checks whether the remote contains the data for the given key.
	Present(a Annex, key string) (bool, error)
	// Remove removes the content of the given key from the remote.
	Remove(a Annex, key string) error
}

RemoteV1 is the core interface that external special remote implementations must satisfy.

type URLInfo

type URLInfo struct {
	URL      string
	Size     int
	Filename string
}

URLInfo contains information about one URL for use with the CHECKURL command.