gitsync

Documentation

Overview

Package gitsync is a thin wrapper around the `git` CLI (via os/exec), used to ship the TaskFrame database between machines as a JSON file in a git repo. It has no project dependencies and only needs `git` on PATH. All I/O of the synced file itself lives in the caller; this package only runs git.

Index

• func Available() bool
• func IsAuth(err error) bool
• func IsNonFastForward(err error) bool
• type GitError
  • func (e *GitError) Error() string
  • func (e *GitError) Unwrap() error
• type Repo
  • func Clone(ctx context.Context, url, dir string) (*Repo, error)
  • func Open(dir string) *Repo
  • func (r *Repo) AddCommit(ctx context.Context, msg string) (bool, error)
  • func (r *Repo) AheadBehind(ctx context.Context, upstream string) (ahead, behind int, err error)
  • func (r *Repo) CheckoutNewBranch(ctx context.Context, name string) error
  • func (r *Repo) Config(ctx context.Context, key, val string) error
  • func (r *Repo) DefaultBranch(ctx context.Context) (string, error)
  • func (r *Repo) Dir() string
  • func (r *Repo) Fetch(ctx context.Context) error
  • func (r *Repo) File(name string) string
  • func (r *Repo) HeadHash(ctx context.Context) (string, error)
  • func (r *Repo) IsDirty(ctx context.Context) (bool, error)
  • func (r *Repo) Push(ctx context.Context, branch string, setUpstream bool) error
  • func (r *Repo) RemoteHash(ctx context.Context, branch string) (string, error)
  • func (r *Repo) ResetHard(ctx context.Context, ref string) error

Functions

func Available

func Available() bool

Available reports whether the git binary is on PATH.

func IsAuth

func IsAuth(err error) bool

IsAuth reports whether err looks like a git authentication/authorization failure (bad credentials, missing SSH key, no permission).

func IsNonFastForward

func IsNonFastForward(err error) bool

IsNonFastForward reports whether a push was rejected because the remote moved (should be unreachable in the sync flow, kept as a safety net).

Types

type GitError

type GitError struct {
	Args   []string
	Stderr string
	Err    error
}

GitError wraps a failed git invocation. Its message embeds git's own stderr, so it stays English — matching the store/task convention that domain errors are not localized. The CLI classifies it (IsAuth/IsNonFastForward) and maps it to localized guidance.

func (*GitError) Error

func (e *GitError) Error() string

func (*GitError) Unwrap

func (e *GitError) Unwrap() error

type Repo

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

Repo is a git clone working directory.

func Clone

func Clone(ctx context.Context, url, dir string) (*Repo, error)

Clone clones url into dir and returns the repo. An empty remote clones fine (it just yields an unborn branch).

func Open

func Open(dir string) *Repo

Open wraps an existing clone directory (no validation).

func (*Repo) AddCommit

func (r *Repo) AddCommit(ctx context.Context, msg string) (bool, error)

AddCommit stages everything and commits with a hermetic identity (so it works on a fresh machine or in CI with no global git config). It returns committed=false when there is nothing to commit (an identical export is a no-op, not an error).

func (*Repo) AheadBehind

func (r *Repo) AheadBehind(ctx context.Context, upstream string) (ahead, behind int, err error)

AheadBehind reports how many commits HEAD is ahead of / behind upstream (e.g. "origin/main"). Used by `sync status`.

func (*Repo) CheckoutNewBranch

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

CheckoutNewBranch creates and switches to a fresh branch (used when the remote is unborn, so the first push has a branch to publish).

func (*Repo) Config

func (r *Repo) Config(ctx context.Context, key, val string) error

Config sets a local git config value on the clone.

func (*Repo) DefaultBranch

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

DefaultBranch resolves origin's default branch, falling back to "main" when the remote is empty (no HEAD yet).

func (*Repo) Dir

func (r *Repo) Dir() string

Dir returns the clone working directory.

func (*Repo) Fetch

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

Fetch updates remote-tracking refs.

func (*Repo) File

func (r *Repo) File(name string) string

File joins name onto the clone directory.

func (*Repo) HeadHash

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

HeadHash returns the local HEAD commit, or "" if the branch is unborn.

func (*Repo) IsDirty

func (r *Repo) IsDirty(ctx context.Context) (bool, error)

IsDirty reports whether the working tree has uncommitted changes.

func (*Repo) Push

func (r *Repo) Push(ctx context.Context, branch string, setUpstream bool) error

Push pushes HEAD to origin/<branch>. setUpstream adds -u for the first push.

func (*Repo) RemoteHash

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

RemoteHash returns the commit of origin/<branch>, or "" if the remote branch does not exist yet (empty repo). Call Fetch first.

func (*Repo) ResetHard

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

ResetHard makes the working tree and index match ref exactly.