git

package
v0.1.0-beta5 Latest Latest
Warning

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

 Go to latest Published: Jun 17, 2024 License: GPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

Package git provides access to the Git CLI with a Git library-like interface.

All shell-to-Git interactions should be done through this package.

Index

Constants

This section is empty.

Variables

View Source 
var ErrDetachedHead = errors.New("in detached HEAD state")

ErrDetachedHead indicates that the repository is unexpectedly in detached HEAD state.

View Source 
var ErrNoRebase = errors.New("no rebase in progress")

ErrNoRebase indicates that a rebase is not in progress.

View Source 
var ErrNotExist = errors.New("does not exist")

ErrNotExist is returned when a Git object does not exist.

Functions

This section is empty.

Types

type BlobInfo 

type BlobInfo struct {
	// Mode is the file mode of the blob.
	//
	// Defaults to [RegularMode] if unset.
	Mode Mode

	// Hash is the hash of the blob.
	Hash Hash

	// Path is the path to the blob relative to the tree root.
	// If it contains slashes, intermediate directories will be created.
	Path string
}

BlobInfo is a single blob in a tree.

type BranchDeleteOptions 

type BranchDeleteOptions struct {
	// Force specifies that a branch should be deleted
	// even if it has unmerged changes.
	Force bool

	// Remote indicates that the branch being deleted
	// is a remote tracking branch.
	Remote bool
}

BranchDeleteOptions specifies options for deleting a branch.

type CommitDetail 

type CommitDetail struct {
	// ShortHash is the short (usually 7-character) hash of the commit.
	ShortHash Hash

	// Subject is the first line of the commit message.
	Subject string

	// AuthorDate is the time the commit was authored.
	AuthorDate time.Time
}

CommitDetail contains information about a commit.

func (*CommitDetail) String 

func (cd *CommitDetail) String() string

type CommitMessage 

type CommitMessage struct {
	// Subject for the commit.
	// Contains no leading or trailing whitespace.
	Subject string

	// Body of the commit.
	// Contains no leading or trailing whitespace.
	Body string
}

CommitMessage is the subject and body of a commit.

func (CommitMessage) String 

func (m CommitMessage) String() string

type CommitRange 

type CommitRange []string

CommitRange builds up arguments for a ListCommits command.

func CommitRangeFrom 

func CommitRangeFrom(from Hash) CommitRange

CommitRangeFrom builds a commit range that reports the given commit and all its parents until the root commit.

func (CommitRange) ExcludeFrom 

func (r CommitRange) ExcludeFrom(hash Hash) CommitRange

ExcludeFrom indicates that the listing should exclude commits reachable from the given hash.

func (CommitRange) FirstParent 

func (r CommitRange) FirstParent() CommitRange

FirstParent indicates that only the first parent of each commit should be listed if it is a merge commit.

func (CommitRange) Limit 

func (r CommitRange) Limit(n int) CommitRange

Limit sets the maximum number of commits to list.

type CommitRequest 

type CommitRequest struct {
	// Message is the commit message.
	//
	// If empty, $EDITOR is opened to edit the message.
	Message string

	// All stages all changes before committing.
	All bool

	// Amend amends the last commit.
	Amend bool

	// NoEdit skips editing the commit message.
	NoEdit bool

	// AllowEmpty allows a commit with no changes.
	AllowEmpty bool
}

CommitRequest is a request to commit changes. It relies on the 'git commit' command.

type CommitTreeRequest 

type CommitTreeRequest struct {
	// Hash is the hash of a tree object
	// representing the state of the repository
	// at the time of the commit.
	Tree Hash // required

	// Message is the commit message.
	Message string // required

	// Parents are the hashes of the parent commits.
	// This will usually have one element.
	// It may have more than one element for a merge commit,
	// and no elements for the initial commit.
	Parents []Hash

	// Author and Committer sign the commit.
	// If Committer is nil, Author is used for both.
	//
	// If both are nil, the current user is used.
	// Note that current user may not be available in all contexts.
	// Prefer to set Author and Committer explicitly.
	Author, Committer *Signature
}

CommitTreeRequest is a request to create a new commit.

type CreateBranchRequest 

type CreateBranchRequest struct {
	// Name of the branch.
	Name string

	// Head is the commitish to start the branch from.
	// Defaults to the current HEAD.
	Head string
}

CreateBranchRequest specifies the parameters for creating a new branch.

type FetchOptions 

