worktree

Documentation

Overview

Package worktree lists the SQL files of a working directory and reports what git says about them.

It knows nothing about tview and nothing about databases: it answers "which files are here" and "which of them changed", and the caller decides what to do with the answers.

git is optional. A directory that is not a repository, or a machine with no git installed, still yields its .sql files — only the branch and the per-file markers go missing. That is the same bargain the schema cache and the query history make: a missing convenience must not cost the session.

Index

• Constants
• Variables
• type File
• type Snapshot
• type Stamp
• type Status
  • func (s Status) Describe() string
  • func (s Status) Marker() string
• type Worktree
  • func Open(path string) (*Worktree, error)
  • func (w *Worktree) Name() string
  • func (w *Worktree) Read(rel string) (string, Stamp, error)
  • func (w *Worktree) Scan(ctx context.Context) (Snapshot, error)
  • func (w *Worktree) Stat(rel string) (Stamp, error)
  • func (w *Worktree) Write(rel, text string) (Stamp, error)

Constants

const MaxFileSize = 4 << 20

MaxFileSize is the largest file that will be loaded into the editor.

A mysqldump is routinely hundreds of megabytes, and handing one to a text widget does not produce a slow interface — it produces one that never draws again. Refusing is the only outcome that leaves the user something working.

Variables

var (
	// ErrOutsideWorktree refuses a path that resolves beyond the attached
	// directory. The interface hands back whatever path it was given, and a
	// stale or crafted one must not reach a file the user never attached.
	ErrOutsideWorktree = errors.New("path is outside the worktree")

	// ErrTooLarge refuses a file that would wedge the editor.
	ErrTooLarge = errors.New("file is too large to open")
)

Types

type File

type File struct {
	// Rel is relative to the attached directory, which is what the user
	// chose and therefore what they should be shown.
	Rel string
	Abs string

	Status Status
}

File is one SQL file of the worktree.

type Snapshot

type Snapshot struct {
	// Branch is the checked-out branch, or the short commit id when HEAD is
	// detached. Empty when git had nothing to say.
	Branch   string
	Detached bool
	Dirty    bool

	// Remote is the origin URL, empty when there is no origin. It is read here
	// rather than asked for because the project a session wants to browse is
	// nearly always the one the checkout came from.
	Remote string

	Files []File

	// Truncated reports that the listing hit its cap, so the user is told
	// rather than left believing they saw everything.
	Truncated bool
}

Snapshot is one reading of the worktree: what is in it, and where git says the work stands.

It is a value rather than state on Worktree so that a rescan cannot leave the file list and the branch describing different moments.

type Stamp

type Stamp struct {
	ModTime time.Time
	Size    int64
}

Stamp identifies the version of a file that was read.

It is compared, never interpreted, so a comparable struct is the whole of what it needs to be.

type Status

type Status rune

Status is what git says about one file, reduced to a single character.

git reports two: one for the index and one for the working tree. The pane showing these has room for one, so the index status wins — a file staged as new and then edited again is still a file that does not exist on the branch yet, which is the more useful thing to know.

const (
	// StatusNone means git had nothing to say: the file is committed and
	// unchanged. It is the zero value so a file map needs no initialisation.
	StatusNone      Status = 0
	StatusModified  Status = 'M'
	StatusAdded     Status = 'A'
	StatusDeleted   Status = 'D'
	StatusRenamed   Status = 'R'
	StatusUntracked Status = '?'
	StatusConflict  Status = 'U'
)

func (Status) Describe

func (s Status) Describe() string

Describe names the status in words, for the line under the file name.

func (Status) Marker

func (s Status) Marker() string

Marker is the character shown beside the file name. Clean files get a space so the names stay in one column.

type Worktree

type Worktree struct {
	// Root is absolute, with symlinks resolved, so containment checks compare
	// like with like.
	Root string
	// contains filtered or unexported fields
}

Worktree is an attached directory.

func Open

func Open(path string) (*Worktree, error)

Open attaches a directory, resolving and checking it before anything else depends on it.

git is not consulted here — that happens on Scan, so attaching stays instant even on a repository large enough that a status takes a moment.

func (*Worktree) Name

func (w *Worktree) Name() string

Name is the worktree's last path element, which is what identifies it on a status bar too narrow for the whole path.

func (*Worktree) Read

func (w *Worktree) Read(rel string) (string, Stamp, error)

Read loads a file's text along with the stamp identifying the version read.

func (*Worktree) Scan

func (w *Worktree) Scan(ctx context.Context) (Snapshot, error)

Scan lists the SQL files and reads the branch.

func (*Worktree) Stat

func (w *Worktree) Stat(rel string) (Stamp, error)

Stat reports the stamp of a file without reading it, which is how a save notices the file changed since it was opened.

func (*Worktree) Write

func (w *Worktree) Write(rel, text string) (Stamp, error)

Write replaces a file's contents and reports the new stamp.

The replacement goes through a temporary file in the same directory and a rename, so a crash partway through leaves the previous version intact rather than a truncated migration.