gpoll

README

GPoll

Go library for polling a Git repository.

Installation

go get github.com/eddieowens/gpoll

Usage

package main

import (
    "fmt"
    "github.com/eddieowens/gpoll"
    "log"
)

func main() {
    poller, err := gpoll.NewPoller(gpoll.PollConfig{
        Git: gpoll.GitConfig{
            Auth: gpoll.GitAuthConfig{
                // Uses the SSH key from my local directory.
                SshKey: "~/.ssh/id_rsa",
            },
            // The target remote.
            Remote: "git@github.com:eddieowens/gpoll.git",
        },
        OnUpdate: func(change gpoll.GitChange) {
            switch change.EventType {
            case gpoll.EventTypeDelete:
                fmt.Printf("%s was deleted", change.Filename)
            case gpoll.EventTypeUpdate:
                fmt.Printf("%s was updated", change.Filename)
            case gpoll.EventTypeCreate:
                fmt.Printf("%s was created", change.Filename)
            }
        },
    })
    
    if err != nil {
        panic(err)
    }
    
    // Will poll the repo until poller.Stop() is called.
    log.Fatal(poller.Start())
}

Documentation

Overview

A library for polling a Git repository for changes.

Index

• type Author
• type ChangeType
• type Commit
• type CommitDiff
• type FileChange
• type FileChangeFilterFunc
• type GitAuthConfig
• type GitConfig
• type GitService
• type HandleCommitFunc
• type PollConfig
• type Poller
  • func NewPoller(config PollConfig) (Poller, error)

Types

type Author

type Author struct {
	Name string

	Email string
}

type ChangeType

type ChangeType int

const (
	// A pre-existing file was edited in the commit.
	ChangeTypeUpdate ChangeType = iota

	// A new file was created in the commit.
	ChangeTypeCreate

	// A pre-existing file was deleted in the commit.
	ChangeTypeDelete

	// The file is present from the initial clone of the repo. Only ever used once for the clone of the repo.
	ChangeTypeInit
)

type Commit

type Commit struct {
	// The Sha of the commit.
	Sha string

	// When the commit occurred in UTC.
	When time.Time

	// The author of the commit.
	Author Author

	// The message made by the author.
	Message string
}

type CommitDiff

type CommitDiff struct {
	// The list of changes that occurred in the commit.
	Changes []FileChange

	// The base for the file changes.
	From Commit

	// The result of the file changes.
	To Commit
}

Represents a batch of changes to files between two commits in a Git repo.

type FileChange

type FileChange struct {
	// The name and absolute path to the changed file.
	Filepath string

	// The type of change that occurred e.g. added, created, deleted the file.
	ChangeType ChangeType
}

Represents a change to a file within the target Git repo.

type FileChangeFilterFunc

type FileChangeFilterFunc func(change FileChange) bool

type GitAuthConfig

type GitAuthConfig struct {
	// The filepath to the SSH key. Required if the Username and Password are not set.
	SshKey string `validation:"required_without=Username Password"`

	// The username for the git repo. Required if the SshKey is not set or if the Password is set.
	Username string `validation:"required_without=SshKey,required_with=Password"`

	// The password for the git repo. Required if the SshKey is not set or if the Username is set.
	Password string `validation:"require_without=SshKey,required_with=Username"`
}

type GitConfig

type GitConfig struct {
	// Authentication/authorization for the git repo to poll. Required.
	Auth GitAuthConfig `validate:"required"`

	// The remote git repository that should be polled. Required.
	Remote string `validate:"required"`

	// The branch of the git repo to poll. Defaults to master.
	Branch string

	// The directory that the git repository will be cloned into. Defaults to the current directory.
	CloneDirectory string
}

type GitService

type GitService interface {
	Clone(remote, branch, directory string) (*git.Repository, error)
	DiffRemote(repo *git.Repository, branch string) ([]CommitDiff, error)
	FetchLatestRemoteCommit(repo *git.Repository, branch string) (*object.Commit, error)
	HeadCommit(repo *git.Repository) (*object.Commit, error)
	Diff(from *object.Commit, to *object.Commit) (*CommitDiff, error)
	ToInternal(c *object.Commit) *Commit
}

type HandleCommitFunc

type HandleCommitFunc func(commit CommitDiff)

type PollConfig

type PollConfig struct {
	Git GitConfig `validate:"required"`

	// Function for filtering out FileChanges made to a Git commit. If the function returns true, the FileChange will be
	// included in the commit passed into the HandleCommit calls. If false is returned, the file will always be ignored.
	FileChangeFilter FileChangeFilterFunc

	// Function that is called when a commit is made to the Git repo. This function maintains chronological order of
	// commits and is called synchronously.
	HandleCommit HandleCommitFunc

	// The polling interval. Defaults to 30 seconds.
	Interval time.Duration
}

type Poller

type Poller interface {
	// Start polling your git repo without blocking. The poller will diff the remote against the local clone directory at
	// the specified interval and return all changes through the configured callback and the returned channel.
	StartAsync() (chan CommitDiff, error)

	// Start polling your git repo blocking whatever thread it is run on. The poller will diff the remote against the
	// local clone directory at the specified interval and return all changes through the configured callback.
	Start() error

	// Stop all polling.
	Stop()

	// Diff the remote and the local and return all differences.
	Poll() ([]CommitDiff, error)
}

func NewPoller

func NewPoller(config PollConfig) (Poller, error)

Create a new Poller from config. Will return an error for misconfiguration.