Documentation
¶
Index ¶
- Variables
- func Ahead(ctx context.Context, r Repo) (n int, ok bool, err error)
- func BranchAhead(ctx context.Context, r Repo, branch, head string) (tip string, ahead int, err error)
- func DefaultBranch(ctx context.Context, r Repo) (string, error)
- func DeleteBranch(ctx context.Context, r Repo, branch, tip string) error
- func DeletePRRefs(ctx context.Context, r Repo, number int) error
- func HasUpstream(ctx context.Context, r Repo, branch string) (bool, error)
- func HunkID(path string, h Hunk) string
- func ManagedWorktree(r Repo, path string) bool
- func MarkdownFiles(ctx context.Context, root string) ([]string, error)
- func PruneSession(ctx context.Context, r Repo, session string) (int, error)
- func PruneWorktree(ctx context.Context, r Repo, worktree string) (int, error)
- func PushRemote(ctx context.Context, r Repo, branch string) (string, error)
- func PushURLs(ctx context.Context, r Repo, remote string) ([]string, error)
- func RemoteBranches(ctx context.Context, r Repo, remote string) ([]string, error)
- func RemoteHasBranch(ctx context.Context, r Repo, remote, branch string) (bool, error)
- func RemoteURL(ctx context.Context, r Repo, remote string) (string, error)
- func RemoveWorktree(ctx context.Context, r Repo, path string) error
- func Unpushed(ctx context.Context, r Repo, remote string) (int, error)
- func WorktreeChanges(ctx context.Context, dir string) (int, error)
- func WorktreeDir(branch string) (string, error)
- func WorktreePath(r Repo, style RootStyle, branch string) (string, error)
- type Batch
- type BranchSource
- type Commit
- type Created
- type Engine
- func (e *Engine) Diff(ctx context.Context, src Source) (Result, error)
- func (e *Engine) FileText(ctx context.Context, worktree string, f FileDiff) (old, nw []string, err error)
- func (e *Engine) Stats(ctx context.Context, src Source) (Stats, error)
- func (e *Engine) TurnList(ctx context.Context, worktree, session string) (TurnList, error)
- func (e *Engine) TurnListAt(ctx context.Context, worktree, session, workingTree string) (TurnList, error)
- func (e *Engine) Update(ctx context.Context, prev Result, src Source, b Batch) (Result, error)
- type EngineOptions
- type FileDiff
- type HeadInfo
- type Hunk
- type Limits
- type Line
- type LineKind
- type NewWorktree
- type OpenTurn
- type PRRefs
- type PRSource
- type Place
- type PlaceCache
- type PushResult
- type Repo
- type Result
- type RootBatch
- type RootStyle
- type SnapshotOptions
- type Source
- type Stats
- type Status
- type Tool
- type TreeOptions
- type Turn
- func EndTurn(ctx context.Context, dir, session string, n int, opts SnapshotOptions) (Turn, error)
- func MarkMissing(ctx context.Context, dir, session string, n int, end bool) (Turn, error)
- func Snapshot(ctx context.Context, dir, session string, opts SnapshotOptions) (Turn, error)
- func Turns(ctx context.Context, r Repo, session string) ([]Turn, error)
- type TurnList
- type TurnSource
- type WatchOptions
- type WatchSet
- type Watcher
- type WorkTree
- type Worktree
Constants ¶
This section is empty.
Variables ¶
var ( // ErrWorktreeDirty means git refused to remove a worktree with modified or untracked files. ErrWorktreeDirty = errors.New("git: worktree has uncommitted changes") // ErrNoCommit means the commit is not in this repository. ErrNoCommit = errors.New("git: commit not in this repository") // ErrBranchMoved means the branch tip is not the one the caller saw. ErrBranchMoved = errors.New("git: branch moved") )
var ( // ErrNoSnapshot means the requested turn has no snapshot. ErrNoSnapshot = errors.New("git: turn has no snapshot") // ErrNoTurns means the session has no recorded turns. ErrNoTurns = errors.New("git: session has no turns") // ErrNotFetched means the pull request refs are not in the repository. ErrNotFetched = errors.New("git: pull request refs not fetched") // ErrTooLarge means a file is too large to read whole. ErrTooLarge = errors.New("git: file too large") )
var ( // ErrNotRepo means the directory is not inside a git work tree. ErrNotRepo = errors.New("git: not inside a work tree") // ErrBare means the repository has no main checkout. ErrBare = errors.New("git: bare repository") )
var ( // ErrExists means the worktree path is already taken. ErrExists = errors.New("git: worktree path exists") // ErrBadBranch means the branch name is not usable as a branch or a directory. ErrBadBranch = errors.New("git: invalid branch name") // ErrNoBase means there is no usable base branch. ErrNoBase = errors.New("git: no base branch") )
var ErrBadSession = errors.New("git: session id is not a UUID")
ErrBadSession means a session id is not a UUID.
var ErrNoPR = errors.New("git: no such pull request on the remote")
ErrNoPR means the remote has no such pull request.
var ErrNoRemote = errors.New("git: no such remote")
ErrNoRemote means the named remote is not configured.
var ErrNotCounted = errors.New("git: the edit does not count")
ErrNotCounted means a file edit does not belong to any worktree's changes: the path is not absolute, lies in a git dir, outside any work tree, or is ignored.
var ErrRejected = errors.New("git: push rejected")
ErrRejected means the remote refused the push, e.g. a non-fast-forward.
var ErrTurnNotOpen = errors.New("git: the turn is not open in this worktree")
ErrTurnNotOpen means the turn to end has no start in this worktree, or has an end already.
var ErrWatchSetClosed = errors.New("watch set closed")
ErrWatchSetClosed is returned by Acquire after Close.
Functions ¶
func Ahead ¶
Ahead counts the commits HEAD has that its upstream lacks. ok is false when there is nothing to compare with: a detached HEAD, an unborn branch, no upstream, or an upstream ref that is gone.
func BranchAhead ¶
func BranchAhead(ctx context.Context, r Repo, branch, head string) (tip string, ahead int, err error)
BranchAhead returns the tip of branch and how many commits it has that head does not. A tip equal to head needs no object; a head that is not a commit here is ErrNoCommit.
func DefaultBranch ¶
DefaultBranch returns the start point for new branches: origin/<name> when origin/HEAD points at an existing branch, else main, else master.
func DeleteBranch ¶
DeleteBranch deletes branch with `branch -D` when its tip is still tip. The caller has already checked the branch is merged; git still refuses a branch checked out in any worktree.
func DeletePRRefs ¶
DeletePRRefs removes the refs FetchPR wrote in one transaction. Missing refs are not an error.
func HasUpstream ¶
HasUpstream reports whether branch has an upstream configured, whether or not its remote-tracking ref exists. Push sets an upstream exactly when this is false.
func HunkID ¶
HunkID identifies a hunk by its path and its changed lines, so it survives moved line numbers, other context and a renamed old path.
func ManagedWorktree ¶
ManagedWorktree reports whether path sits directly under one of the repository's worktree roots, inside or sibling, with symlinks resolved. The main checkout is not one, and neither is a path whose parent is missing.
func MarkdownFiles ¶
MarkdownFiles lists the markdown files under root as sorted, slash-separated paths relative to root, whether git tracks, ignores or has never seen them. It skips .git, node_modules, vendor and every folder below root that holds a .git entry (a nested checkout or worktree), and does not follow symlinked folders. At the cap the walk stops: the files found so far (the first in walk order) come back, sorted, without an error. So do the files found when ctx's deadline passes mid-walk. An unreadable folder below root is skipped; an unreadable root, a cancelled ctx and a deadline before any file are errors.
func PruneSession ¶
PruneSession deletes every turn ref of the session, in both layouts, and returns how many.
func PruneWorktree ¶
PruneWorktree deletes every turn ref of worktree, in both layouts, and returns how many it removed. worktree is a worktree root as Repo.Root gives it, the form the commits record; a symlinked spelling does not match.
func PushRemote ¶
PushRemote names the remote a push of branch goes to: branch.<b>.pushRemote, else remote.pushDefault, else branch.<b>.remote (unless "."), else origin. It must be a configured remote.
func PushURLs ¶
PushURLs returns every URL a push to remote goes to, one per pushurl, with url.<base>.pushInsteadOf and insteadOf applied. Without a pushurl it is the fetch URL. The URLs may carry credentials, so never put them in an error or log.
func RemoteBranches ¶
RemoteBranches returns the names of the remote-tracking branches of remote, without the remote's name and without HEAD, sorted. A remote with no tracking refs, or one that is not configured, has none.
func RemoteHasBranch ¶
RemoteHasBranch reports whether the remote-tracking ref of branch on remote exists, which says nothing about the remote itself until a fetch or push.
func RemoteURL ¶
RemoteURL returns the URL git would use for remote, with url.<base>.insteadOf applied. The URL may carry credentials, so never put it in an error or log.
func RemoveWorktree ¶
RemoveWorktree runs `git worktree remove` for path from the main checkout (the common dir for a bare repository). It is never forced, so git refuses a worktree with changes (ErrWorktreeDirty) or a locked one.
func Unpushed ¶
Unpushed counts the commits of HEAD that no remote-tracking branch of remote has, which is every commit before a first push.
func WorktreeChanges ¶
WorktreeChanges counts the entries `git status` reports in dir: modified, staged and untracked paths, a rename or copy once.
func WorktreeDir ¶
WorktreeDir turns a branch name into a directory name.
func WorktreePath ¶
WorktreePath is where CreateWorktree puts a worktree for branch under the root of style. It reads nothing from the disk, so a page can preview it on every frame. It fails with ErrBadBranch when the name has no directory form and with ErrBare when the inside root has no main checkout.
Types ¶
type Batch ¶
type Batch struct {
// Paths are touched paths relative to the worktree root, sorted,
// deduplicated, never ignored. A removed directory appears as its own path
// and its children may be absent: treat a vanished path as a prefix. Files a
// .gitignore change un-ignores are listed only in newly watched
// directories: treat a touched .gitignore as "everything may have changed".
Paths []string
Git bool // HEAD, the index, packed-refs or a ref outside refs/aim changed
Overflow bool // events were lost; treat everything as changed
}
Batch is one debounced set of changes in a worktree.
type BranchSource ¶
type BranchSource struct{ Worktree, Base string }
BranchSource compares the merge base of Base and HEAD with the working tree. An empty Base means the default branch.
type Commit ¶
type Commit struct{ OID, Subject, Body string }
Commit is one entry of a branch's history.
func HeadCommit ¶
HeadCommit returns the commit HEAD points at, with its subject (the body is left empty). An unborn branch is an error.
type Created ¶
type Created struct {
Worktree Worktree
Excluded bool // this call added /.worktrees/ to info/exclude
Tools []Tool // tools that need their own ignore entry (RootInside only)
}
Created is the result of CreateWorktree.
func CreateWorktree ¶
CreateWorktree adds a worktree for nw.Branch under the chosen root, creating the branch from the base unless it exists (then the base is ignored). A non-empty Worktree.Path in the result means the worktree exists, even when the error is not nil.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine turns sources into structured diffs. It is safe for concurrent use.
func NewEngine ¶
func NewEngine(o EngineOptions) *Engine
NewEngine returns an engine for the given options.
func (*Engine) FileText ¶
func (e *Engine) FileText(ctx context.Context, worktree string, f FileDiff) (old, nw []string, err error)
FileText returns the lines of both sides of f, read from the object database. An empty id gives an empty side. A side over 8 MiB gives ErrTooLarge.
func (*Engine) Stats ¶
Stats totals the diff of src with the listing pass only: no hunks, and no cache. Only branch sources are supported.
func (*Engine) TurnList ¶
TurnList lists the session's turns in worktree that changed it: a closed turn whose end differs from its start, any turn with a marker, an open turn that is no longer current, and the open current turn while the working tree differs from its start.
func (*Engine) TurnListAt ¶
func (e *Engine) TurnListAt(ctx context.Context, worktree, session, workingTree string) (TurnList, error)
TurnListAt is TurnList for a caller that already has the worktree's current tree id, such as the New side of a live branch diff: the open current turn is compared with it instead of a fresh working-tree snapshot.
func (*Engine) Update ¶
Update brings prev, the result of Diff for src, up to date after the watcher batch b. It rebuilds the working tree and re-lists only the touched paths; the result equals a fresh Diff. Anything that could change which files pair up, the old side, or which files fall inside the caps runs a full Diff. The Repo opened for a worktree is reused until its git dirs move or an update fails; an update whose context ended keeps it.
type EngineOptions ¶
type EngineOptions struct {
Limits Limits // zero fields take the defaults
TempDir string // where working-tree snapshots keep their temporary index
IndexCache string // keeps a refreshed index copy per worktree; empty = none
}
EngineOptions configure NewEngine.
type FileDiff ¶
type FileDiff struct {
Path, OldPath string
Status Status
OldOID, NewOID string // full ids; "" on the side a file does not exist
OldMode, NewMode string
Binary, Untracked, Truncated bool
Added, Removed int
Hunks []Hunk
}
FileDiff is one changed file. OldPath is set for renames and copies only. Untracked marks a file whose path git does not track and the old side lacks, also when git paired it with another file as a rename or copy. Hunks stay empty for binary files, files without line changes and files marked Truncated; cached hunks are shared, so treat them as read-only.
type HeadInfo ¶
type HeadInfo struct {
Branch string // without refs/heads/
Detached bool
OID string // full commit id
}
HeadInfo is what a worktree's HEAD points at. A detached HEAD has an empty Branch; an unborn branch has an empty OID.
type Limits ¶
type Limits struct{ Files, Bytes, Lines int }
Limits bound the work and memory of one diff.
func DefaultLimits ¶
func DefaultLimits() Limits
DefaultLimits returns 400 files with hunks, 2 MiB of diff text and 5000 changed lines per file.
type Line ¶
type Line struct {
Kind LineKind
Old, New int // line numbers; 0 on the side the line is not on
Text string
NoNewline bool
}
Line is one line of a hunk.
type NewWorktree ¶
type NewWorktree struct {
Branch string
Base string // "" = the default branch; ignored when Branch already exists
Root RootStyle
}
NewWorktree describes a worktree to create.
type PRRefs ¶
type PRRefs struct{ Head, Base string }
PRRefs are the commits FetchPR stored: the pull request's head and the tip of its base branch.
type PRSource ¶
PRSource compares the merge base of a pull request's base and head, as FetchPR stored them, with its head.
type Place ¶
type Place struct {
Root string // the worktree's top level
Common string // the repository's common dir, shared by its worktrees
Repo string // the repository's name, Repo.Name
}
Place is the worktree holding a file an agent edited.
func EditPlace ¶
EditPlace finds the worktree an edited file belongs to. The file need not exist yet: the nearest existing directory above it decides, with symlinks resolved, since git reports real paths. It fails with ErrNotCounted for a path that is not absolute, has a ".git" component, is outside any work tree or is ignored by that worktree's own rules.
type PlaceCache ¶
type PlaceCache struct {
// contains filtered or unexported fields
}
PlaceCache answers EditPlace for many callers: it keeps counted places and ErrNotCounted answers for a minute, and makes lookups of one path in flight share one resolution. Its zero value is not usable; make one with NewPlaceCache.
func NewPlaceCache ¶
func NewPlaceCache(resolve func(context.Context, string) (Place, error), now func() time.Time) *PlaceCache
NewPlaceCache makes a cache over resolve, normally EditPlace, whose entries age by now.
type PushResult ¶
type PushResult struct {
Remote, Branch string
Dst string // the remote ref pushed to
Created bool // the remote branch is new
UpToDate bool
SetUpstream bool
}
PushResult reports what one push did.
type Repo ¶
type Repo struct {
Root string // the worktree's top level, absolute
GitDir string // this worktree's git dir, absolute
CommonDir string // the repository's common dir, absolute
}
Repo locates one worktree and the repository it belongs to.
type Result ¶
type Result struct {
Old, New string // tree ids
Live bool // New is the working tree
Turn int // turn sources: the position shown in the worktree's list
Turns int // turn sources: how many turns the worktree's list held
Head string // PR sources: the head commit shown; a merge passes it
Files []FileDiff
Truncated bool
}
Result is a diff between two trees.
type RootBatch ¶
RootBatch is one watcher batch, or the report of a watch that failed to start (Err set), tagged with the worktree root it belongs to.
type SnapshotOptions ¶
type SnapshotOptions struct {
TempDir string // where the temporary index is created
IndexCache string // keeps a refreshed index copy per worktree; empty = none
MaxUntracked int64 // bytes; 0 = 50 MiB, negative = no cap
Unchanged bool // reuse the worktree's latest tree in the session without staging
Turn int // the turn's number; 0 takes one more than the session's highest in the repository
Ends int // a turn of this worktree to end with the same tree when it is open; 0 for none
}
SnapshotOptions tune one snapshot.
type Source ¶
type Source interface {
// contains filtered or unexported methods
}
Source selects what Engine.Diff compares.
type Stats ¶
type Stats struct{ Files, Added, Removed int }
Stats totals a diff: the changed files and their added and removed lines. Binary files count as files without lines.
type Tool ¶
type Tool struct {
Name string
Path string // the file or directory that triggered it, relative to the root
Hint string // what to add
}
Tool is a development tool in the main checkout that would pick up files under .worktrees/ unless it gets its own ignore entry.
func DetectTools ¶
DetectTools reads files in root, never runs anything, and lists the tools that need an ignore entry for .worktrees. JSON that does not parse counts as needing an entry. A check that fails to read is skipped and joined into the error, so the tools found are still returned.
type TreeOptions ¶
type TreeOptions struct {
TempDir string // where the temporary index is created
IndexCache string // keeps a refreshed index copy per worktree; empty = none
MaxUntracked int64 // bytes; 0 = 50 MiB, negative = no cap
}
TreeOptions tune WorkingTree.
type Turn ¶
type Turn struct {
N int
Commit string // the start
Tree string
Missing bool // the start is a "no snapshot" marker
EndCommit string // "" while the turn is open
EndTree string
EndMissing bool // the end is a marker
Current bool // N is the session's highest turn number in the repository
Skipped []string
Time time.Time // the start's committer time
}
Turn is one turn of a session in one worktree.
func EndTurn ¶
EndTurn records the working tree as the end of turn n of the worktree containing dir. A turn with no start there, a start marker or an end is ErrTurnNotOpen.
func MarkMissing ¶
MarkMissing records that a turn has no snapshot: a commit of the empty tree with the trailer "Snapshot: none". As a start it is turn n (0 for the next), so later turns keep their numbers; as an end (end true) it closes the open turn n.
type TurnList ¶
type TurnList struct {
Turns []Turn
Live bool // the last is the open current turn and differs from the working tree
}
TurnList is the turns that changed a worktree, oldest first.
type TurnSource ¶
TurnSource compares one turn of a worktree with what followed it. Turn is a position in the worktree's TurnList: 1 the oldest, 0 the latest.
type WatchOptions ¶
type WatchOptions struct {
Debounce time.Duration // quiet time before a batch goes out; 100 ms when zero
MaxDelay time.Duration // longest an unsent change waits while events keep coming; 1 s when zero
SeqBase uint64 // Seq's starting value, so a restarted watcher never repeats one
// contains filtered or unexported fields
}
WatchOptions tunes the debounce. Zero values select the defaults.
type WatchSet ¶
type WatchSet struct {
// contains filtered or unexported fields
}
WatchSet owns one Watcher per worktree root, shared by every holder and reference-counted. Its batches arrive on one channel.
func NewWatchSet ¶
func NewWatchSet(ctx context.Context, opts WatchOptions) *WatchSet
NewWatchSet returns an empty set. Watchers use opts, except SeqBase, and stop when ctx ends or Close is called.
func (*WatchSet) Acquire ¶
Acquire holds a watcher for r.Root, starting one when none exists. The returned release is idempotent and safe to call after Close; the last release stops the watcher. On failure it returns the error and sends one RootBatch with Err set.
func (*WatchSet) Batches ¶
Batches delivers the batches of every watched root. It is closed by Close. A failed Acquire also sends a batch with Err set; that report is dropped when the channel is full, since Acquire returned the same error.
type Watcher ¶
type Watcher struct {
// contains filtered or unexported fields
}
Watcher reports debounced changes of one worktree. Directories git ignores, .git internals and the main checkout's .worktrees get no watch.
func (*Watcher) Batches ¶
Batches delivers the changes. It is closed by Close or when the context ends.
func (*Watcher) Close ¶
Close stops the watcher and waits for its goroutine. It is safe to call more than once.
func (*Watcher) Degraded ¶
Degraded reports whether the watcher has reported an error or lost events. Changes may then go unseen, so its Seq proves nothing.
type WorkTree ¶
type WorkTree struct {
Tree string // tree id of the working tree as git would stage it
Untracked []string // untracked paths that entered the tree
Skipped []string // untracked paths over the size cap, left out
}
WorkTree is a working tree written as a git tree object.
func WorkingTree ¶
WorkingTree writes the worktree's current content as a tree through a temporary copy of its index, so the real index, refs and files are only read.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fsnotify provides a cross-platform interface for file system notifications.
|
Package fsnotify provides a cross-platform interface for file system notifications. |
|
internal
Package internal contains some helpers.
|
Package internal contains some helpers. |
|
Package invisible finds the characters that draw nothing but change how text reads: format characters, variation selectors and line separators.
|
Package invisible finds the characters that draw nothing but change how text reads: format characters, variation selectors and line separators. |
|
Package linediff splits texts into lines and finds a shortest line edit script between two of them.
|
Package linediff splits texts into lines and finds a shortest line edit script between two of them. |