repository

package
v0.3.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2025 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package repository periodically mirrors (bare clones) remote repository locally. It supports multiple checked out worktrees on different references. The mirror is created with `--mirror=fetch` hence everything in `refs/*` on the remote will be directly mirrored into `refs/*` in the local repository.

The implementation borrows heavily from kubernetes/git-sync. If you want to sync single repository on one reference then you are probably better off with kubernetes/git-sync, as it provides a lot more customisation. `git-mirror` should be used if multiple mirrored repositories with multiple checked out branches (worktrees) is required.

Logging:

package takes slog reference for logging and prints logs up to 'trace' level

Example: 

loggerLevel  = new(slog.LevelVar)
levelStrings = map[string]slog.Level{
	"trace": slog.Level(-8),
	"debug": slog.LevelDebug,
	"info":  slog.LevelInfo,
	"warn":  slog.LevelWarn,
	"error": slog.LevelError,
}

logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
	Level: loggerLevel,
}))
loggerLevel.Set(levelStrings["trace"])

repos, err := repository.New(repoConf, nil, logger)
if err != nil {
	panic(err)
}

Index

Constants

View Source 
const (
	GCAuto       = "auto"
	GCAlways     = "always"
	GCAggressive = "aggressive"
	GCOff        = "off"
)
View Source 
const (
	MinAllowedInterval = time.Second
)

Variables

View Source 
var (
	ErrRepoMirrorFailed   = errors.New("repository mirror failed")
	ErrRepoWTUpdateFailed = errors.New("repository worktree update failed")
)

Functions

func DefaultRepoDir 

func DefaultRepoDir(root string) string

DefaultRepoDir returns path of dir where all repositories mirrors are cloned

func EnableMetrics 

func EnableMetrics(metricsNamespace string, registerer prometheus.Registerer)

EnableMetrics will enable metrics collection for git mirrors. Available metrics are...

  • git_last_mirror_timestamp - (tags: repo) A Gauge that captures the Timestamp of the last successful git sync per repo.
  • git_mirror_count - (tags: repo,success) A Counter for each repo sync, incremented with each sync attempt and tagged with the result (success=true|false)
  • git_mirror_latency_seconds - (tags: repo) A Summary that keeps track of the git sync latency per repo.

func IsCommitHash 

func IsCommitHash(hash string) bool

IsCommitHash returns whether or not a string is a abbreviated Hash or 40 char SHA-1 or 64 char SHA-256 hash

func IsFullCommitHash 

func IsFullCommitHash(hash string) bool

IsCommitHash returns whether or not a string is a 40 char SHA-1 or 64 char SHA-256 hash

Types

type Auth 

type Auth struct {
	// username to use for basic or token based authentication
	Username string `yaml:"username"`

	// password or personal access token to use for authentication
	Password string `yaml:"password"`

	// SSH Details
	// path to the ssh key used to fetch remote
	SSHKeyPath string `yaml:"ssh_key_path"`

	// path to the known hosts of the remote host
	SSHKnownHostsPath string `yaml:"ssh_known_hosts_path"`

	// Github APP Details
	// The application id or the client ID of the Github app
	GithubAppID string `yaml:"github_app_id"`
	// The installation id of the app (in the organization).
	GithubAppInstallationID string `yaml:"github_app_installation_id"`
	// path to the github app private key
	GithubAppPrivateKeyPath string `yaml:"github_app_private_key_path"`
}

Auth represents authentication config of the repository

type CommitInfo 

type CommitInfo struct {
	Hash         string
	ChangedFiles []string
}

func ParseCommitWithChangedFilesList 

func ParseCommitWithChangedFilesList(output string) []CommitInfo

ParseCommitWithChangedFilesList will parse following output of 'show/log' command with `--name-only`, `--pretty=format:%H` flags 

72ea9c9de6963e97ac472d9ea996e384c6923cca

80e11d114dd3aa135c18573402a8e688599c69e0
one/readme.yaml
one/hello.tf
two/readme.yaml

type Config 

type Config struct {
	// git URL of the remote repo to mirror
	Remote string `yaml:"remote"`

	// Root is the absolute path to the root dir where repo dir
	// will be created. Worktree links will be created here if
	// absolute path is not provided
	Root string `yaml:"root"`

	// LinkRoot is the absolute path to the dir which is the root for the worktree links
	// if link is a relative path it will be relative to this dir
	// if link is not specified it will be constructed from repo name and worktree ref
	// and it will be placed in this dir
	// if not specified it will be same as root
	LinkRoot string `yaml:"link_root"`

	// Interval is time duration for how long to wait between mirrors
	Interval time.Duration `yaml:"interval"`

	// MirrorTimeout represents the total time allowed for the complete mirror loop
	MirrorTimeout time.Duration `yaml:"mirror_timeout"`

	// GitGC garbage collection string. valid values are
	// 'auto', 'always', 'aggressive' or 'off'
	GitGC string `yaml:"git_gc"`

	// Auth config to fetch remote repos
	Auth Auth `yaml:"auth"`

	// Worktrees contains list of worktrees links which will be maintained.
	// worktrees are optional repo can be mirrored without worktree
	Worktrees []WorktreeConfig `yaml:"worktrees"`
}

Config represents the config for the mirrored repository of the given remote.

func (*Config) PopulateEmptyLinkPaths 

