git

Documentation

Index

• func Add(repoPath string, files []string) error
• func CheckoutBranch(repoPath, branch string) error
• func Clone(ctx context.Context, url, targetDir, branch string, depth int) (string, error)
• func CloneDir(repoPath, branch string) string
• func CloneLocal(repoPath, targetDir, branch string) error
• func Commit(repoPath, message string) error
• func CreateBranch(repoPath, name, base string) error
• func CreateTrackingBranch(repoPath, localName, remoteBranch string) error
• func CreateWorktree(repoPath, branch, targetDir string) error
• func CurrentBranch(repoPath string) (string, error)
• func DeleteBranch(repoPath, branch string) error
• func DetectMainBranch(repoPath string) (string, error)
• func Fetch(repoPath, remote string) error
• func FetchAll(repoPath string) error
• func IsGitRepo(path string) bool
• func IsPathIgnored(repoPath, path string) bool
• func LastCommitHash(repoPath string) (string, error)
• func Merge(repoPath, branch string) error
• func PullFromBranch(repoPath, remote, branch string) error
• func PullMain(repoPath string) error
• func PushBranch(repoPath, remote, branch string) error
• func RemoveClone(clonePath string) error
• func RemoveWorktree(repoPath, worktreePath string) error
• func SanitizeBranchName(name string) string
• func SanitizeBranchNameWithPrefix(name, prefix string) string
• func ShowFile(repoPath, ref, filePath string) (string, bool, error)
• func WorktreeDir(repoPath, branch string) string
• type Branch
  • func ListBranches(repoPath string) ([]Branch, error)
• type DiffEntry
  • func DiffNameStatus(repoPath, base, head string) ([]DiffEntry, error)
• type DiffStatResult
  • func DiffStat(repoPath, base, head string) (DiffStatResult, error)
• type FileStatus
  • func Status(repoPath string) ([]FileStatus, error)
  • func StatusForPath(repoPath, subPath string) ([]FileStatus, error)
• type RemoteInfo
  • func ListRemotes(repoPath string) ([]RemoteInfo, error)
• type Worktree
  • func ListWorktrees(repoPath string) ([]Worktree, error)

Functions

func Add

func Add(repoPath string, files []string) error

Add stages the specified files in the repo at repoPath.

func CheckoutBranch

func CheckoutBranch(repoPath, branch string) error

CheckoutBranch switches the repository at repoPath to the specified branch.

func Clone

func Clone(ctx context.Context, url, targetDir, branch string, depth int) (string, error)

Clone clones a git repository from url into targetDir. It supports optional branch and depth (shallow clone) parameters. Returns the combined stdout/stderr output and any error.

func CloneDir

func CloneDir(repoPath, branch string) string

CloneDir returns the conventional directory for a branch clone given the project repo path and branch name. The convention is:

{parent}/{project}-branches/{branch}/

For example, if repoPath is /home/user/projects/myapp and branch is "hotfix/login-fix", the clone directory will be /home/user/projects/myapp-branches/hotfix/login-fix/

func CloneLocal

func CloneLocal(repoPath, targetDir, branch string) error

CloneLocal creates a local clone of repoPath into targetDir with the specified branch checked out. After cloning, it updates the clone's origin remote URL to match the original repo's origin so that push/pull operations target the real remote rather than the local path.

func Commit

func Commit(repoPath, message string) error

Commit creates a commit in the repo at repoPath with the given message. Only already-staged changes are committed.

func CreateBranch

func CreateBranch(repoPath, name, base string) error

CreateBranch creates a new branch at repoPath based on the given base branch and switches to it. Equivalent to `git checkout -b <name> <base>`.

func CreateTrackingBranch

func CreateTrackingBranch(repoPath, localName, remoteBranch string) error

CreateTrackingBranch creates a local branch that tracks a remote branch. Equivalent to `git checkout -b <localName> --track <remoteBranch>`.

func CreateWorktree

func CreateWorktree(repoPath, branch, targetDir string) error

CreateWorktree creates a new git worktree for the given branch. If targetDir is empty, the conventional directory layout is used. The branch must already exist (local or remote).

func CurrentBranch

func CurrentBranch(repoPath string) (string, error)

CurrentBranch returns the name of the currently checked-out branch in the repository at repoPath. Returns an error if the command fails or the repo is in a detached HEAD state with no branch name.

func DeleteBranch

func DeleteBranch(repoPath, branch string) error

DeleteBranch safely deletes a local branch. Uses -d (not -D) so git will refuse if the branch has unmerged commits.

func DetectMainBranch

func DetectMainBranch(repoPath string) (string, error)

DetectMainBranch returns the name of the main integration branch (either "main" or "master") by checking which exists locally.

func Fetch

func Fetch(repoPath, remote string) error

Fetch runs `git fetch <remote>` in the given repo.

func FetchAll

func FetchAll(repoPath string) error

FetchAll runs `git fetch --all --prune` in the given repo.

func IsGitRepo

func IsGitRepo(path string) bool

IsGitRepo checks whether the given path contains a git repository by looking for a .git directory or file (worktrees use a .git file).

func IsPathIgnored

func IsPathIgnored(repoPath, path string) bool

IsPathIgnored checks whether the given path is ignored by git (e.g. listed in .gitignore). Returns true if the path is ignored.

