gitx

package
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Nov 4, 2026 License: BSD-3-Clause Imports: 16 Imported by: 0

Documentation

Overview

Package gitx runs the system git binary for a workspace. Chapar does not bundle a git implementation: the user's git knows their credentials, hooks and config, and gives the same results as their terminal.

Index

Constants

View Source 
const (
	AskPassEnv = "CHAPAR_GIT_ASKPASS"
)

Environment variables that pass credentials to the askpass helper. The helper is the chapar binary itself, run by git with AskPassEnv set.

Variables

View Source 
var ErrAuth = errors.New("the remote needs a user name and token")

ErrAuth means the remote refused the credentials, or git needed some and had none.

View Source 
var ErrDiverged = errors.New("this branch and the remote both have new commits")

ErrDiverged means a pull can't fast-forward: both sides have new commits.

View Source 
var ErrNoUpstream = errors.New("the remote has no branch to pull from")

ErrNoUpstream means the branch doesn't track a remote branch and the remote has no branch of the same name.

View Source 
var ErrNotInstalled = errors.New("git is not installed")

ErrNotInstalled means no working git binary was found.

View Source 
var ErrNotRepo = errors.New("not a git repository")

ErrNotRepo means the directory is not inside a git work tree.

View Source 
var ErrRejected = errors.New("the remote has commits this branch doesn't have; pull first")

ErrRejected means the remote has commits the local branch lacks.

Functions

func AskPass 

func AskPass(args []string, out io.Writer) int

AskPass answers a git credential prompt from the environment: the user name for a "Username for ..." prompt, the token for a "Password for ..." one. It returns the exit code; git treats a non-zero code as no answer.

func ForgetAuth 

func ForgetAuth(remote string) error

ForgetAuth removes the credentials saved for remote's server.

func IsHTTP 

func IsHTTP(remote string) bool

IsHTTP reports whether remote is an http or https URL, the kind that takes a user name and token. Other remotes use SSH or the file system.

func SaveAuth 

func SaveAuth(remote string, a Auth) error

SaveAuth keeps a for remote's server in the OS secret store.

Types

type Auth 

type Auth struct {
	Username string
	Password string
}

Auth is a user name and token (or password) for an HTTPS remote. The zero Auth leaves authentication to the user's own git setup: credential helpers, SSH keys and agents.

func LoadAuth 

func LoadAuth(remote string) Auth

LoadAuth returns the credentials saved for remote's server, or the zero Auth when there are none or remote is not an HTTP URL.

type Branch 

type Branch struct {
	// Name is "main" for a local branch, "origin/main" for a remote one.
	Name    string
	Remote  bool
	Current bool
	// Upstream is the remote branch a local branch tracks, or "".
	Upstream string
}

Branch is a local branch, or a remote one with no local branch of the same name.

type Change 

type Change struct {
	// Path is relative to the workspace, with forward slashes.
	Path string
	// OrigPath is the path before a rename. It is "" when the file was
	// renamed from outside the workspace.
	OrigPath string
	Kind     ChangeKind
	// Staged and Unstaged are git's X and Y status letters, '.' for none.
	Staged, Unstaged byte
}

Change is a file that differs from the last commit, staged or not.

type ChangeKind 

type ChangeKind int

ChangeKind is how a file differs from the last commit. 

const (
	Modified ChangeKind = iota
	Added
	Deleted
	Renamed
	Untracked
	Conflicted
)

func (ChangeKind) String 

func (k ChangeKind) String() string

type Commit 

type Commit struct {
	Hash    string
	Short   string
	Parents []string
	Author  string
	Email   string
	When    time.Time
	Subject string
}

Commit is one entry of the history.

type ExitError 

type ExitError struct {
	Args    []string
	Code    int
	Message string
}

ExitError is a git command that failed. Message is what git wrote to stderr.

func (*ExitError) Error 

func (e *ExitError) Error() string

type Git 

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

Git is a git binary that was found and runs.

func Find 

func Find(ctx context.Context) (*Git, error)

Find looks git up on PATH, then in the places installers put it, and checks that it runs. A GUI app may start with a shorter PATH than a shell, and on Windows it keeps the PATH it started with after git is installed. On macOS /usr/bin/git is a stub that fails until the command line tools are installed, so finding the file is not enough.

func (*Git) Clone 

func (g *Git) Clone(ctx context.Context, url, dir string, auth Auth) error

Clone copies the repository at url into dir, which must not exist or be empty.

func (*Git) Init 

func (g *Git) Init(ctx context.Context, dir string) error

Init makes dir the root of a new repository. A git that has no default branch configured starts on main.

func (*Git) Open 

func (g *Git) Open(ctx context.Context, dir string) (*Repo, error)

Open finds the work tree dir belongs to. It returns ErrNotRepo when there is none.

func (*Git) Version 

func (g *Git) Version() string

Version is the version git reports, such as "2.53.0".

type Op 

type Op int

Op is a multi-step operation git is in the middle of. 

const (
	OpNone Op = iota
	OpMerge
	OpRevert
	OpRebase
	OpCherryPick
)

func (Op) String 

func (o Op) String() string

type Repo 

type Repo struct {

	// Dir is the workspace directory.
	Dir string
	// Root is the top of the work tree.
	Root string
	// contains filtered or unexported fields
}

Repo is a workspace directory inside a git work tree. The work tree may be the workspace itself or a directory above it; paths Repo takes and returns are relative to the workspace and use forward slashes.

func (*Repo) Abort 

