Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

hort ls

List every sandbox on this machine with its state.

hort ls

Options:
  -h, --help  Print help

Output

A header naming each column, then one line per sandbox, from every project:

$ hort ls
NAME       STATE        SESSIONS  AGE     IDLE    GIT                          BRANCH     DIRTY
old-spike  orphaned     0         2d 3h   2d 2h   worktree                     old-spike  clean
notes      live         0         35s     15s     -                            -          -
pr-bot     live         1         2h 5m   active  clone, work only in the box  pr-bot     clean
fix-login  live         2         41m 3s  active  worktree                     fix-login  dirty
ghost      lost-record  0         -       -       -                            -          -
    running with no record on disk; run 'hort down ghost' to stop its container and host-side helpers

Each column is aligned under its name in the header:

ColumnMeaning
NAMEThe sandbox name.
STATElive, orphaned, inconsistent or lost-record. See States.
SESSIONSProcesses running in the sandbox besides its anchor. One shell running one command counts as 2.
AGETime since hort up built it.
IDLEactive while anything runs inside; otherwise time since the latest of creation, last attach and last announced completion.
GITHow the sandbox was built: worktree, or for a clone-mode sandbox clone when the project's repository has every commit in it, clone, work only in the box when the clone holds commits it does not, and clone, work unknown when hort could not tell. - when there is no mode to report: a lost-record row, a project without git, or a sandbox whose worktree or clone is gone.
BRANCHThe sandbox's branch, or - without git.
DIRTYdirty if the worktree, or the clone of a clone-mode sandbox, has uncommitted changes, clean if not. - when the worktree or the clone records a submodule, a repository added inside it, because hort does not look inside one.

A - means hort could not tell: there is no record to read (a lost-record row), the project has no git (git mode, branch and dirty), the worktree or the clone records a submodule (dirty), reading the sandbox's worktree or clone did not answer within a few seconds (dirty, and for a clone the work it holds too), the worktree is gone, or hort could not read the sandbox's process list (sessions, and idle with it). hort shows - rather than guessing.

A lost-record row is followed by an indented line with the command that collects it.

Age and idle are printed in at most two units, the larger first (2d 3h, 41m 3s), and are rounded down, never up, so an idle time ls shows is one hort prune --idle accepts back: a sandbox listed idle 2d 2h is idle long enough for hort prune --idle "2d 2h". A sandbox younger than a second shows 0s.

Behaviour

ls never changes anything and never fails because of one sandbox: it compares hort's records, the processes the kernel is running and the worktrees on disk, and reports what it finds. It needs neither pasta nor a rootfs and does not read the configuration, so it works even when a configuration file is broken.

dirty is checked in each sandbox's own worktree or clone, whatever directory you run ls from. A dirty sandbox is the one to look at first: it holds work nobody has committed.

A clone is checked from your host without obeying anything the agent wrote into it. The agent can write the clone's git configuration, which can name programs git runs while it checks, such as a file monitor or a filter, so hort reads the clone's files and index with no git configuration at all and those programs never run on your machine. That leaves your own global git configuration out of the check as well: a file ignored only through a core.excludesFile set there makes a clone dirty.

A clone's commits are looked for in the repository of the project it was built from, whatever directory you run ls from, with the same check hort down asks before removing it. work only in the box is the same words hort prune skips such a sandbox with: commits that exist nowhere but in that sandbox, which go with it when it is removed. Push them or fetch them out first.

Messages

ls prints nothing but the listing. On an empty machine it prints nothing at all. The general errors in Commands can still occur, for example if hort's state directory is unreadable.