type FetchOptions struct {
	// Remote is the remote to fetch from.
	//
	// If empty, the default remote for the current branch is used.
	// If the current branch does not have a remote configured,
	// the operation fails.
	Remote string

	// Refspecs are the refspecs to fetch.
	// If non-empty, the Remote must be specified as well.
	Refspecs []Refspec
}

FetchOptions specifies parameters for the Fetch method.

type FileStatus 

type FileStatus struct {
	// Status of the file.
	Status string

	// Path to the file relative to the tree root.
	Path string
}

FileStatus is a single file in a diff.

type FileStatusCode 

type FileStatusCode string

FileStatusCode specifies the status of a file in a diff. 

const (
	FileUnchanged   FileStatusCode = ""
	FileAdded       FileStatusCode = "A"
	FileCopied      FileStatusCode = "C"
	FileDeleted     FileStatusCode = "D"
	FileModified    FileStatusCode = "M"
	FileRenamed     FileStatusCode = "R"
	FileTypeChanged FileStatusCode = "T"
	FileUnmerged    FileStatusCode = "U"
)

List of file status codes from https://git-scm.com/docs/git-diff-index#Documentation/git-diff-index.txt---diff-filterACDMRTUXB82308203.

type Hash 

type Hash string

Hash is a 40-character Git object ID. 

const ZeroHash Hash = "0000000000000000000000000000000000000000"

ZeroHash is the hash of an empty Git object. It is used to represent the absence of a hash.

func (Hash) IsZero 

func (h Hash) IsZero() bool

IsZero reports whether the hash is the zero hash.

func (Hash) Short 

func (h Hash) Short() string

Short reports the short form of the hash.

func (Hash) String 

func (h Hash) String() string

type InitOptions 

type InitOptions struct {
	// Log specifies the logger to use for messages.
	Log *log.Logger

	// Branch is the name of the initial branch to create.
	// Defaults to "main".
	Branch string
	// contains filtered or unexported fields
}

InitOptions configures the behavior of Init.

type ListTreeOptions 

type ListTreeOptions struct {
	// Recurse specifies whether subtrees should be expanded.
	Recurse bool
}

ListTreeOptions specifies options for the ListTree operation.

type LocalBranch 

type LocalBranch struct {
	// Name is the name of the branch.
	Name string

	// CheckedOut indicates whether the branch is currently checked out
	// in a worktree.
	CheckedOut bool
}

LocalBranch represents a local branch in a repository.

type Mode 

type Mode int

Mode is the octal file mode of a Git tree entry. 

const (
	ZeroMode    Mode = 0o000000
	RegularMode Mode = 0o100644
	DirMode     Mode = 0o40000
)

List of modes that git-spice cares about. Git recognizes a few more, but we don't use them.

func ParseMode 

func ParseMode(s string) (Mode, error)

ParseMode parses a Git tree entry mode from a string. These strings are octal numbers, e.g. 

100644
040000

Git only recognizes a handful of values for this, but we don't enforce that here.

func (Mode) String 

func (m Mode) String() string

type OpenOptions 

type OpenOptions struct {
	// Log specifies the logger to use for messages.
	Log *log.Logger
	// contains filtered or unexported fields
}

OpenOptions configures the behavior of Open.

type PullOptions 

type PullOptions struct {
	Remote    string
	Rebase    bool
	Autostash bool
	Refspec   Refspec
}

PullOptions specifies options for the Pull operation.

type PushOptions 

type PushOptions struct {
	// Remote is the remote to push to.
	//
	// If empty, the default remote for the current branch is used.
	// If the current branch does not have a remote configured,
	// the operation fails.
	Remote string

	// ForceWithLease indicates that a push should overwrite a ref
	// even if the new value is not a descendant of the current value
	// provided that our knowledge of the current value is up-to-date.
	ForceWithLease string

	// Refspec is the refspec to push.
	// If empty, the current branch is pushed to the remote.
	Refspec Refspec
}

PushOptions specifies options for the Push operation.

type RebaseBackend 

type RebaseBackend int

RebaseBackend specifies the kind of rebase backend in use.

See https://git-scm.com/docs/git-rebase#_behavioral_differences for details. 

const (
	// RebaseBackendMerge refers to the "merge" backend.
	// It is the default backend used by Git,
	// and handles more corner cases better.
	RebaseBackendMerge RebaseBackend = iota

	// RebaseBackendApply refers to the "apply" backend.
	// It is rarely used and may be phased out in the future
	// if the merge backend gains all of its features.
	// It is enabled with the --apply flag.
	RebaseBackendApply
)

