gitsync

Documentation

Overview

Package gitsync wraps the system git executable with the small set of operations dot needs to reconcile a package directory with its remote: rebasing pulls, working-tree inspection, and commit and push of local edits.

Index

• Constants
• func CommitMessage(hostname string, groups []PackageGroup) string
• func ShortHostname(hostname string) string
• type Commit
• type ErrCommand
  • func (e ErrCommand) Error() string
  • func (e ErrCommand) Unwrap() error
• type ErrGitNotFound
  • func (e ErrGitNotFound) Error() string
  • func (e ErrGitNotFound) Unwrap() error
• type ErrNotRepository
  • func (e ErrNotRepository) Error() string
• type ErrRebaseConflict
  • func (e ErrRebaseConflict) Error() string
  • func (e ErrRebaseConflict) Unwrap() error
• type ExecRunner
  • func NewExecRunner() (*ExecRunner, error)
  • func (r *ExecRunner) Run(ctx context.Context, dir string, args ...string) (Output, error)
• type Output
  • func (o Output) Combined() string
• type PackageGroup
  • func GroupByPackage(entries []StatusEntry) []PackageGroup
  • func (g PackageGroup) Label() string
• type PullResult
  • func (r PullResult) UpToDate() bool
• type Repo
  • func NewRepo(dir string, runner Runner) *Repo
  • func Open(dir string) (*Repo, error)
  • func (r *Repo) CommitAll(ctx context.Context, message string) error
  • func (r *Repo) Dir() string
  • func (r *Repo) EnsureRepository(ctx context.Context) error
  • func (r *Repo) Head(ctx context.Context) (string, error)
  • func (r *Repo) Pull(ctx context.Context) (PullResult, error)
  • func (r *Repo) Push(ctx context.Context) error
  • func (r *Repo) Status(ctx context.Context) ([]StatusEntry, error)
• type Runner
• type StatusEntry
  • func ParsePorcelain(out string) []StatusEntry
  • func (e StatusEntry) Code() string

Constants

const RootCommitToken = "repo root"

RootCommitToken names repository-root files inside a commit subject, where the parenthesised RootLabel would read as doubled brackets.

const RootLabel = "(repository root)"

RootLabel is the display name used for changed files that live directly in the repository root rather than inside a package directory.

Functions

func CommitMessage

func CommitMessage(hostname string, groups []PackageGroup) string

CommitMessage builds the commit message used by `dot sync --push`.

func ShortHostname

func ShortHostname(hostname string) string

ShortHostname reduces a hostname to its first label, dropping any domain suffix. It returns unknownHost when no usable label is present.

Types

type Commit

type Commit struct {
	Hash    string
	Subject string
}

Commit is a single commit summary produced by a pull.

type ErrCommand

type ErrCommand struct {
	Args     []string
	ExitCode int
	Stderr   string
	Err      error
}

ErrCommand reports a git invocation that exited non-zero or failed to start.

func (ErrCommand) Error

func (e ErrCommand) Error() string

func (ErrCommand) Unwrap

func (e ErrCommand) Unwrap() error

type ErrGitNotFound

type ErrGitNotFound struct {
	Err error
}

ErrGitNotFound reports that the git executable is not installed or not on PATH.

func (ErrGitNotFound) Error

func (e ErrGitNotFound) Error() string

func (ErrGitNotFound) Unwrap

func (e ErrGitNotFound) Unwrap() error

type ErrNotRepository

type ErrNotRepository struct {
	Dir string
}

ErrNotRepository reports that a directory is not inside a git working tree.

func (ErrNotRepository) Error

func (e ErrNotRepository) Error() string

type ErrRebaseConflict

type ErrRebaseConflict struct {
	Dir    string
	Paths  []string
	Output string
	// Err is the failing git invocation, kept so callers can inspect it.
	Err error
}

ErrRebaseConflict reports that `git pull --rebase` stopped with conflicts. Paths lists the conflicted files relative to the repository root.

func (ErrRebaseConflict) Error

func (e ErrRebaseConflict) Error() string

func (ErrRebaseConflict) Unwrap

func (e ErrRebaseConflict) Unwrap() error

type ExecRunner

