README ¶
Gitz
Write fluent interactions to Git using the gitz
library. Programmatically crafting git commands becomes a breeze! Verify your code using the inbuilt testing framework.
Badges
Documentation
Check out the latest documentation
Documentation ¶
Overview ¶
Package git provides a simple lightweight library for performing fluent git operations against an existing cloned repository
Index ¶
- Constants
- func CheckConfigPath(path string) error
- func ToInlineConfig(pairs ...string) ([]string, error)
- type BlobDetails
- type CheckoutOption
- type Client
- func (c *Client) Checkout(branch string, opts ...CheckoutOption) (string, error)
- func (c *Client) Clean() (bool, error)
- func (c *Client) Clone(url string, opts ...CloneOption) (string, error)
- func (c *Client) Commit(msg string, opts ...CommitOption) (string, error)
- func (c *Client) Config() (map[string]string, error)
- func (c *Client) ConfigG(paths ...string) (map[string][]string, error)
- func (c *Client) ConfigL(paths ...string) (map[string][]string, error)
- func (c *Client) ConfigS(paths ...string) (map[string][]string, error)
- func (c *Client) ConfigSetG(pairs ...string) error
- func (c *Client) ConfigSetL(pairs ...string) error
- func (c *Client) ConfigSetS(pairs ...string) error
- func (c *Client) DeleteTag(tag string, opts ...DeleteTagsOption) (string, error)
- func (c *Client) DeleteTags(tags []string, opts ...DeleteTagsOption) (string, error)
- func (c *Client) Diff(opts ...DiffOption) ([]FileDiff, error)
- func (c *Client) Fetch(opts ...FetchOption) (string, error)
- func (c *Client) Log(opts ...LogOption) (*Log, error)
- func (c *Client) PorcelainStatus(opts ...StatusOption) ([]FileStatus, error)
- func (c *Client) Pull(opts ...PullOption) (string, error)
- func (c *Client) Push(opts ...PushOption) (string, error)
- func (c *Client) PushRef(ref string) (string, error)
- func (c *Client) Repository() (Repository, error)
- func (c *Client) RestoreUsing(statuses []FileStatus) error
- func (c *Client) ShowBlobs(refs ...string) (map[string]BlobDetails, error)
- func (c *Client) ShowCommits(refs ...string) (map[string]CommitDetails, error)
- func (c *Client) ShowTags(refs ...string) (map[string]TagDetails, error)
- func (c *Client) ShowTrees(refs ...string) (map[string]TreeDetails, error)
- func (c *Client) Stage(opts ...StageOption) (string, error)
- func (c *Client) Staged() ([]string, error)
- func (c *Client) Tag(tag string, opts ...CreateTagOption) (string, error)
- func (c *Client) TagBatch(tags []string, opts ...CreateTagOption) (string, error)
- func (c *Client) TagBatchAt(pairs []string, opts ...CreateTagOption) (string, error)
- func (c *Client) Tags(opts ...ListTagsOption) ([]string, error)
- func (c *Client) ToRelativePath(path string) (string, error)
- func (c *Client) VerifyCommit(hash string) (*CommitVerification, error)
- func (c *Client) VerifyTag(ref string) (*TagVerification, error)
- func (c *Client) Version() string
- type CloneOption
- type CommitDetails
- type CommitOption
- type CommitVerification
- type CreateTagOption
- func WithAnnotation(message string) CreateTagOption
- func WithCommitRef(ref string) CreateTagOption
- func WithLocalOnly() CreateTagOption
- func WithSigned() CreateTagOption
- func WithSigningKey(key string) CreateTagOption
- func WithSkipSigning() CreateTagOption
- func WithTagConfig(kv ...string) CreateTagOption
- type DeleteTagsOption
- type DiffChange
- type DiffChunk
- type DiffOption
- type ErrGitExecCommand
- type ErrGitMissing
- type ErrGitNonRelativePath
- type ErrInvalidConfigPath
- type ErrMissingConfigValue
- type ErrMissingTagCommitRef
- type FetchOption
- type FileDiff
- type FileStatus
- type FileStatusIndicator
- type ListTagsOption
- type Log
- type LogEntry
- type LogOption
- func WithGrep(matches ...string) LogOption
- func WithInvertGrep(matches ...string) LogOption
- func WithMatchAll() LogOption
- func WithPaths(paths ...string) LogOption
- func WithRawOnly() LogOption
- func WithRef(ref string) LogOption
- func WithRefRange(fromRef string, toRef string) LogOption
- func WithSkip(n int) LogOption
- func WithTake(n int) LogOption
- type Person
- type PullOption
- type PushOption
- type Repository
- type Signature
- type SortKey
- type StageOption
- type StatusOption
- type TagAnnotation
- type TagDetails
- type TagFilter
- type TagVerification
- type TreeDetails
Constants ¶
const ( // RelativeAtRoot can be used to compare if a path is equivalent to the // root of a current git repository working directory RelativeAtRoot = "." // HeadRef is a pointer to the latest commit within a git repository HeadRef = "HEAD" )
Variables ¶
This section is empty.
Functions ¶
func CheckConfigPath ¶ added in v0.4.0
CheckConfigPath performs rudimentary checks to ensure the config path conforms to the git config specification. A config path is invalid if:
- No dot separator exists, or the last character is a dot separator
- First character after the last dot separator is not a letter
- Path contains non-alphanumeric characters
func ToInlineConfig ¶ added in v0.6.0
ToInlineConfig converts a series of config settings from path value notation into the corresponding inline config notation compatible with git commands
"user.name", "penguin" => []string{"-c user.name='penguin'"}
Types ¶
type BlobDetails ¶ added in v0.6.0
type BlobDetails struct { // Diff contains the blobs contents Diff string // Ref contains the unique identifier associated with the blob Ref string }
BlobDetails contains details about a specific blob within a repository
type CheckoutOption ¶ added in v0.6.0
type CheckoutOption func(*checkoutOptions)
CheckoutOption provides a way for setting specific options while attempting to checkout a branch. Each supported option can customize how a branch is checked out from the remote and integrated into the current repository (working directory)
func WithCheckoutConfig ¶ added in v0.6.0
func WithCheckoutConfig(kv ...string) CheckoutOption
WithCheckoutConfig allows temporary git config to be set while checking out a branch from the remote. Config set using this approach will override any config defined within existing git config files. Config must be provided as key value pairs, mismatched config will result in an ErrMissingConfigValue error. Any invalid paths will result in an ErrInvalidConfigPath error
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client provides a way of performing fluent operations against git. Any git operation exposed by this client are effectively handed-off to an installed git client on the current OS. Git operations will be mapped as closely as possible to the official Git specification
func (*Client) Checkout ¶ added in v0.3.0
func (c *Client) Checkout(branch string, opts ...CheckoutOption) (string, error)
Checkout will attempt to checkout a branch with the given name. If the branch does not exist, it is created at the current working tree reference (or commit), and then switched to. If the branch does exist, then switching to it restores all working tree files
func (*Client) Clean ¶ added in v0.6.0
Clean determines if the current repository (working directory) is in a clean state. A repository is deemed clean, if it contains no changes
func (*Client) Clone ¶ added in v0.2.0
func (c *Client) Clone(url string, opts ...CloneOption) (string, error)
Clone a repository by its provided URL into a newly created directory. A default clone will ensure remote tracking branches are created for each branch within the repository with only the default branch being checked out fully. The cloned directory will mirror that of the repository name within its URL. Options can be provided to customize the clone behavior
func (*Client) Commit ¶
func (c *Client) Commit(msg string, opts ...CommitOption) (string, error)
Commit a snapshot of changes within the current repository (working directory) and describe those changes with a given log message. Commit behavior can be customized through the use of options
func (*Client) Config ¶ added in v0.4.0
Config attempts to retrieve all git config for the current repository. A map is returned containing each config item and its corresponding latest value. Values are resolved from local, system and global config
func (*Client) ConfigG ¶ added in v0.5.0
ConfigG attempts to query a batch of global git config settings for their values. If multiple values have been set for any config item, all are returned, ordered by most recent value first. A partial batch is never returned, all config settings must exist
func (*Client) ConfigL ¶ added in v0.4.0
ConfigL attempts to query a batch of local git config settings for their values. If multiple values have been set for any config item, all are returned, ordered by most recent value first. A partial batch is never returned, all config settings must exist
func (*Client) ConfigS ¶ added in v0.5.0
ConfigS attempts to query a batch of system git config settings for their values. If multiple values have been set for any config item, all are returned, ordered by most recent value first. A partial batch is never returned, all config settings must exist
func (*Client) ConfigSetG ¶ added in v0.5.0
ConfigSetG attempts to batch assign values to a group of global git config settings. If any setting exists, a new line is added to the local git config, effectively assigning multiple values to the same setting. Basic validation is performed to minimize the possibility of a partial batch update
func (*Client) ConfigSetL ¶ added in v0.4.0
ConfigSetL attempts to batch assign values to a group of local git config settings. If any setting exists, a new line is added to the local git config, effectively assigning multiple values to the same setting. Basic validation is performed to minimize the possibility of a partial batch update
func (*Client) ConfigSetS ¶ added in v0.5.0
ConfigSetS attempts to batch assign values to a group of system git config settings. If any setting exists, a new line is added to the local git config, effectively assigning multiple values to the same setting. Basic validation is performed to minimize the possibility of a partial batch update
func (*Client) DeleteTag ¶
func (c *Client) DeleteTag(tag string, opts ...DeleteTagsOption) (string, error)
DeleteTag a tag both locally and from the remote origin
func (*Client) DeleteTags ¶ added in v0.6.0
func (c *Client) DeleteTags(tags []string, opts ...DeleteTagsOption) (string, error)
DeleteTags will attempt to delete a series of tags from the current repository and push those deletions back to the remote
func (*Client) Diff ¶ added in v0.9.0
func (c *Client) Diff(opts ...DiffOption) ([]FileDiff, error)
Diff captures the changes made to files within the current repository (working directory). Options can be provided to customize how the current diff is determined. By default, all diffs (or changes) to files within the repository will be retrieved. The diff is generated using the following git options:
git diff -U0 --no-color
func (*Client) Fetch ¶ added in v0.7.0
func (c *Client) Fetch(opts ...FetchOption) (string, error)
Fetch all remote changes from a remote repository without integrating (merging) them into the current repository (working directory). Ensures the current repository only tracks the latest remote changes
func (*Client) Log ¶
Log retrieves the commit log of the current repository (working directory) in an easy-to-parse format. Options can be provided to customize log retrieval, creating a targeted snapshot. By default, the entire history from the repository HEAD (most recent commit) will be retrieved. The logs are generated using the default git options:
git log --pretty='format:> %H %B%-N' --no-color
func (*Client) PorcelainStatus ¶ added in v0.6.0
func (c *Client) PorcelainStatus(opts ...StatusOption) ([]FileStatus, error)
PorcelainStatus identifies if there are any changes within the current repository (working directory) and returns them in the parseable porcelain v1 format
func (*Client) Pull ¶
func (c *Client) Pull(opts ...PullOption) (string, error)
Pull all changes from a remote repository and immediately update the current repository (working directory) with those changes. This ensures that your current repository keeps track of remote changes and stays in sync
func (*Client) Push ¶
func (c *Client) Push(opts ...PushOption) (string, error)
Push (or upload) all local changes to the remote repository. By default, changes associated with the current branch will be pushed back to the remote. Options can be provided to configure branch and tag push semantics
func (*Client) PushRef ¶ added in v0.3.0
PushRef will push an individual reference to the remote repository Deprecated: use [Push] instead
func (*Client) Repository ¶ added in v0.2.0
func (c *Client) Repository() (Repository, error)
Repository captures and returns a snapshot of the current repository (working directory) state
func (*Client) RestoreUsing ¶ added in v0.9.0
func (c *Client) RestoreUsing(statuses []FileStatus) error
RestoreUsing will restore a given set of files back to their previous known state within the current repository (working directory). By inspecting each files FileStatus, the correct decision can be made when restoring it
func (*Client) ShowBlobs ¶ added in v0.6.0
func (c *Client) ShowBlobs(refs ...string) (map[string]BlobDetails, error)
ShowBlobs retrieves details about any number of blobs within the current repository (working directory)
func (*Client) ShowCommits ¶ added in v0.6.0
func (c *Client) ShowCommits(refs ...string) (map[string]CommitDetails, error)
ShowCommits retrieves details about any number of commits within the current repository (working directory)
func (*Client) ShowTags ¶ added in v0.6.0
func (c *Client) ShowTags(refs ...string) (map[string]TagDetails, error)
ShowTags retrieves details about any number of tags within the current repository (working directory)
func (*Client) ShowTrees ¶ added in v0.6.0
func (c *Client) ShowTrees(refs ...string) (map[string]TreeDetails, error)
ShowTrees retrieves details about any number of trees within the current repository (working directory)
func (*Client) Stage ¶
func (c *Client) Stage(opts ...StageOption) (string, error)
Stage changes to any file or folder within the current repository (working directory) ready for inclusion in the next commit. Options can be provided to further configure stage semantics. By default, all changes will be staged ready for the next commit.
func (*Client) Staged ¶ added in v0.6.0
Staged retrieves a list of all currently staged file changes within the current repository
func (*Client) Tag ¶
func (c *Client) Tag(tag string, opts ...CreateTagOption) (string, error)
Tag a specific point within a repositories history and push it to the configured remote. Tagging comes in two flavours:
- A lightweight tag, which points to a specific commit within the history and marks a specific point in time
- An annotated tag, which is treated as a full object within git, and must include a tagging message (or annotation)
By default, a lightweight tag will be created, unless specific tag options are provided
func (*Client) TagBatch ¶ added in v0.8.0
func (c *Client) TagBatch(tags []string, opts ...CreateTagOption) (string, error)
TagBatch attempts to create a batch of tags against a specific point within a repositories history. All tags are created locally and then pushed in a single transaction to the remote. This behavior is enforced by explicitly enabling the WithLocalOnly option
func (*Client) TagBatchAt ¶ added in v0.8.0
func (c *Client) TagBatchAt(pairs []string, opts ...CreateTagOption) (string, error)
TagBatchAt attempts to create a batch of tags that target specific commits within a repositories history. Any number of pairs consisting of a tag and commit hash must be provided.
TagBatchAt([]string{"0.1.0", "740a8b9", "0.2.0", "9e7dfbb"})
All tags are created locally and then pushed in a single transaction to the remote. This behavior is enforced by explicitly enabling the WithLocalOnly option
func (*Client) Tags ¶ added in v0.3.0
func (c *Client) Tags(opts ...ListTagsOption) ([]string, error)
Tags retrieves all local tags from the current repository (working directory). By default, all tags are retrieved in ascending lexicographic order as implied through the RefName sort key. Options can be provided to customize retrieval
func (*Client) ToRelativePath ¶ added in v0.4.0
ToRelativePath determines if a path is relative to the working directory of the repository and returns the resolved relative path. A ErrGitNonRelativePath error will be returned if the path exists outside of the working directory. RelativeAtRoot is returned if the path and working directory are equivalent
func (*Client) VerifyCommit ¶ added in v0.5.0
func (c *Client) VerifyCommit(hash string) (*CommitVerification, error)
VerifyCommit validates that a given commit has a valid GPG signature and returns details about that signature
type CloneOption ¶ added in v0.3.0
type CloneOption func(*cloneOptions)
CloneOption provides a way for setting specific options during a clone operation. Each supported option can customize the way in which the repository is cloned onto the file system into a target working directory
func WithCheckoutRef ¶ added in v0.3.0
func WithCheckoutRef(ref string) CloneOption
WithCheckoutRef changes the default checkout behavior after a clone succeeds. A branch or tag reference is supported. Checking out a tag will result in a detached HEAD. An empty string will be ignored
func WithCloneConfig ¶ added in v0.6.0
func WithCloneConfig(kv ...string) CloneOption
WithCloneConfig allows temporary git config to be set while cloning the remote into a newly created directory. Config set using this approach will override any config defined within existing git config files. Config must be provided as key value pairs, mismatched config will result in an ErrMissingConfigValue error. Any invalid paths will result in an ErrInvalidConfigPath error
func WithDepth ¶ added in v0.3.0
func WithDepth(depth int) CloneOption
WithDepth ensures the repository will be cloned at a specific depth, effectively truncating the history to the required number of commits. The result will be a shallow repository. Any depth less than one is ignored, resulting in a full clone of the history
func WithDirectory ¶ added in v0.3.0
func WithDirectory(dir string) CloneOption
WithDirectory provides a named directory for cloning the repository into. If the directory already exists, it must be empty for the clone to be successful. An empty string will be ignored
func WithNoTags ¶ added in v0.3.0
func WithNoTags() CloneOption
WithNoTags prevents any tags from being included during the clone
type CommitDetails ¶ added in v0.6.0
type CommitDetails struct { // Author represents a person who originally created the files // within the repository Author Person // AuthorDate contains the date and time of when the author // originally created the files within the repository AuthorDate time.Time // Committer represents a person who changed any existing files // within the repository Committer Person // CommitterDate contains the date and time of when the committer // changed any existing files within the repository CommitterDate time.Time // Message contains the message associated with the commit Message string // Ref contains the unique identifier associated with the commit Ref string // Signature contains details of the verified GPG signature Signature *Signature }
CommitDetails contains details about a specific commit within a repository
type CommitOption ¶ added in v0.5.0
type CommitOption func(*commitOptions)
CommitOption provides a way for setting specific options during a commit operation. Each supported option can customize the way the commit is created against the current repository (working directory)
func WithAllowEmpty ¶ added in v0.5.0
func WithAllowEmpty() CommitOption
WithAllowEmpty allows a commit to be created without having to track any changes. This bypasses the default protection by git, preventing a commit from having the exact same tree as its parent
func WithCommitConfig ¶ added in v0.6.0
func WithCommitConfig(kv ...string) CommitOption
WithCommitConfig allows temporary git config to be set during the execution of the commit. Config set using this approach will override any config defined within existing git config files. Config must be provided as key value pairs, mismatched config will result in an ErrMissingConfigValue error. Any invalid paths will result in an ErrInvalidConfigPath error
func WithGpgSign ¶ added in v0.5.0
func WithGpgSign() CommitOption
WithGpgSign will create a GPG-signed commit using the GPG key associated with the committers email address. Overriding this behavior is possible through the user.signingkey config setting. This option does not need to be explicitly called if the commit.gpgSign config setting is set to true
func WithGpgSigningKey ¶ added in v0.5.0
func WithGpgSigningKey(key string) CommitOption
WithGpgSigningKey will create a GPG-signed commit using the provided GPG key ID, overridding any default GPG key set by the user.signingKey git config setting
func WithNoGpgSign ¶ added in v0.5.0
func WithNoGpgSign() CommitOption
WithNoGpgSign ensures the created commit will not be GPG signed regardless of the value assigned to the repositories commit.gpgSign git config setting
type CommitVerification ¶ added in v0.5.0
type CommitVerification struct { // Author represents a person who originally created the files // within the repository Author Person // Committer represents a person who changed any existing files // within the repository Committer Person // Hash contains the unique identifier associated with the commit Hash string // Message contains the message associated with the commit Message string // Signature contains details of the verified GPG signature Signature *Signature }
CommitVerification contains details about a GPG signed commit
type CreateTagOption ¶ added in v0.3.0
type CreateTagOption func(*createTagOptions)
CreateTagOption provides a way for setting specific options during a tag creation operation. Each supported option can customize the way the tag is created against the current repository (working directory)
func WithAnnotation ¶
func WithAnnotation(message string) CreateTagOption
WithAnnotation ensures the created tag is annotated with the provided message. This ultimately converts the standard lightweight tag into an annotated tag which is stored as a full object within the git database. Any leading and trailing whitespace will automatically be trimmed from the message. This allows empty messages to be ignored
func WithCommitRef ¶ added in v0.8.0
func WithCommitRef(ref string) CreateTagOption
WithCommitRef ensures the created tag points to a specific commit within the history of the repository. This changes the default behavior of creating a tag against the HEAD (or latest commit) within the repository
func WithLocalOnly ¶ added in v0.7.0
func WithLocalOnly() CreateTagOption
WithLocalOnly ensures the created tag will not be pushed back to the remote and be kept as a local tag only
func WithSigned ¶ added in v0.5.0
func WithSigned() CreateTagOption
WithSigned will create a GPG-signed tag using the GPG key associated with the taggers email address. Overriding this behavior is possible through the user.signingkey config setting. This option does not need to be explicitly called if the tag.gpgSign config setting is set to true. An annotated tag is mandatory when signing. A default annotation will be assigned, unless overridden with the WithAnnotation option:
created tag 0.1.0
func WithSigningKey ¶ added in v0.5.0
func WithSigningKey(key string) CreateTagOption
WithSigningKey will create a GPG-signed tag using the provided GPG key ID, overridding any default GPG key set by the user.signingKey config setting. An annotated tag is mandatory when signing. A default annotation will be assigned, unless overridden with the WithAnnotation option:
created tag 0.1.0
func WithSkipSigning ¶ added in v0.5.0
func WithSkipSigning() CreateTagOption
WithSkipSigning ensures the created tag will not be GPG signed regardless of the value assigned to the repositories tag.gpgSign git config setting
func WithTagConfig ¶ added in v0.6.0
func WithTagConfig(kv ...string) CreateTagOption
WithTagConfig allows temporary git config to be set during the creation of a tag. Config set using this approach will override any config defined within existing git config files. Config must be provided as key value pairs, mismatched config will result in an ErrMissingConfigValue error. Any invalid paths will result in an ErrInvalidConfigPath error
type DeleteTagsOption ¶ added in v0.6.0
type DeleteTagsOption func(*deleteTagsOptions)
DeleteTagsOption provides a way for setting specific options during a tag deletion operation
func WithLocalDelete ¶ added in v0.6.0
func WithLocalDelete() DeleteTagsOption
WithLocalDelete ensures the reference to the tag is deleted from the local index only and is not pushed back to the remote. Useful if working with temporary tags that need to be removed
type DiffChange ¶ added in v0.9.0
type DiffChange struct { // LineNo is the position within the file where the // change starts LineNo int // Count is the number of lines that has changed Count int // Change contains the text that has changed Change string }
DiffChange captures details about an individual chunk within a git diff. It contains both the changed text and its exact position (and line count) within the file
type DiffChunk ¶ added in v0.9.0
type DiffChunk struct { // Added optionally contains details of the text that has // been added to a file as part of the current change Added DiffChange // Removed optionally contains details of the text that has // been removed from a file as part of the current change Removed DiffChange }
DiffChunk represents a snapshot of a single change (chunk) to a file within a repository (working directory)
type DiffOption ¶ added in v0.9.0
type DiffOption func(*diffOptions)
DiffOption provides a way for setting specific options during a diff operation. Each supported option can customize the way the diff is executed against the current repository (working directory)
func WithDiffPaths ¶ added in v0.9.0
func WithDiffPaths(paths ...string) DiffOption
WithDiffPaths allows the diff to be targeted to specific files and folers within the current repository (working directory). Paths to files and folders are relative to the root of the repository. All leading and trailing whitepsace will be trimmed from the file paths, allowing empty paths to be ignored
type ErrGitExecCommand ¶
type ErrGitExecCommand struct { // Cmd contains the command that caused the git client to error Cmd string // Out contains any raw output from the git client as a result // of the error Out string }
ErrGitExecCommand is raised when a git command fails to execute
func (ErrGitExecCommand) Error ¶
func (e ErrGitExecCommand) Error() string
Error returns a friendly formatted message of the current error
type ErrGitMissing ¶
type ErrGitMissing struct { // PathEnv contains the value of the PATH environment variable PathEnv string }
ErrGitMissing is raised when no git client was identified within the PATH environment variable on the current OS
func (ErrGitMissing) Error ¶
func (e ErrGitMissing) Error() string
Error returns a friendly formatted message of the current error
type ErrGitNonRelativePath ¶ added in v0.4.0
type ErrGitNonRelativePath struct { // RootDir contains the root working directory of the repository RootDir string // TargetPath contains the path that was resolved against the // root working directory of the repository TargetPath string // RelativePath contains the resolved relative path which raised // the error RelativePath string }
ErrGitNonRelativePath is raised when attempting to resolve a path within a git repository that isn't relative to the root of the working directory
func (ErrGitNonRelativePath) Error ¶ added in v0.4.0
func (e ErrGitNonRelativePath) Error() string
Error returns a friendly formatted message of the current error
type ErrInvalidConfigPath ¶ added in v0.4.0
type ErrInvalidConfigPath struct { // Path to the config setting Path string // Position of the first offending character within the path Position int // Reason why the path is invalid Reason string }
ErrInvalidConfigPath is raised when a config setting is to be accessed with an invalid config path
func (ErrInvalidConfigPath) Error ¶ added in v0.4.0
func (e ErrInvalidConfigPath) Error() string
Error returns a friendly formatted message of the current error
type ErrMissingConfigValue ¶ added in v0.6.0
type ErrMissingConfigValue struct { // Path to the config setting Path string }
ErrMissingConfigValue is raised when a git config path does not have a corresponding value
func (ErrMissingConfigValue) Error ¶ added in v0.6.0
func (e ErrMissingConfigValue) Error() string
Error returns a friendly formatted message of the current error
type ErrMissingTagCommitRef ¶ added in v0.8.0
type ErrMissingTagCommitRef struct { // Tag reference Tag string }
ErrMissingTagCommitRef is raised when a git tag is missing an associated commit hash
func (ErrMissingTagCommitRef) Error ¶ added in v0.8.0
func (e ErrMissingTagCommitRef) Error() string
Error returns a friendly formatted message of the current error
type FetchOption ¶ added in v0.7.0
type FetchOption func(*fetchOptions)
FetchOption provides a way for setting specific options while fetching changes from the remote. Each supported option can customize how changes are fetched from the remote
func WithAll ¶ added in v0.7.0
func WithAll() FetchOption
WithAll will fetch the latest changes from all tracked remotes
func WithDepthTo ¶ added in v0.7.0
func WithDepthTo(depth int) FetchOption
WithDepthTo will limit the number of commits to be fetched from the remotes history to the specified depth. If fetching into a shallow clone of a repository, this can be used to shorten or deepen the existing history
func WithFetchConfig ¶ added in v0.7.0
func WithFetchConfig(kv ...string) FetchOption
WithFetchConfig allows temporary git config to be set while fetching changes from the remote. Config set using this approach will override any config defined within existing git config files. Config must be provided as key value pairs, mismatched config will result in an ErrMissingConfigValue error. Any invalid paths will result in an ErrInvalidConfigPath error
func WithFetchRefSpecs ¶ added in v0.7.0
func WithFetchRefSpecs(refs ...string) FetchOption
WithFetchRefSpecs allows remote references to be cherry-picked and fetched into the current repository (working copy). A reference (or refspec) can be as simple as a name, where git will automatically resolve any ambiguity, or as explicit as providing a source and destination for reference within the remote. Check out the official git documentation on how to write a more complex [refspec] [refspec]: https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt-ltrefspecgt
func WithForce ¶ added in v0.7.0
func WithForce() FetchOption
WithForce will force the fetching of a remote branch into a local branch with a different name (or refspec). Default behavior within git prevents such an operation. Typically used in conjunction with the WithFetchRefSpecs option
func WithIgnoreTags ¶ added in v0.7.0
func WithIgnoreTags() FetchOption
WithIgnoreTags disables local tracking of tags from the remote
func WithTags ¶ added in v0.7.0
func WithTags() FetchOption
WithTags will fetch all tags from the remote into local tag references with the same name
func WithUnshallow ¶ added in v0.10.0
func WithUnshallow() FetchOption
WithUnshallow will fetch the complete history from the remote
type FileDiff ¶ added in v0.9.0
type FileDiff struct { // Path of the file within the repository (working directory) Path string // DiffChunk contains all of the identified changes within // the file Chunks []DiffChunk }
FileDiff represents a snapshot containing all of the changes to a file within a repository (working directory)
type FileStatus ¶ added in v0.6.0
type FileStatus struct { // Indicators is a two character array that contains // the current status of a file within both the current index // and the working repository tree. // // Examples: // // '??' - a file that is not tracked // ' A' - a file that has been added to the working tree // 'M ' - a file that has been modified within the index Indicators [2]FileStatusIndicator // Path of the file relative to the root of the // current repository Path string }
FileStatus represents the status of a file within a repository
func (FileStatus) Modified ¶ added in v0.9.0
func (f FileStatus) Modified() bool
Modified idenfities whether a file has been modified and therefore contains changes
func (FileStatus) Renamed ¶ added in v0.9.0
func (f FileStatus) Renamed() bool
Renamed identifies whether a file has been renamed
func (FileStatus) String ¶ added in v0.6.0
func (f FileStatus) String() string
String representation of a file status that adheres to the porcelain v1 format
func (FileStatus) Untracked ¶ added in v0.9.0
func (f FileStatus) Untracked() bool
Untracked identifies whether a file is not currently tracked
type FileStatusIndicator ¶ added in v0.6.0
type FileStatusIndicator byte
FileStatusIndicator contains a single character that represents a files status within a git repository. Based on the git specification: https://git-scm.com/docs/git-status#_output
const ( Added FileStatusIndicator = 'A' Copied FileStatusIndicator = 'C' Deleted FileStatusIndicator = 'D' Ignored FileStatusIndicator = '!' Modified FileStatusIndicator = 'M' Renamed FileStatusIndicator = 'R' TypeChanged FileStatusIndicator = 'T' Updated FileStatusIndicator = 'U' Unmodified FileStatusIndicator = ' ' Untracked FileStatusIndicator = '?' )
type ListTagsOption ¶ added in v0.3.0
type ListTagsOption func(*listTagsOptions)
ListTagsOption provides a way for setting specific options during a list tags operation. Each supported option can customize the way in which the tags are queried and returned from the current repository (workng directory)
func WithCount ¶ added in v0.4.0
func WithCount(n int) ListTagsOption
WithCount limits the number of tags that are returned after all processing and filtering has been applied the retrieved list
func WithFilters ¶ added in v0.4.0
func WithFilters(filters ...TagFilter) ListTagsOption
WithFilters allows the retrieved list of tags to be processed with a set of user-defined filters. Each filter is applied in turn to the working set. Nil filters are ignored
func WithShellGlob ¶ added in v0.3.0
func WithShellGlob(patterns ...string) ListTagsOption
WithShellGlob limits the number of tags that will be retrieved, by only returning tags that match a given Shell Glob pattern. If multiple patterns are provided, tags will be retrieved if they match against a single pattern. All leading and trailing whitespace will be trimmed, allowing empty patterns to be ignored
func WithSortBy ¶ added in v0.3.0
func WithSortBy(keys ...SortKey) ListTagsOption
WithSortBy allows the retrieved order of tags to be changed by sorting against a reserved field name. By default, sorting will always be in ascending order. To change this behaviour, prefix a field name with a hyphen (-<fieldname>). You can sort tags against multiple fields, but this does change the expected behavior. The last field name is treated as the primary key for the entire sort. All leading and trailing whitespace will be trimmed, allowing empty field names to be ignored
type Log ¶
type Log struct { // Raw contains the raw commit log Raw string // Commits contains the optionally parsed commit log. By default // the parsed history will always be present, unless the // [WithRawOnly] option is provided during retrieval Commits []LogEntry }
Log represents a snapshot of commit history from a repository
type LogEntry ¶
type LogEntry struct { // Hash contains the unique identifier associated with the commit Hash string // AbbrevHash contains the seven character abbreviated commit hash AbbrevHash string // Message contains the message associated with the commit Message string }
LogEntry represents a single parsed entry from within the commit history of a repository
type LogOption ¶
type LogOption func(*logOptions)
LogOption provides a way for setting specific options during a log operation. Each supported option can customize the way the log history of the current repository (working directory) is processed before retrieval
func WithGrep ¶ added in v0.2.0
WithGrep limits the number of commits that will be output within the log history to any with a log message that contains one of the provided matches (regular expressions). All leading and trailing whitespace will be trimmed, allowing empty matches to be ignored
func WithInvertGrep ¶ added in v0.2.0
WithInvertGrep limits the number of commits that will be output within the log history to any with a log message that does not contain one of the provided matches (regular expressions). All leading and trailing whitespace will be trimmed, allowing empty matches to be ignored
func WithMatchAll ¶ added in v0.2.0
func WithMatchAll() LogOption
WithMatchAll when used in combination with git.WithGrep will limit the number of returned commits to those whose log message contains all of the provided matches (regular expressions)
func WithPaths ¶
WithPaths allows the log history to be retrieved for any number of files and folders within the current repository (working directory). Only commits that have had a direct impact on those files and folders will be retrieved. Paths to files and folders are relative to the root of the repository. All leading and trailing whitespace will be trimmed from the file paths, allowing empty paths to be ignored.
A relative path can be resolved using [ToRelativePath].
func WithRawOnly ¶
func WithRawOnly() LogOption
WithRawOnly ensures only the raw output from the git log of the current repository (working directory) is retrieved. No post-processing is carried out, resulting in an empty [Log.Commits] slice
func WithRef ¶
WithRef provides a starting point other than HEAD (most recent commit) when retrieving the log history of the current repository (working directory). Typically a reference can be either a commit hash, branch name or tag. The output of this option will typically be a shorter, fine-tuned history. This option is mutually exclusive with WithRefRange. All leading and trailing whitespace are trimmed from the reference, allowing empty references to be ignored
func WithRefRange ¶
WithRefRange provides both a start and end point when retrieving a focused snapshot of the log history from the current repository (working directory). Typically a reference can be either a commit hash, branch name or tag. The output of this option will be a shorter, fine-tuned history, for example, the history between two tags. This option is mutually exclusive with WithRef. All leading and trailing whitespace are trimmed from the references, allowing empty references to be ignored
func WithSkip ¶ added in v0.2.0
WithSkip skips any number of most recent commits from within the log history. A positive number (greater than zero) is expected. Skipping more commits than exists, will result in no history being retrieved. Skipping zero commits, will retrieve the entire log. This option has a higher order of precedence than git.WithTake
func WithTake ¶ added in v0.2.0
WithTake limits the number of commits that will be output within the log history. A positive number (greater than zero) is expected. Taking more commits than exists, has the same effect as retrieving the entire log. Taking zero commits, will retrieve an empty log. This option has a lower order of precedence than git.WithSkip
type Person ¶ added in v0.6.0
type Person struct { // Name of the person Name string // Email address associated with the person Email string }
Person represents a human that has performed an interaction against a repository
type PullOption ¶ added in v0.6.0
type PullOption func(*pullOptions)
PullOption provides a way for setting specific options while pulling changes from the remote. Each supported option can customize how changes are pulled from the remote and integrated into the current repository (working directory)
func WithFetchAll ¶ added in v0.7.0
func WithFetchAll() PullOption
WithFetchAll will fetch the latest changes from all tracked remotes
func WithFetchDepthTo ¶ added in v0.7.0
func WithFetchDepthTo(depth int) PullOption
WithFetchDepthTo will limit the number of commits to be fetched from the remotes history. If fetching into a shallow clone of a repository, this can be used to shorten or deepen the existing history
func WithFetchForce ¶ added in v0.7.0
func WithFetchForce() PullOption
WithFetchForce will force the fetching of a remote branch into a local branch with a different name (or refspec). Default behavior within git prevents such an operation. Typically used in conjunction with the WithFetchRefSpecs option
func WithFetchIgnoreTags ¶ added in v0.7.0
func WithFetchIgnoreTags() PullOption
WithFetchIgnoreTags disables local tracking of tags from the remote
func WithFetchTags ¶ added in v0.7.0
func WithFetchTags() PullOption
WithFetchTags will fetch all tags from the remote into local tag references with the same name
func WithPullConfig ¶ added in v0.6.0
func WithPullConfig(kv ...string) PullOption
WithPullConfig allows temporary git config to be set while pulling changes from the remote. Config set using this approach will override any config defined within existing git config files. Config must be provided as key value pairs, mismatched config will result in an ErrMissingConfigValue error. Any invalid paths will result in an ErrInvalidConfigPath error
func WithPullRefSpecs ¶ added in v0.7.0
func WithPullRefSpecs(refs ...string) PullOption
WithPullRefSpecs allows remote references to be cherry-picked and fetched into the current repository (working copy) during a pull. A reference (or refspec) can be as simple as a name, where git will automatically resolve any ambiguity, or as explicit as providing a source and destination for reference within the remote. Check out the official git documentation on how to write a more complex [refspec] [refspec]: https://git-scm.com/docs/git-pull#Documentation/git-pull.txt-ltrefspecgt
type PushOption ¶ added in v0.3.0
type PushOption func(*pushOptions)
PushOption provides a way of setting specific options during a git push operation. Each supported option can customize the way in which references are pushed back to the remote
func WithAllBranches ¶ added in v0.3.0
func WithAllBranches() PushOption
WithAllBranches will push all locally created branch references back to the remote
func WithAllTags ¶ added in v0.3.0
func WithAllTags() PushOption
WithAllTags will push all locally created tag references back to the remote
func WithDeleteRefSpecs ¶ added in v0.6.0
func WithDeleteRefSpecs(refs ...string) PushOption
WithDeleteRefSpecs will trigger the deletion of any named references when pushed back to the remote
func WithPushConfig ¶ added in v0.6.0
func WithPushConfig(kv ...string) PushOption
WithPushConfig allows temporary git config to be set while pushing changes to the remote. Config set using this approach will override any config defined within existing git config files. Config must be provided as key value pairs, mismatched config will result in an ErrMissingConfigValue error. Any invalid paths will result in an ErrInvalidConfigPath error
func WithPushOptions ¶ added in v0.5.0
func WithPushOptions(options ...string) PushOption
WithPushOptions allows any number of aribitrary strings to be pushed to the remote server. All options are transmitted in their received order. A server must have the git config setting receive.advertisePushOptions set to true to receive push options
func WithRefSpecs ¶ added in v0.3.0
func WithRefSpecs(refs ...string) PushOption
WithRefSpecs allows local references to be cherry-picked and pushed back to the remote. A reference (or refspec) can be as simple as a name, where git will automatically resolve any ambiguity, or as explicit as providing a source and destination for each local reference within the remote. Check out the official git documentation on how to write a more complex refspec
type Repository ¶ added in v0.2.0
type Repository struct { // DetachedHead is true if the current repository HEAD points to a // specific commit, rather than a branch DetachedHead bool // DefaultBranch is the initial branch that is checked out when // a repository is cloned DefaultBranch string // Origin contains the URL of the remote which this repository // was cloned from Origin string // Remotes will contain all of the remotes and their URLs as // configured for this repository Remotes map[string]string // RootDir contains the path to the cloned directory RootDir string // ShallowClone is true if the current repository has been cloned // to a specified depth without the entire commit history ShallowClone bool }
Repository provides a snapshot of the current state of a repository (working directory)
type Signature ¶ added in v0.6.0
type Signature struct { // Fingerprint contains the fingerprint of the private key used // during key verification Fingerprint string // Author represents the person associated with the private key Author *Person }
Signature contains details about a GPG signature
type SortKey ¶ added in v0.3.0
type SortKey string
SortKey represents a structured field name that can be used as a sort key when analysing referenced objects such as tags
const ( // CreatorDate sorts the reference in ascending order by the creation date // of the underlying commit CreatorDate SortKey = "creatordate" // CreatorDateDesc sorts the reference in descending order by the creation date // of the underlying commit CreatorDateDesc SortKey = "-creatordate" // RefName sorts the reference by its name in ascending lexicographic order RefName SortKey = "refname" // RefNameDesc sorts the reference by its name in descending lexicographic order RefNameDesc SortKey = "-refname" // TaggerDate sorts the reference in ascending order by its tag creation date TaggerDate SortKey = "taggerdate" // TaggerDateDesc sorts the reference in descending order by its tag // creation date TaggerDateDesc SortKey = "-taggerdate" // Version interpolates the references as a version number and sorts in // ascending order Version SortKey = "version:refname" // VersionDesc interpolates the references as a version number and sorts in // descending order VersionDesc SortKey = "-version:refname" )
type StageOption ¶ added in v0.2.0
type StageOption func(*stageOptions)
StageOption provides a way for setting specific options during a stage operation. Each supported option can customize the way files are staged within the current repository (working directory)
func WithPathSpecs ¶ added in v0.2.0
func WithPathSpecs(specs ...string) StageOption
WithPathSpecs permits a series of PathSpecs (or globs) to be defined that will stage any matching files within the current repository (working directory). Paths to files and folders are relative to the root of the repository. All leading and trailing whitespace will be trimmed from the file paths, allowing empty paths to be ignored
type StatusOption ¶ added in v0.9.0
type StatusOption func(*statusOptions)
StatusOption provides a way for setting specific options during a porcelain status operation. Each support option can customize the list of file statuses identified within the current repository (working directory)
func WithIgnoreRenames ¶ added in v0.9.0
func WithIgnoreRenames() StatusOption
WithIgnoreRenames will turn off rename detection, removing any renamed files or directories from the retrieved file statuses
func WithIgnoreUntracked ¶ added in v0.9.0
func WithIgnoreUntracked() StatusOption
WithIgnoreUntracked will remove any untracked files from the retrieved file statuses
type TagAnnotation ¶ added in v0.6.0
type TagAnnotation struct { // Tagger represents a person who created the tag Tagger Person // TaggerDate contains the date and time of when the tagger created // the tag within the repository TaggerDate time.Time // Message contains the annotated message associated with the tag Message string }
TagAnnotation contains details about an annotation associated with a tag within a repository
type TagDetails ¶ added in v0.6.0
type TagDetails struct { // Annotation contains optional details about the annotation associated // with the tag Annotation *TagAnnotation // Commit contains details about the associated commit Commit CommitDetails // Ref contains the unique identifier associated with the tag Ref string }
TagDetails contains details about a specific tag within a repository
type TagFilter ¶ added in v0.4.0
TagFilter allows a tag to be filtered based on any user-defined criteria. If the filter returns true, the tag will be included within the filtered results:
componentFilter := func(tag string) bool { return strings.HasPrefix(tag, "component/") }
type TagVerification ¶ added in v0.5.0
type TagVerification struct { // Annotation contains the annotated message associated with // the tag Annotation string // Ref contains the unique identifier associated with the tag Ref string // Signature contains details of the verified GPG signature Signature *Signature // Tagger represents a person who created the tag Tagger Person }
TagVerification contains details about a GPG signed tag
type TreeDetails ¶ added in v0.6.0
type TreeDetails struct { // Entries contains the file and directory listing within a tree Entries []string // Ref contains the unique identifier associated with the tree Ref string }
TreeDetails contains details about a specifc tree within a repository