func (RebaseBackend) String 

func (b RebaseBackend) String() string

type RebaseInterruptError 

type RebaseInterruptError struct {
	Kind  RebaseInterruptKind
	State *RebaseState // always non-nil

	// Err is non-nil only if the rebase operation failed
	// due to a conflict.
	Err error
}

RebaseInterruptError indicates that a rebasing operation was interrupted. It includes the kind of interruption and the current rebase state.

func (*RebaseInterruptError) Error 

func (e *RebaseInterruptError) Error() string

func (*RebaseInterruptError) Unwrap 

func (e *RebaseInterruptError) Unwrap() error

type RebaseInterruptKind 

type RebaseInterruptKind int

RebaseInterruptKind specifies the kind of rebase interruption. 

const (
	// RebaseInterruptConflict indicates that a rebase operation
	// was interrupted due to a conflict.
	RebaseInterruptConflict RebaseInterruptKind = iota

	// RebaseInterruptDeliberate indicates that a rebase operation
	// was interrupted deliberately by the user.
	// This is usually done to edit the rebase instructions.
	RebaseInterruptDeliberate
)

type RebaseRequest 

type RebaseRequest struct {
	// Branch is the branch to rebase.
	Branch string

	// Upstream is the upstream commitish
	// from which the current branch started.
	//
	// Commits between Upstream and Branch will be rebased.
	Upstream string

	// Onto is the new base commit to rebase onto.
	// If unspecified, defaults to Upstream.
	Onto string

	// Autostash is true if the rebase should automatically stash
	// dirty changes before starting the rebase operation,
	// and re-apply them after the rebase is complete.
	Autostash bool

	// Quiet reduces the output of the rebase operation.
	Quiet bool

	// Interactive is true if the rebase should present the user
	// with a list of rebase instructions to edit
	// before starting the rebase operation.
	Interactive bool
}

RebaseRequest is a request to rebase a branch.

type RebaseState 

type RebaseState struct {
	// Branch is the branch being rebased.
	Branch string

	// Backend specifies which merge backend is being used.
	// Merge is the default.
	// Apply is rarely used and may be phased out in the future.
	Backend RebaseBackend
}

RebaseState holds information about the current state of a rebase operation.

type Refspec 

type Refspec string

Refspec specifies which refs to fetch/submit for fetch/push operations. See git-fetch(1) and git-push(1) for more information.

func (Refspec) String 

func (r Refspec) String() string

type RenameBranchRequest 

type RenameBranchRequest struct {
	// OldName is the current name of the branch.
	OldName string

	// NewName is the new name for the branch.
	NewName string
}

RenameBranchRequest specifies the parameters for renaming a branch.

type Repository 

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

Repository is a handle to a Git repository. It provides read-write access to the repository's contents.

func Init 

func Init(ctx context.Context, dir string, opts InitOptions) (*Repository, error)

Init initializes a new Git repository at the given directory. If dir is empty, the current working directory is used.

func Open 

func Open(ctx context.Context, dir string, opts OpenOptions) (*Repository, error)

Open opens the repository at the given directory. If dir is empty, the current working directory is used.

func (*Repository) BranchUpstream 

func (r *Repository) BranchUpstream(ctx context.Context, branch string) (string, error)

BranchUpstream reports the upstream branch of a local branch. Returns ErrNotExist if the branch has no upstream configured.

func (*Repository) Checkout 

func (r *Repository) Checkout(ctx context.Context, branch string) error

Checkout switches to the specified branch. If the branch does not exist, it returns an error.

func (*Repository) Commit 

func (r *Repository) Commit(ctx context.Context, req CommitRequest) error

Commit runs the 'git commit' command, allowing the user to commit changes.

func (*Repository) CommitMessageRange 

func (r *Repository) CommitMessageRange(ctx context.Context, start, stop string) ([]CommitMessage, error)

CommitMessageRange returns the commit messages in the range (start, ^stop). That is, all commits reachable from start but not from stop.

func (*Repository) CommitSubject 

func (r *Repository) CommitSubject(ctx context.Context, commitish string) (string, error)

CommitSubject returns the subject of a commit.

func (*Repository) CommitTree 

func (r *Repository) CommitTree(ctx context.Context, req CommitTreeRequest) (Hash, error)

CommitTree creates a new commit with a given tree hash as the state of the repository.

It returns the hash of the new commit.

func (*Repository) CountCommits 