type ExecRunner struct {
	// GitPath is the resolved path to the git executable.
	GitPath string
	// Env overrides the environment passed to git. A nil Env inherits the
	// process environment.
	Env []string
}

ExecRunner runs git through os/exec.

func NewExecRunner

func NewExecRunner() (*ExecRunner, error)

NewExecRunner locates git on PATH and returns a runner for it. It returns ErrGitNotFound when git is not installed.

func (*ExecRunner) Run

func (r *ExecRunner) Run(ctx context.Context, dir string, args ...string) (Output, error)

Run executes git with the given arguments in dir and captures its output. Trailing newlines are trimmed from both streams.

type Output

type Output struct {
	Stdout   string
	Stderr   string
	ExitCode int
}

Output holds the captured result of a git invocation.

func (Output) Combined

func (o Output) Combined() string

Combined returns stdout and stderr joined, in that order, skipping empties.

type PackageGroup

type PackageGroup struct {
	Package string
	Entries []StatusEntry
}

PackageGroup collects the changed entries that belong to one top-level directory of the package repository. Package is empty for repository-root files.

func GroupByPackage

func GroupByPackage(entries []StatusEntry) []PackageGroup

GroupByPackage groups entries by their top-level directory. Groups are sorted by package name with repository-root files first; entries inside a group are sorted by path.

func (PackageGroup) Label

func (g PackageGroup) Label() string

Label returns the group name for display, substituting RootLabel for repository-root files.

type PullResult

type PullResult struct {
	OldHead string
	NewHead string
	// Commits are the commits reachable from the new head but not the old
	// one, newest first.
	Commits []Commit
}

PullResult describes the effect of a rebasing pull.

func (PullResult) UpToDate

func (r PullResult) UpToDate() bool

UpToDate reports whether the pull left the branch unchanged.

type Repo

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

Repo is a git working tree that dot manages.

func NewRepo

func NewRepo(dir string, runner Runner) *Repo

NewRepo returns a Repo for dir that uses the given runner.

func Open

func Open(dir string) (*Repo, error)

Open returns a Repo for dir backed by the system git executable.

func (*Repo) CommitAll

func (r *Repo) CommitAll(ctx context.Context, message string) error

CommitAll stages every change in the working tree and commits it. Commit hooks run normally; dot never bypasses them.

func (*Repo) Dir

func (r *Repo) Dir() string

Dir returns the working directory the repository operates on.

func (*Repo) EnsureRepository

func (r *Repo) EnsureRepository(ctx context.Context) error

EnsureRepository verifies that the directory is inside a git working tree. It reports ErrNotRepository only when git says so, or when the directory does not exist; any other git failure (a broken installation, a permissions problem, a rejected repository) is returned unchanged.

func (*Repo) Head

func (r *Repo) Head(ctx context.Context) (string, error)

Head returns the current commit hash. A repository whose HEAD is unborn, meaning it has no commits yet, reports an empty hash and no error.

func (*Repo) Pull

func (r *Repo) Pull(ctx context.Context) (PullResult, error)

Pull runs `git pull --rebase --autostash` and reports the commits gained. It returns ErrRebaseConflict when the rebase stops with conflicting paths; callers are expected to stop and let the user resolve them by hand.

func (*Repo) Push

func (r *Repo) Push(ctx context.Context) error

Push publishes the current branch to its configured remote.

func (*Repo) Status

func (r *Repo) Status(ctx context.Context) ([]StatusEntry, error)

Status returns the working-tree entries reported by git status --porcelain.

type Runner

type Runner interface {
	Run(ctx context.Context, dir string, args ...string) (Output, error)
}

Runner executes a git subcommand in a working directory.

type StatusEntry

type StatusEntry struct {
	Index    byte
	Worktree byte
	Path     string
	OrigPath string
}

StatusEntry is a single line of `git status --porcelain` output. Index holds the staged status code, Worktree the unstaged status code. OrigPath is populated only for renames and copies.

func ParsePorcelain

func ParsePorcelain(out string) []StatusEntry

ParsePorcelain parses `git status --porcelain` (v1) output into entries. Lines that are too short to carry a status code and a path are skipped.

func (StatusEntry) Code

func (e StatusEntry) Code() string

Code returns the two-character porcelain status code, for example "??" or " M".