Documentation
¶
Index ¶
- Variables
- func AddWorktree(ctx context.Context, repo, path, branch string) error
- func AdminDir(ctx context.Context, worktreePath string) (string, error)
- func CurrentBranch(dir string) string
- func DeleteBranch(ctx context.Context, repo, branch string, force bool) error
- func ExcludeLocally(ctx context.Context, repo, pattern string) error
- func Fetch(ctx context.Context, dir string) error
- func IsRepository(dir string) bool
- func ReadRemoteURL(ctx context.Context, dir string) string
- func RemoveWorktree(ctx context.Context, repo, path string, force bool) error
- func UncommittedPaths(ctx context.Context, dir string) ([]string, error)
- func UnreachableCommits(ctx context.Context, dir string) (int, error)
- type ChangeStatus
- type ChangedFile
- type Repo
- type Status
- type WorkspaceDiff
- type Worktree
Constants ¶
This section is empty.
Variables ¶
var ErrNotARepository = errors.New("not a git repository")
ErrNotARepository reports that a path is not inside any Git working tree.
It is separated from other failures on purpose: "this is a plain directory" is an answer a caller acts on, while "git timed out" is one it must not mistake for that answer. Resolving a workspace to a Project turns on exactly that distinction — treating a transient failure as "no repository" would give a checkout a second identity and split the memory its worktrees share.
Functions ¶
func AddWorktree ¶
AddWorktree creates a worktree at path on a new branch, starting from the repository's current HEAD.
Starting from HEAD rather than a remote default is what makes the new tree match the conversation that asked for it. Uncommitted changes do not come along; reporting them is the caller's job, per docs/design/workspace-root-and-worktrees.md D6.
func AdminDir ¶
AdminDir returns the per-worktree administrative directory — the `<repo>/.git/worktrees/<name>` a linked worktree's .git file points at.
It is where per-worktree state belongs: outside the working tree, so nothing written there shows up in the user's `git status`, and removed with the worktree, so nothing outlives what it describes.
func CurrentBranch ¶
CurrentBranch returns the current branch name when dir is the root of a Git repository. Returns empty string if dir is not a repo, git is unavailable, or on error.
func DeleteBranch ¶
DeleteBranch removes a branch that no longer has a worktree. force deletes it even when it holds commits no other ref reaches.
func ExcludeLocally ¶
ExcludeLocally adds pattern to the repository's .git/info/exclude when it is not already there.
Deliberately not .gitignore: that file is the user's, tracked and reviewed, and a tool adding a line to it produces a diff nobody asked for. info/exclude is per-clone and untracked, which is exactly the scope of a local worktree directory. See docs/design/workspace-root-and-worktrees.md D1.
func Fetch ¶
Fetch updates the remote-tracking refs for dir.
This is the only function here that touches the network, and it exists so that reaching the network is something a user asks for by name. Discovery, status, and provenance must never call it.
func IsRepository ¶
IsRepository reports whether dir is the root of a checkout.
The check is for dir's own .git rather than asking Git, because `git status` inside a plain directory answers for the nearest enclosing repository. A plugins directory that happens to sit inside someone's home checkout would otherwise give every plugin that repository's commit.
func ReadRemoteURL ¶
ReadRemoteURL returns the fetch URL of dir's origin, or "" when the checkout has no remote. A plugin developed locally and never pushed is ordinary, not an error.
func RemoveWorktree ¶
RemoveWorktree deletes a worktree and its administrative directory. Git refuses a tree with changes unless force is set; the caller is expected to have decided that already.
func UncommittedPaths ¶
UncommittedPaths lists the paths Git reports as changed or untracked in dir.
Types ¶
type ChangeStatus ¶
type ChangeStatus string
const ( StatusAdded ChangeStatus = "added" StatusModified ChangeStatus = "modified" StatusDeleted ChangeStatus = "deleted" StatusRenamed ChangeStatus = "renamed" )
type ChangedFile ¶
type ChangedFile struct {
Path string `json:"path"`
OldPath string `json:"old_path,omitempty"`
Status ChangeStatus `json:"status"`
Additions int `json:"additions"`
Deletions int `json:"deletions"`
Patch string `json:"patch,omitempty"`
Binary bool `json:"binary,omitempty"`
Truncated bool `json:"truncated,omitempty"`
}
type Repo ¶
type Repo struct {
// CommonDir is the repository's common Git directory, absolute — the
// `<repo>/.git` that a primary checkout and every linked worktree share, as
// distinct from the per-worktree AdminDir below.
//
// It is the only local relation that holds exactly across one repository's
// working trees and no wider: a path is not it, because worktrees have
// several; a remote URL is not it, because clones share one and it can be
// rewritten. See docs/design/local-project-memory.md §7.2.
CommonDir string
// TopLevel is the root of the working tree the path is in, absolute. Unlike
// CommonDir it differs per worktree, which is what makes the pair useful
// together: one names the repository, the other the tree being worked in.
TopLevel string
}
Repo is what Git says about the working tree containing a path.
func Repository ¶
Repository returns the common directory and working-tree root for dir, or ErrNotARepository when dir is not inside a checkout.
Both come from one rev-parse because both are wanted at the same moments — resolving a Project, naming it — and a second process spawn on every session start buys nothing.
type Status ¶
type Status struct {
// Commit is the full hash HEAD points at, empty on an unborn branch.
Commit string
// Branch is empty when HEAD is detached.
Branch string
Detached bool
// Dirty covers tracked modifications and untracked files alike: either
// means the directory is not the commit it names.
Dirty bool
// HasUpstream reports whether the branch tracks one. Ahead and Behind
// count commits against the tracking ref as it is known locally, so they
// are only current for as long as the last fetch is.
HasUpstream bool
Ahead int
Behind int
}
Status is what local Git metadata says about a working tree.
Nothing here contacts a remote. Plugin discovery may never make a network request, and a status read that could block on the network would put that invariant one flag away from being broken.
func ReadStatus ¶
ReadStatus reads commit, branch, and dirty state in one Git invocation.
Porcelain v2 reports all three: the header lines carry the commit and branch, and any non-header line is a change. Asking separately would cost a process per fact on a path a run repeats.
type WorkspaceDiff ¶
type WorkspaceDiff struct {
Workspace string `json:"workspace"`
Files []ChangedFile `json:"files"`
Error string `json:"error,omitempty"`
}
func ReadWorkspace ¶
func ReadWorkspace(ctx context.Context, workspace string) (WorkspaceDiff, error)
type Worktree ¶
type Worktree struct {
// Path is the working tree's own directory, absolute.
Path string
// Branch is the checked-out branch without its refs/heads/ prefix, empty
// when the worktree is detached.
Branch string
// Head is the commit the worktree is on.
Head string
// Main marks the primary checkout, which Git lists first and which cannot
// be removed.
Main bool
// Locked reports Git's own `git worktree lock`, a guard against pruning.
// It is not occupancy: nothing here says whether a process is working in
// the tree. See docs/design/workspace-root-and-worktrees.md D10.
Locked bool
}
Worktree is one working tree of a repository, as Git reports it.
Source Files