func (r *Repository) CountCommits(ctx context.Context, commits CommitRange) (int, error)

CountCommits reports the number of commits matched by the given range.

func (*Repository) CreateBranch 

func (r *Repository) CreateBranch(ctx context.Context, req CreateBranchRequest) error

CreateBranch creates a new branch in the repository. This operation fails if a branch with the same name already exists.

func (*Repository) CurrentBranch 

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

CurrentBranch reports the current branch name. It returns ErrDetachedHead if the repository is in detached HEAD state.

func (*Repository) DeleteBranch 

func (r *Repository) DeleteBranch(
	ctx context.Context,
	branch string,
	opts BranchDeleteOptions,
) error

DeleteBranch deletes a branch from the repository. It returns an error if the branch does not exist, or if it has unmerged changes and the Force option is not set.

func (*Repository) DetachHead 

func (r *Repository) DetachHead(ctx context.Context, commitish string) error

DetachHead detaches the HEAD from the current branch while staying at the same commit.

func (*Repository) DiffIndex 

func (r *Repository) DiffIndex(ctx context.Context, treeish string) ([]FileStatus, error)

DiffIndex compares the index with the given tree and returns the list of files that are different.

The treeish argument can be any valid tree-ish reference.

func (*Repository) Fetch 

func (r *Repository) Fetch(ctx context.Context, opts FetchOptions) error

Fetch fetches objects and refs from a remote repository.

func (*Repository) ForkPoint 

func (r *Repository) ForkPoint(ctx context.Context, a, b string) (Hash, error)

ForkPoint reports the point at which b diverged from a. See man git-merge-base for more information.

func (*Repository) HashAt 

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

HashAt reports the hash of the object at the provided path in the given treeish.

func (*Repository) Head 

func (r *Repository) Head(ctx context.Context) (Hash, error)

Head reports the commit hash of HEAD.

func (*Repository) IsAncestor 

func (r *Repository) IsAncestor(ctx context.Context, a, b Hash) bool

IsAncestor reports whether a is an ancestor of b.

func (*Repository) ListCommits 

func (r *Repository) ListCommits(ctx context.Context, commits CommitRange) ([]Hash, error)

ListCommits returns a list of commits matched by the given range.

func (*Repository) ListCommitsDetails 

func (r *Repository) ListCommitsDetails(ctx context.Context, commits CommitRange) ([]CommitDetail, error)

ListCommitsDetails returns details about commits matched by the given range.

func (*Repository) ListRemotes 

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

ListRemotes returns a list of remotes for the repository.

func (*Repository) ListTree 

func (r *Repository) ListTree(
	ctx context.Context,
	tree Hash,
	opts ListTreeOptions,
) (_ []TreeEntry, err error)

ListTree lists the entries in the given tree.

By default, the returned entries will only include the immediate children of the tree. Subdirectories will be listed as tree objects, and have to be expanded manually.

If opts.Recurse is true, this operation will expand all subtrees. The returned entries will only include blobs, and their path will be the full path relative to the root of the tree.

func (*Repository) LocalBranches 

func (r *Repository) LocalBranches(ctx context.Context) ([]LocalBranch, error)

LocalBranches lists local branches in the repository.

func (*Repository) MakeTree 

func (r *Repository) MakeTree(ctx context.Context, ents []TreeEntry) (_ Hash, err error)

MakeTree creates a new Git tree from the given entries. The tree will contain *only* the given entries and nothing else. Entries must not contain slashes in their names; this operation does not create subtrees.

func (*Repository) MergeBase 

func (r *Repository) MergeBase(ctx context.Context, a, b string) (Hash, error)

MergeBase reports the common ancestor of a and b.

func (*Repository) PeelToCommit 

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

PeelToCommit reports the commit hash of the provided commit-ish. It returns ErrNotExist if the object does not exist.

func (*Repository) PeelToTree 

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

PeelToTree reports the tree object at the provided tree-ish. It returns ErrNotExist if the object does not exist.

func (*Repository) Pull 

func (r *Repository) Pull(ctx context.Context, opts PullOptions) error

Pull fetches objects and refs from a remote repository and merges them into the current branch.

func (*Repository) Push 

func (r *Repository) Push(ctx context.Context, opts PushOptions) error

Push pushes objects and refs to a remote repository.

func (*Repository) ReadObject 

func (r *Repository) ReadObject(ctx context.Context, typ Type, hash Hash, dst io.Writer) error