func (repo *Config) PopulateEmptyLinkPaths() error

PopulateEmptyLinkPaths will try and generate missing link paths

type Repository 

type Repository struct {
	// contains filtered or unexported fields
}

Repository represents the mirrored repository of the given remote. The implementation borrows heavily from https://github.com/kubernetes/git-sync. A Repository is safe for concurrent use by multiple goroutines.

func New 

func New(repoConf Config, gitExec string, envs []string, log *slog.Logger) (*Repository, error)

New creates new repository from the given config. Remote repo will not be mirrored until either Mirror() or StartLoop() is called. 

func (r *Repository) AbsoluteLink(link string) string

AbsoluteLink returns absolute link path based on repo's root 

func (r *Repository) AddWorktreeLink(wtc WorktreeConfig) error

AddWorktreeLink adds workTree link to the mirror repository.

func (*Repository) BranchCommits 

func (r *Repository) BranchCommits(ctx context.Context, branch string) ([]CommitInfo, error)

BranchCommits lists commits from the tip of the branch but not from the HEAD of the repository in chronological order. (latest to oldest)

func (*Repository) ChangedFiles 

func (r *Repository) ChangedFiles(ctx context.Context, hash string) ([]string, error)

ChangedFiles returns path of the changed files for given commit hash

func (*Repository) Clone 

func (r *Repository) Clone(ctx context.Context, dst, ref string, pathspecs []string, rmGitDir bool) (string, error)

Clone creates a single-branch local clone of the mirrored repository to a new location on disk. On success, it returns the hash of the new repository clone's HEAD. if pathspec is provided only those paths will be checked out. if ref is commit hash then pathspec will be ignored. if rmGitDir is true `.git` folder will be deleted after the clone. if dst not empty all its contents will be removed.

func (*Repository) Directory 

func (r *Repository) Directory() string

Dir returns absolute path to the repo directory

func (*Repository) Hash 

func (r *Repository) Hash(ctx context.Context, ref, path string) (string, error)

Hash returns the hash of the given revision and for the path if specified.

func (*Repository) IsRunning 

func (r *Repository) IsRunning() bool

IsRunning returns if repositories mirror loop is running or not

func (*Repository) ListCommitsWithChangedFiles 

func (r *Repository) ListCommitsWithChangedFiles(ctx context.Context, ref1, ref2 string) ([]CommitInfo, error)

ListCommitsWithChangedFiles returns path of the changed files for given commit hash list all the commits and files which are reachable from 'ref2', but not from 'ref1' The output is given in reverse chronological order.

func (*Repository) MergeCommits 

func (r *Repository) MergeCommits(ctx context.Context, mergeCommitHash string) ([]CommitInfo, error)

MergeCommits lists commits from the mergeCommitHash but not from the first parent of mergeCommitHash (mergeCommitHash^) in chronological order. (latest to oldest)

func (*Repository) Mirror 

func (r *Repository) Mirror(ctx context.Context) error

Mirror will run mirror loop of the repository

  1. init and validate if existing repo dir
  2. fetch remote
  3. ensure worktrees
  4. cleanup if needed

func (*Repository) ObjectExists 

func (r *Repository) ObjectExists(ctx context.Context, obj string) error

ObjectExists returns error is given object is not valid or if it doesn't exists

func (*Repository) QueueMirrorRun 

func (r *Repository) QueueMirrorRun()

QueueMirrorRun will queue a mirror run on repository. If a mirror is already in progress, another mirror will be triggered as soon as the current one completes. If a run is already queued then new request will be ignored

func (*Repository) Remote 

func (r *Repository) Remote() string

Remote returns repository's remote url 

func (r *Repository) RemoveWorktreeLink(link string) error

RemoveWorktreeLink removes workTree link from the mirror repository. it will remove published link as well even (if it failed to remove worktree)

func (*Repository) StartLoop 

func (r *Repository) StartLoop(ctx context.Context)

StartLoop mirrors repository periodically based on repo's mirror interval

func (*Repository) StopLoop 

func (r *Repository) StopLoop()

StopLoop stops sync loop gracefully

func (*Repository) Subject 

func (r *Repository) Subject(ctx context.Context, hash string) (string, error)

Subject returns commit subject of given commit hash 

func (r *Repository) WorktreeLinks() map[string]*WorkTreeLink

WorktreeLinks returns current clone of worktree maps 

type WorkTreeLink struct {
	// contains filtered or unexported fields
}
func (wt *WorkTreeLink) AbsoluteLink() string

AbsoluteLink returns worktree's absolute link path

func (*WorkTreeLink) Equals 

func (wt *WorkTreeLink) Equals(wtc WorktreeConfig) bool

Equals returns if given worktree and its config is equal they are considered equal only if link, ref and pathspecs are matching. order of pothspecs is ignored

type WorktreeConfig 

type WorktreeConfig struct {
	// Link is the path at which to create a symlink to the worktree dir
	// if path is not absolute it will be created under repository link_root
	// if link is not specified it will be constructed from repo name and worktree ref
	// and it will be placed in link_root dir
	Link string `yaml:"link"`

	// Ref represents the git reference of the worktree branch, tags or hash
	// are supported. default is HEAD
	Ref string `yaml:"ref"`

	// Pathspecs of the dirs to checkout if required
	Pathspecs []string `yaml:"pathspecs"`
}

Worktree represents maintained worktree on given link.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.