func LastCommitHash

func LastCommitHash(repoPath string) (string, error)

LastCommitHash returns the short hash of the most recent commit in the repository at repoPath.

func Merge

func Merge(repoPath, branch string) error

Merge merges the given branch into the currently checked-out branch in repoPath. If a conflict occurs, the merge is aborted and an error is returned.

func PullFromBranch

func PullFromBranch(repoPath, remote, branch string) error

PullFromBranch fetches the given remote and merges remote/branch into the currently checked-out branch. If a conflict occurs, the merge is aborted and an error is returned.

func PullMain

func PullMain(repoPath string) error

PullMain fetches origin and merges the remote main branch into the currently checked-out branch. If a conflict occurs, the merge is aborted and an error is returned.

Deprecated: Use PullFromBranch for explicit remote/branch control.

func PushBranch

func PushBranch(repoPath, remote, branch string) error

PushBranch pushes a local branch to the given remote.

func RemoveClone

func RemoveClone(clonePath string) error

RemoveClone deletes a cloned repository directory and all its contents.

func RemoveWorktree

func RemoveWorktree(repoPath, worktreePath string) error

RemoveWorktree removes a worktree by its path. It uses --force to handle worktrees with modified or untracked files.

func SanitizeBranchName

func SanitizeBranchName(name string) string

SanitizeBranchName converts a human-readable feature name into a valid git branch name prefixed with "feature/". For example:

"Add OAuth2 Support" → "feature/add-oauth2-support"

func SanitizeBranchNameWithPrefix

func SanitizeBranchNameWithPrefix(name, prefix string) string

SanitizeBranchNameWithPrefix converts a human-readable name into a valid git branch name using the given prefix. If prefix is empty, no prefix is applied. Examples:

("login fix", "hotfix") → "hotfix/login-fix"
("login fix", "")       → "login-fix"

func ShowFile

func ShowFile(repoPath, ref, filePath string) (string, bool, error)

ShowFile returns the content of a file at a specific ref. Returns ("", false, nil) if the file doesn't exist at that ref. Returns (content, true, nil) for binary files.

func WorktreeDir

func WorktreeDir(repoPath, branch string) string

WorktreeDir returns the conventional directory for a worktree given the project repo path and branch name. The convention is:

{parent}/{project}-worktrees/{branch}/

For example, if repoPath is /home/user/projects/myapp and branch is "feature/auth", the worktree directory will be /home/user/projects/myapp-worktrees/feature/auth/

Types

type Branch

type Branch struct {
	Name      string `json:"name"`
	IsCurrent bool   `json:"is_current"`
	IsRemote  bool   `json:"is_remote"`
	Remote    string `json:"remote,omitempty"`
}

Branch represents a git branch (local or remote).

func ListBranches

func ListBranches(repoPath string) ([]Branch, error)

ListBranches returns all local and remote branches for the repository at repoPath by running `git branch -a`.

type DiffEntry

type DiffEntry struct {
	Status  string `json:"status"` // M, A, D, R, C
	Path    string `json:"path"`
	OldPath string `json:"old_path,omitempty"` // for renames
}

DiffEntry represents a changed file between two refs.

func DiffNameStatus

func DiffNameStatus(repoPath, base, head string) ([]DiffEntry, error)

DiffNameStatus returns the list of changed files between two refs using git diff --name-status base...head.

type DiffStatResult

type DiffStatResult struct {
	FilesChanged int `json:"files_changed"`
	Insertions   int `json:"insertions"`
	Deletions    int `json:"deletions"`
}

DiffStatResult holds aggregate diff statistics.

func DiffStat

func DiffStat(repoPath, base, head string) (DiffStatResult, error)

DiffStat returns aggregate diff statistics between two refs.

type FileStatus

type FileStatus struct {
	Path   string `json:"path"`
	Status string `json:"status"` // M, A, D, ?, R, etc.
	Staged bool   `json:"staged"`
}

FileStatus represents a single entry from `git status --porcelain`.

func Status

func Status(repoPath string) ([]FileStatus, error)

Status returns the working tree status for the repo at repoPath by parsing the output of `git status --porcelain`.

func StatusForPath

func StatusForPath(repoPath, subPath string) ([]FileStatus, error)

StatusForPath returns the working tree status for files under subPath (relative to repoPath). Only entries whose path starts with subPath are returned. The returned FileStatus paths are relative to the repo root.

type RemoteInfo

type RemoteInfo struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

RemoteInfo holds details about a single git remote.

func ListRemotes

func ListRemotes(repoPath string) ([]RemoteInfo, error)

ListRemotes returns all configured remotes for the repo at repoPath by parsing `git remote -v` output.

type Worktree

type Worktree struct {
	Path   string `json:"path"`
	Branch string `json:"branch"`
	HEAD   string `json:"head"`
	IsMain bool   `json:"is_main"`
}

Worktree represents a git worktree entry parsed from `git worktree list --porcelain`.

func ListWorktrees

func ListWorktrees(repoPath string) ([]Worktree, error)

ListWorktrees returns all worktrees for the repository at repoPath by parsing the porcelain output of `git worktree list --porcelain`.

Porcelain format per worktree block:

worktree /absolute/path
HEAD <sha>
branch refs/heads/<name>
<blank line>

The first worktree listed is always the main working tree.