func (r *Repo) Abort(ctx context.Context, op Op) error

Abort gives up the operation in progress and puts the branch and files back as they were before it.

func (*Repo) Branches 

func (r *Repo) Branches(ctx context.Context) ([]Branch, error)

Branches lists the local branches, then the remote branches no local branch tracks.

func (*Repo) Commit 

func (r *Repo) Commit(ctx context.Context, message string, changes []Change) (string, error)

Commit records the changes, and only them, with message. Other changes, staged or not, are left as they are. It returns the new commit's id.

func (*Repo) CommitChanges 

func (r *Repo) CommitChanges(ctx context.Context, c Commit) ([]Change, error)

CommitChanges lists the workspace files c changed, compared with its first parent.

func (*Repo) CommitDiff 

func (r *Repo) CommitDiff(ctx context.Context, c Commit, ch Change) ([]byte, error)

CommitDiff is the patch c made to one file.

func (*Repo) ConflictVersions 

func (r *Repo) ConflictVersions(ctx context.Context, path string) (Versions, error)

ConflictVersions reads the common ancestor's, this branch's and the incoming version of a conflicted file.

func (*Repo) Contained 

func (r *Repo) Contained() bool

Contained reports whether the work tree is the workspace itself rather than a directory above it.

func (*Repo) Continue 

func (r *Repo) Continue(ctx context.Context, op Op) error

Continue records the operation in progress once its conflicts are resolved, with git's own commit message for it.

func (*Repo) CreateBranch 

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

CreateBranch starts a branch named name at HEAD and checks it out.

func (*Repo) Diff 

func (r *Repo) Diff(ctx context.Context, c Change) ([]byte, error)

Diff is the patch from the last commit to the work tree for one change, staged and unstaged edits together.

func (*Repo) Discard 

func (r *Repo) Discard(ctx context.Context, c Change) error

Discard puts a changed file back the way the last commit has it: an edited or deleted file is restored, a new file is deleted.

func (*Repo) Fetch 

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

Fetch updates the remote branches, so ahead and behind counts are current.

func (*Repo) HasCommits 

func (r *Repo) HasCommits(ctx context.Context) bool

HasCommits reports whether HEAD points at a commit. It is false in a repository nobody has committed to yet.

func (*Repo) Identity 

func (r *Repo) Identity(ctx context.Context) (name, email string)

Identity is the name and email commits are made with, from any level of git config. Either is "" when it is not set.

func (*Repo) InProgress 

func (r *Repo) InProgress(ctx context.Context) (Op, string)

InProgress reports the operation git stopped in, for the user to finish or abort, and its message (the merge or revert commit's first line).

func (*Repo) Log 

func (r *Repo) Log(ctx context.Context, n int) ([]Commit, error)

Log returns up to n commits that touched the workspace, newest first. It returns no commits, and no error, before the first commit.

func (*Repo) Merge 

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

Merge merges ref, such as "origin/main", into the current branch. It reports whether git stopped with conflicts for the user to resolve; the merge is then in progress.

func (*Repo) Pull 

func (r *Repo) Pull(ctx context.Context, auth Auth, st *Status) (bool, error)

Pull brings in the remote branch's new commits when the local branch has none of its own. A branch with no upstream starts tracking the remote's branch of the same name. It reports whether HEAD moved.

func (*Repo) Push 

func (r *Repo) Push(ctx context.Context, auth Auth, st *Status) error

Push sends the branch's commits to the remote. A branch with no upstream is pushed to the remote branch of the same name and tracks it.

func (*Repo) Remote 

func (r *Repo) Remote(ctx context.Context) (name, url string, err error)

Remote is the repository's remote: origin, or the first one when there is no origin. Both are "" when the repository has none.

func (*Repo) Resolve 

func (r *Repo) Resolve(ctx context.Context, path string, data []byte) error

Resolve settles a conflicted file with data, or deletes it when data is nil, and marks it resolved.

func (*Repo) Revert 

func (r *Repo) Revert(ctx context.Context, c Commit) (bool, error)

Revert makes a commit that undoes c. A merge commit is undone against its first parent. It reports whether git stopped with conflicts.

func (*Repo) SetIdentity 

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

SetIdentity sets the name and email for commits in this repository only.

func (*Repo) SetRemote 

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

SetRemote points origin, or the remote Remote returns, at url, adding origin when the repository has no remote.

func (*Repo) ShowFile 

func (r *Repo) ShowFile(ctx context.Context, rev, path string) ([]byte, error)

ShowFile reads a file as it was at rev, such as "HEAD".

func (*Repo) Status 

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

Status reads the branch and the changed files in the workspace.

func (*Repo) Switch 

func (r *Repo) Switch(ctx context.Context, b Branch) error

Switch checks out a branch. A remote branch, such as "origin/topic", gets a local branch that tracks it. Work tree changes stay; git refuses when the branch has different versions of the files they touch.

type Status 

type Status struct {
	// Branch is the checked out branch, or "" when HEAD is detached.
	Branch string
	// Head is the commit HEAD points at, or "" before the first commit.
	Head string
	// Upstream is the branch Branch tracks, such as "origin/main", or "".
	Upstream string
	// Ahead and Behind count commits against Upstream.
	Ahead, Behind int
	// Changes are the files in the workspace that differ from Head.
	Changes []Change
}

Status is the state of the work tree and its branch.

type Versions 

type Versions struct {
	Base, Ours, Theirs []byte
}

Versions are the three versions of a conflicted file. A version is nil when that side doesn't have the file.

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.