ReadObject reads the object with the given hash from the repository into the given writer.

This is not useful for tree objects. Use ListTree instead.

func (*Repository) Rebase 

func (r *Repository) Rebase(ctx context.Context, req RebaseRequest) error

Rebase runs a git rebase operation with the specified parameters. It returns [ErrRebaseInterrupted] or [ErrRebaseConflict] for known rebase interruptions.

func (*Repository) RebaseAbort 

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

RebaseAbort aborts an ongoing rebase operation.

func (*Repository) RebaseContinue 

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

RebaseContinue continues an ongoing rebase operation.

func (*Repository) RebaseState 

func (r *Repository) RebaseState(context.Context) (*RebaseState, error)

RebaseState loads information about an ongoing rebase, or ErrNoRebase if no rebase is in progress.

func (*Repository) RemoteDefaultBranch 

func (r *Repository) RemoteDefaultBranch(ctx context.Context, remote string) (string, error)

RemoteDefaultBranch reports the default branch of a remote. The remote must be known to the repository.

func (*Repository) RemoteURL 

func (r *Repository) RemoteURL(ctx context.Context, remote string) (string, error)

RemoteURL reports the URL of a known Git remote.

func (*Repository) RenameBranch 

func (r *Repository) RenameBranch(ctx context.Context, req RenameBranchRequest) error

RenameBranch renames a branch in the repository.

func (*Repository) SetBranchUpstream 

func (r *Repository) SetBranchUpstream(
	ctx context.Context,
	branch, upstream string,
) error

SetBranchUpstream sets the upstream ref for a local branch. The upstream must be in the form "remote/branch".

func (*Repository) SetRef 

func (r *Repository) SetRef(ctx context.Context, req SetRefRequest) error

SetRef changes the value of a ref to a new hash.

It optionally allows verifying the current value of the ref before updating it.

func (*Repository) UpdateTree 

func (r *Repository) UpdateTree(ctx context.Context, req UpdateTreeRequest) (_ Hash, err error)

UpdateTree updates an existing Git tree with differential changes to blobs and returns the hash of the new tree.

func (*Repository) WriteObject 

func (r *Repository) WriteObject(ctx context.Context, typ Type, src io.Reader) (Hash, error)

WriteObject writes an object of the given type to the repository, and returns the hash of the written object.

type SetRefRequest 

type SetRefRequest struct {
	// Ref is the name of the ref to set.
	// If the ref is a branch or tag, it should be fully qualified
	// (e.g., "refs/heads/main" or "refs/tags/v1.0").
	Ref string

	// Hash is the hash to set the ref to.
	Hash Hash

	// OldHash, if set, specifies the current value of the ref.
	// The ref will only be updated if it currently points to OldHash.
	// Set this to ZeroHash to ensure that a ref being created
	// does not already exist.
	OldHash Hash
}

SetRefRequest is a request to set a ref to a new hash.

type Signature 

type Signature struct {
	// Name of the signer.
	Name string

	// Email of the signer.
	Email string

	// Time at which the signature was made.
	// If this is zero, the current time is used.
	Time time.Time
}

Signature holds authorship information for a commit.

type TreeEntry 

type TreeEntry struct {
	// Mode is the file mode of the entry.
	//
	// For regular files, this is RegularMode.
	// For directories, this is DirMode.
	Mode Mode

	// Type is the type of the entry.
	//
	// This is either BlobType or TreeType.
	Type Type

	// Hash is the hash of the entry.
	Hash Hash

	// Name is the name of the entry.
	Name string
}

TreeEntry is a single entry in a Git tree.

type Type 

type Type string

Type specifies the type of a Git object. 

const (
	BlobType   Type = "blob"
	CommitType Type = "commit"
	TreeType   Type = "tree"
)

Supported object types.

func (Type) String 

func (t Type) String() string

type UpdateTreeRequest 

type UpdateTreeRequest struct {
	// Tree is the starting tree hash.
	//
	// This may be empty or [ZeroHash] to start with an empty tree.
	Tree Hash

	// Writes is a sequence of blobs to write to the tree.
	Writes []BlobInfo

	// Deletes is a set of paths to delete from the tree.
	Deletes []string
}

UpdateTreeRequest is a request to update an existing Git tree.

Unlike MakeTree, it's able to operate on paths with slashes.

Source Files

View all Source files

Directories

Path Synopsis
Package gittest provides utilities for testing git repositories.
 Package gittest provides utilities for testing git repositories.

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.