gitwatch

README

gitwatch

Periodically polls a set of targets for changes, if there are any an event is emitted on a channel.

Usage

session, err := gitwatch.New(
    ctx,
    []Repository{
        {URL: "https://github.com/repo/a"},
        {URL: "https://github.com/repo/b"},
    },
    time.Second,
    "./gitwatch-cache/",
    true,
)

go func() {
    for {
        select {
        case event := <-session.Events:
            fmt.Println("git event:", event)
        case err := <-session.Errors:
            fmt.Println("git error:", err)
        }
    }
}()

// blocks until failure
err = session.Run()
if err != nil {
    // process was terminated somehow, handle error
}

By design, once the watcher is up and running (post initial clone phase), errors will not cause it to stop. Instead, errors are passed down the Errors channel for the dependent package to handle. The error returned by Run will either be context.Cancelled or any git errors raised during the initial cloning of all targets.

There also exists a channel called InitialDone which is only ever pushed to once, immediately after all initial targets have been cloned. It's a buffered channel of size 1 so there's no explicit need to ever read from it but it can be useful for sequencing things properly.

You can set the branch and directory name of target repositories. See the docstring for Repository for details.

Documentation

Overview

Package gitwatch provides a simple tool to first clone a set of git repositories to a local directory and then periodically check them all for any updates.

Index

• func GetRepoDirectory(repo string) (string, error)
• type Event
  • func GetEventFromRepo(repo *git.Repository) (event *Event, err error)
  • func (e Event) Commit() object.Commit
• type Repository
• type Session
  • func New(ctx context.Context, repos []Repository, interval time.Duration, dir string, ...) (session *Session, err error)
  • func (s *Session) Add(r Repository) (err error)
  • func (s *Session) Close()
  • func (s *Session) GetEventFromRepoChanges(repo *git.Repository, branch string, auth transport.AuthMethod) (event *Event, err error)
  • func (s *Session) IsRunning() bool
  • func (s *Session) Run() (err error)

Functions

func GetRepoDirectory

func GetRepoDirectory(repo string) (string, error)

GetRepoDirectory the directory name for a repository.

Types

type Event

type Event struct {
	URL       string
	Path      string
	Timestamp time.Time
	// contains filtered or unexported fields
}

Event represents an update detected on one of the watched repositories

func GetEventFromRepo

func GetEventFromRepo(repo *git.Repository) (event *Event, err error)

GetEventFromRepo reads a locally cloned git repository and returns an event based on the most recent commit.

func (Event) Commit

func (e Event) Commit() object.Commit

Commit returns the (immutable) commit associated with an event

type Repository

type Repository struct {
	URL       string               // local or remote repository URL to watch
	Branch    string               // the name of the branch to use `master` being default
	Directory string               // the directory name to clone the repository to, relative from the session's directory
	Auth      transport.AuthMethod // authentication method for git operations
	// contains filtered or unexported fields
}

Repository represents a Git repository address and branch name

type Session

type Session struct {
	Repositories  []Repository         // list of local or remote repository URLs to watch
	Interval      time.Duration        // the interval between remote checks
	Directory     string               // the directory to store repositories
	Auth          transport.AuthMethod // authentication method for git operations
	InitialEvent  bool                 // if true, an event for each repo will be emitted upon construction
	AllowDeletion bool                 // if true, repository will be deleted upon error and re-cloned
	UseForce      bool                 // if true, use force-pull when pulling changes, wiping any local changes
	InitialDone   chan struct{}        // if InitialEvent true, this is pushed to after initial setup done
	Events        chan Event           // when a change is detected, events are pushed here
	Errors        chan error           // when an error occurs, errors come here instead of halting the loop
	// contains filtered or unexported fields
}

Session represents a git watch session configuration

func New

func New(
	ctx context.Context,
	repos []Repository,
	interval time.Duration,
	dir string,
	auth transport.AuthMethod,
	initialEvent bool,
) (session *Session, err error)

New constructs a new git watch session on the given repositories The `auth` parameter is the default authentication method. Elements of the `repos` list may specify their own authentication methods, which override this value when set.

func (*Session) Add

func (s *Session) Add(r Repository) (err error)

Add will add a new repository to the list. Works even after the watcher daemon has already been started.

func (*Session) Close

func (s *Session) Close()

Close gracefully shuts down the git watcher

func (*Session) GetEventFromRepoChanges

func (s *Session) GetEventFromRepoChanges(repo *git.Repository, branch string, auth transport.AuthMethod) (event *Event, err error)

GetEventFromRepoChanges reads a locally cloned git repository an returns an event only if an attempted fetch resulted in new changes in the working tree.

func (*Session) IsRunning

func (s *Session) IsRunning() bool

IsRunning returns true if `Run` has been called

func (*Session) Run

func (s *Session) Run() (err error)

Run begins the watcher and blocks until an error occurs