# zidane-ui/git/headless

Import: `import { … } from 'zidane-ui/git/headless'`. Source: [ui/src/git/headless/index.ts](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/index.ts).

## Functions

### `ageIsDuration`

Function.

Whether an age reads as a duration (`5m`, takes "ago") rather than `now` or a date.

```ts
function ageIsDuration(at: number, now: number): boolean
```

**Parameters**

- `at` (`number`): Epoch ms of the event.
- `now` (`number`): Epoch ms of the current time.

**Returns** `boolean`

Source: [ui/src/git/headless/switcher.ts:160](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L160)

### `clockTime`

Function.

A clock time, `14:05`.

```ts
function clockTime(ms: number): string
```

**Parameters**

- `ms` (`number`): Epoch ms.

**Returns** `string`

Source: [ui/src/git/headless/switcher.ts:169](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L169)

### `compactCount`

Function.

A diff size at a glance: 1234 → `1.2k`.

```ts
function compactCount(n: number): string
```

**Parameters**

- `n` (`number`): The count.

**Returns** `string`

Source: [ui/src/git/headless/switcher.ts:150](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L150)

### `createSwitcherCache`

Function.

Creates an empty [`SwitcherCache`](https://zidane.si/docs/reference/ui-git-headless.md#SwitcherCache).

```ts
function createSwitcherCache(): SwitcherCache
```

**Returns** `SwitcherCache`

Source: [ui/src/git/headless/switcher.ts:189](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L189)

### `environmentBaseKind`

Function.

The base of an environment kind (`worktree@laptop` → `worktree`).

```ts
function environmentBaseKind(kind: string): string
```

**Parameters**

- `kind` (`string`): The environment kind.

**Returns** `string`

Source: [ui/src/git/headless/environment.ts:126](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/environment.ts#L126)

### `environmentKindIcon`

Function.

The icon class of an environment kind; a machine's kind (`worktree@laptop`) takes its base kind's.

```ts
function environmentKindIcon(kind: string): string
```

**Parameters**

- `kind` (`string`): The environment kind.

**Returns** `string`

Source: [ui/src/git/headless/environment.ts:45](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/environment.ts#L45)

### `folderName`

Function.

The last segment of a path, for a folder's short name (`/srv/app/` → `app`).

```ts
function folderName(path: string): string
```

**Parameters**

- `path` (`string`): A `/` or \`\` separated path.

**Returns** `string`

Source: [ui/src/git/headless/environment.ts:135](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/environment.ts#L135)

### `gitErrorText`

Function.

A host error in words: the host's own message, or `DEFAULT_GIT_LABELS.gitUnavailable`.

```ts
function gitErrorText(
  error: { code: 'unavailable' } | { code: 'failed'; message: string },
  labels: Pick<GitLabels, 'gitUnavailable'>,
): string
```

**Parameters**

- `error` (`{ code: 'unavailable' } | { code: 'failed'; message: string }`): The host's error.
- `labels` (`Pick<GitLabels, 'gitUnavailable'>`): The labels in effect.

**Returns** `string`

Source: [ui/src/git/headless/labels.ts:227](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/labels.ts#L227)

### `leavesWorktree`

Function.

The session runs in a worktree (`worktree`, `worktree@<machine>`): any move leaves it, and the move can remove it.

```ts
function leavesWorktree(subject: MoveSessionSubject): boolean
```

**Parameters**

- `subject` (`MoveSessionSubject`): The session.

**Returns** `boolean`

Source: [ui/src/git/headless/move.ts:88](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/move.ts#L88)

### `machinesOf`

Function.

The machines the descriptors name, once each, enabled ones only, without the `hidden` names.

```ts
function machinesOf(
  descriptors: readonly EnvironmentDescriptor[],
  hidden: ReadonlySet<string>,
): { id: string; name: string; status: 'online' | 'offline' }[]
```

**Parameters**

- `descriptors` (`readonly EnvironmentDescriptor[]`): The kinds the draft's host lists.
- `hidden` (`ReadonlySet<string>`): Machine names not to list.

**Returns** `{ id: string; name: string; status: 'online' | 'offline' }[]`

Source: [ui/src/git/headless/environment.ts:107](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/environment.ts#L107)

### `moveChoices`

Function.

The kinds a session can move to, this host's first, then each machine's. Disabled kinds never show; an offline
machine's kinds and unavailable kinds show, not pickable, with the reason.

```ts
function moveChoices(
  descriptors: readonly EnvironmentDescriptor[],
  subject: MoveSessionSubject,
): MoveChoice[]
```

**Parameters**

- `descriptors` (`readonly EnvironmentDescriptor[]`): The kinds the session's host lists.
- `subject` (`MoveSessionSubject`): The session.

**Returns** `MoveChoice[]`

Source: [ui/src/git/headless/move.ts:67](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/move.ts#L67)

### `moveListingCwd`

Function.

The folder query the kinds are listed for: the session's folder when it is this host's (a machine's folder would
make every kind of this host unavailable).

```ts
function moveListingCwd(subject: MoveSessionSubject): string | undefined
```

**Parameters**

- `subject` (`MoveSessionSubject`): The session.

**Returns** `string | undefined`

Source: [ui/src/git/headless/move.ts:99](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/move.ts#L99)

### `moveSubject`

Function.

The subject of a move, from a session row (a sidebar row, the header's session).

```ts
function moveSubject(
  session: { cwd?: string; environment?: { kind: string }; hostId?: string; id: string; turnCount?: number },
): MoveSessionSubject
```

**Parameters**

- `session` (`{ cwd?: string; environment?: { kind: string }; hostId?: string; id: string; turnCount?: number }`): The session's key, folder, host, environment and turn count (absent: it has turns).

**Returns** `MoveSessionSubject`

Source: [ui/src/git/headless/move.ts:30](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/move.ts#L30)

### `prMatches`

Function.

What a pull request search matches: `#12` or `12` (a number prefix), or the title, branch or
author (case-insensitive).

```ts
function prMatches(
  pr: Pick<GitPullRequest, 'number' | 'title' | 'branch' | 'author'>,
  query: string,
): boolean
```

**Parameters**

- `pr` (`Pick<GitPullRequest, 'number' | 'title' | 'branch' | 'author'>`): The pull request.
- `query` (`string`): What was typed.

**Returns** `boolean`

Source: [ui/src/git/headless/switcher.ts:49](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L49)

### `readPullRequests`

Function.

A pull request list as the menu holds it: the list (`null` when the host cannot reach pull
requests) and, when GitHub rate-limited it, when it resumes.

```ts
function readPullRequests(
  result: GitPullRequestList,
): { list: readonly GitPullRequest[] | null; retryAt: number | null }
```

**Parameters**

- `result` (`GitPullRequestList`): The host's answer.

**Returns** `{ list: readonly GitPullRequest[] | null; retryAt: number | null }`

Source: [ui/src/git/headless/switcher.ts:67](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L67)

### `resolveDraftDescriptor`

Function.

The descriptor a draft resolves to: the pick when still usable, else the default, else Local.
`undefined` when nothing is loaded yet.

```ts
function resolveDraftDescriptor(
  descriptors: readonly EnvironmentDescriptor[],
  draft: DraftEnvironment | null,
): EnvironmentDescriptor | undefined
```

**Parameters**

- `descriptors` (`readonly EnvironmentDescriptor[]`): The kinds the draft's host lists.
- `draft` (`DraftEnvironment | null`): The draft's pick, `null` for the default.

**Returns** `EnvironmentDescriptor | undefined`

Source: [ui/src/git/headless/environment.ts:71](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/environment.ts#L71)

### `resolveDraftEnvironment`

Function.

The environment a session is created with for a draft; `undefined` = Local.

```ts
function resolveDraftEnvironment(
  descriptors: readonly EnvironmentDescriptor[],
  draft: DraftEnvironment | null,
): EnvironmentRequest | undefined
```

**Parameters**

- `descriptors` (`readonly EnvironmentDescriptor[]`): The kinds the draft's host lists.
- `draft` (`DraftEnvironment | null`): The draft's pick, `null` for the default.

**Returns** `EnvironmentRequest | undefined`

Source: [ui/src/git/headless/environment.ts:85](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/environment.ts#L85)

### `resolveRemoteClone`

Function.

What a send would clone, from the local project's `origin` and the listing of the server's first root.

```ts
function resolveRemoteClone(
  origin: string | null,
  root: GitFolderListing,
): DraftRemoteClone | null
```

**Parameters**

- `origin` (`string | null`): The `origin` URL of the local project, `null` without one.
- `root` (`GitFolderListing`): The listing of the server's first workspace root.

**Returns** `DraftRemoteClone | null`: `null` when there is nothing to clone (no `origin`, not a repository URL, or a server that says nothing
about clones).

Source: [ui/src/git/headless/remote-clone.ts:39](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/remote-clone.ts#L39)

### `switcherCacheOf`

Function.

The [`SwitcherCache`](https://zidane.si/docs/reference/ui-git-headless.md#SwitcherCache) of a host: one per host, kept as long as the host is.

```ts
function switcherCacheOf(host: GitHost): SwitcherCache
```

**Parameters**

- `host` (`GitHost`): The git host.

**Returns** `SwitcherCache`

Source: [ui/src/git/headless/switcher.ts:208](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L208)

### `switcherCreates`

Function.

A typed name no branch here or pull request carries, offered to start: as a branch, and as a
worktree when one can be started.

```ts
function switcherCreates(
  input: { branches: readonly GitBranch[] | null; canCreateBranch: boolean; canStartWorktree: boolean; current: string | null; prs: readonly GitPullRequest[] | null | undefined; searched: readonly GitPullRequest[] | null | undefined; typed: string },
): SwitcherEntry[]
```

**Parameters**

- `input` (`{ branches: readonly GitBranch[] | null; canCreateBranch: boolean; canStartWorktree: boolean; current: string | null; prs: readonly GitPullRequest[] | null | undefined; searched: readonly GitPullRequest[] | null | undefined; typed: string }`): The typed name (trimmed), the current branch, what is loaded, and what can be started.

**Returns** `SwitcherEntry[]`

Source: [ui/src/git/headless/switcher.ts:113](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L113)

### `switcherKey`

Function.

A row's stable key (and the busy marker of its action).

```ts
function switcherKey(entry: SwitcherEntry): string
```

**Parameters**

- `entry` (`SwitcherEntry`): The row.

**Returns** `string`

Source: [ui/src/git/headless/switcher.ts:137](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L137)

### `switcherSections`

Function.

The sections in order for a query, each capped unless searching or expanded; empty ones left
out. A branch with an open pull request (any known) is listed once, under the pull request.

```ts
function switcherSections(
  input: { branches: readonly GitBranch[] | null; expanded: ReadonlySet<SwitcherSectionId>; prs: readonly GitPullRequest[] | null | undefined; query: string; searched: readonly GitPullRequest[] | null },
): SwitcherSection[]
```

**Parameters**

- `input` (`{ branches: readonly GitBranch[] | null; expanded: ReadonlySet<SwitcherSectionId>; prs: readonly GitPullRequest[] | null | undefined; query: string; searched: readonly GitPullRequest[] | null }`): The loaded pull requests and branches, the search's answer, the query (trimmed,
  lower case) and the expanded sections.

**Returns** `SwitcherSection[]`

Source: [ui/src/git/headless/switcher.ts:83](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L83)

### `syncAction`

Function.

What a click does, or `null` when the chip only reports.

```ts
function syncAction(status: GitStatus): GitSyncAction | null
```

**Parameters**

- `status` (`GitStatus`): The checkout's status.

**Returns** `GitSyncAction | null`

Source: [ui/src/git/headless/sync.ts:20](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/sync.ts#L20)

### `syncSummary`

Function.

The confirmation's one sentence: what will move, and where.

```ts
function syncSummary(
  status: GitStatus,
  labels: { gitAhead: (count: number) => string; gitApproved: string; gitAuthorLabel: (author: string) => string; gitBehind: (count: number) => string; gitBranch: string; gitBranchButton: (branch: string) => string; gitBranchChipLabel: (branch: string) => string; gitBranchDetached: (commit: string) => string; gitBranchHint: string; gitBranchPlaceholder: string; gitBranchSwitch: string; gitBranchSwitchLater: string; gitChangesRequested: string; gitChangesTooltip: string; gitChecksLabel: (checks: Checks) => string; gitChecksText: (checks: Checks) => string; gitCommitsAhead: (count: number, base: string | null) => string; gitCommitsBehind: (count: number) => string; gitCopyBranch: string; gitDefaultBranch: string; gitDontAskAgain: string; gitDraft: string; gitDriftLabel: (ahead: number, behind: number) => string; gitEnvironmentSettings: string; gitFactsThen: (facts: string, action: string) => string; gitFilesUnit: (count: number) => ' file' | ' files'; gitFolderBackToRoots: string; gitFolderCancel: string; gitFolderCreate: string; gitFolderCreating: string; gitFolderDefault: string; gitFolderDefaultTitle: (host: string) => string; gitFolderEmpty: string; gitFolderFilter: string; gitFolderFilterLabel: string; gitFolderNew: string; gitFolderNewName: string; gitFolderNewNameLabel: (parent: string) => string; gitFolderNoMatch: string; gitFolderOpenPath: (path: string) => string; gitFolderPathLabel: string; gitFolderPickerLabel: (host: string) => string; gitFolderReading: string; gitFolderRoots: string; gitFolderSearchDeeper: (query: string) => string; gitFolderSearching: string; gitFolderSearchNone: string; gitFolderSearchResults: string; gitFolderSearchTruncated: string; gitFolderTitle: (folder: string, host: string) => string; gitFolderUse: (name: string) => string; gitFork: string; gitFromHere: string; gitHostLocalDescription: string; gitHostServerDescription: string; gitImportArchived: string; gitImportCancel: string; gitImportChange: string; gitImportClone: string; gitImportCloning: string; gitImportConnecting: string; gitImportField: string; gitImportHintAfter: string; gitImportHintBefore: string; gitImportHintCode: string; gitImportInto: string; gitImportInvalid: string; gitImportPlaceholder: string; gitImportPreview: (label: string, branch: string | undefined, destination: string) => string; gitImportPrivate: string; gitImportProgress: (phase: string, percent: number) => string; gitImportStars: (stars: number) => string; gitImportStop: string; gitImportTitle: string; gitImportViewOnGithub: string; gitIsolation: string; gitIsolationDefault: string; gitLastCommitAge: (age: string, duration: boolean) => string; gitListLabel: string; gitLoadingBranches: string; gitLocal: string; gitLocalLabel: string; gitMachineDescription: (name: string) => string; gitMachineOffline: (name: string) => string; gitMachineStatus: (status: string) => string; gitMenuLabel: string; gitMore: (count: number) => string; gitMoreSearchHint: string; gitMoveBack: string; gitMoveBranch: string; gitMoveCancel: string; gitMoveChangeFolder: string; gitMoveConfirm: (name: string) => string; gitMoveConfirmDetail: string; gitMoveCurrent: string; gitMoveDone: string; gitMoveFolder: string; gitMoveKeepFolder: string; gitMoveLoading: string; gitMoveMainCheckout: string; gitMoveMoving: string; gitMoveNone: string; gitMoveOffline: string; gitMovePickFolder: (name: string) => string; gitMoveRemoveWorktree: string; gitMovesThisChat: string; gitMoveSubmit: string; gitMoveTitle: string; gitMoveWhere: string; gitMoveWorktreeKept: (reason: string | undefined) => string; gitNoGh: string; gitNoMatches: string; gitOpenOnGitHub: string; gitOpenPullRequest: (number: number) => string; gitPrDraft: string; gitPrTooltip: (pr: { draft: boolean; number: number; title: string }) => string; gitPublish: string; gitPublishBranch: (branch: string) => string; gitPublishDialog: string; gitPublishing: string; gitPublishLater: string; gitPublishSummary: (branch: string, ahead: number, remote: string | null) => string; gitPublishTo: (remote: string | null) => string; gitRateLimited: (clock: string) => string; gitRowCurrent: string; gitRowSwitching: string; gitRunsOn: string; gitRunsOnHelpLabel: string; gitRunsOnLocal: string; gitRunsOnLocalFact: string; gitRunsOnMachine: string; gitRunsOnMachineFact: string; gitRunsOnServer: string; gitRunsOnServerFact: string; gitSearching: string; gitSearchLabel: string; gitSearchPlaceholder: string; gitSectionBranches: string; gitSectionMine: string; gitSectionOther: string; gitSectionPullRequests: string; gitSectionReview: string; gitStartAsWorktree: string; gitStartBranch: string; gitStartBranchLabel: (name: string) => string; gitStartCheckedOutElsewhere: (path: string) => string; gitStartingWorktree: string; gitStartNoWorktree: string; gitStartTheWorktree: string; gitStartWorktree: string; gitStartWorktreeLabel: (name: string) => string; gitSync: string; gitSyncCancel: string; gitSyncDialog: string; gitSyncing: string; gitSyncKeepsChanges: string; gitSyncLater: string; gitSyncSummary: (behind: number, ahead: number, upstream: string) => string; gitSyncWith: (upstream: string | null) => string; gitToPull: (count: number) => string; gitToPush: (count: number) => string; gitUnavailable: string; gitUpdatedAge: (age: string, duration: boolean) => string; gitUpToDate: (upstream: string) => string; gitWhereLabel: string; gitWhereTitle: (place: string, isolation: string | undefined, branch: string | undefined) => string; gitWorktreeBranchLabel: string; gitWorktreeBranchPlaceholder: string; gitWorktreeShort: string },
): string
```

**Parameters**

- `status` (`GitStatus`): The checkout's status.
- `labels` (`{ gitAhead: (count: number) => string; gitApproved: string; gitAuthorLabel: (author: string) => string; gitBehind: (count: number) => string; gitBranch: string; gitBranchButton: (branch: string) => string; gitBranchChipLabel: (branch: string) => string; gitBranchDetached: (commit: string) => string; gitBranchHint: string; gitBranchPlaceholder: string; gitBranchSwitch: string; gitBranchSwitchLater: string; gitChangesRequested: string; gitChangesTooltip: string; gitChecksLabel: (checks: Checks) => string; gitChecksText: (checks: Checks) => string; gitCommitsAhead: (count: number, base: string | null) => string; gitCommitsBehind: (count: number) => string; gitCopyBranch: string; gitDefaultBranch: string; gitDontAskAgain: string; gitDraft: string; gitDriftLabel: (ahead: number, behind: number) => string; gitEnvironmentSettings: string; gitFactsThen: (facts: string, action: string) => string; gitFilesUnit: (count: number) => ' file' | ' files'; gitFolderBackToRoots: string; gitFolderCancel: string; gitFolderCreate: string; gitFolderCreating: string; gitFolderDefault: string; gitFolderDefaultTitle: (host: string) => string; gitFolderEmpty: string; gitFolderFilter: string; gitFolderFilterLabel: string; gitFolderNew: string; gitFolderNewName: string; gitFolderNewNameLabel: (parent: string) => string; gitFolderNoMatch: string; gitFolderOpenPath: (path: string) => string; gitFolderPathLabel: string; gitFolderPickerLabel: (host: string) => string; gitFolderReading: string; gitFolderRoots: string; gitFolderSearchDeeper: (query: string) => string; gitFolderSearching: string; gitFolderSearchNone: string; gitFolderSearchResults: string; gitFolderSearchTruncated: string; gitFolderTitle: (folder: string, host: string) => string; gitFolderUse: (name: string) => string; gitFork: string; gitFromHere: string; gitHostLocalDescription: string; gitHostServerDescription: string; gitImportArchived: string; gitImportCancel: string; gitImportChange: string; gitImportClone: string; gitImportCloning: string; gitImportConnecting: string; gitImportField: string; gitImportHintAfter: string; gitImportHintBefore: string; gitImportHintCode: string; gitImportInto: string; gitImportInvalid: string; gitImportPlaceholder: string; gitImportPreview: (label: string, branch: string | undefined, destination: string) => string; gitImportPrivate: string; gitImportProgress: (phase: string, percent: number) => string; gitImportStars: (stars: number) => string; gitImportStop: string; gitImportTitle: string; gitImportViewOnGithub: string; gitIsolation: string; gitIsolationDefault: string; gitLastCommitAge: (age: string, duration: boolean) => string; gitListLabel: string; gitLoadingBranches: string; gitLocal: string; gitLocalLabel: string; gitMachineDescription: (name: string) => string; gitMachineOffline: (name: string) => string; gitMachineStatus: (status: string) => string; gitMenuLabel: string; gitMore: (count: number) => string; gitMoreSearchHint: string; gitMoveBack: string; gitMoveBranch: string; gitMoveCancel: string; gitMoveChangeFolder: string; gitMoveConfirm: (name: string) => string; gitMoveConfirmDetail: string; gitMoveCurrent: string; gitMoveDone: string; gitMoveFolder: string; gitMoveKeepFolder: string; gitMoveLoading: string; gitMoveMainCheckout: string; gitMoveMoving: string; gitMoveNone: string; gitMoveOffline: string; gitMovePickFolder: (name: string) => string; gitMoveRemoveWorktree: string; gitMovesThisChat: string; gitMoveSubmit: string; gitMoveTitle: string; gitMoveWhere: string; gitMoveWorktreeKept: (reason: string | undefined) => string; gitNoGh: string; gitNoMatches: string; gitOpenOnGitHub: string; gitOpenPullRequest: (number: number) => string; gitPrDraft: string; gitPrTooltip: (pr: { draft: boolean; number: number; title: string }) => string; gitPublish: string; gitPublishBranch: (branch: string) => string; gitPublishDialog: string; gitPublishing: string; gitPublishLater: string; gitPublishSummary: (branch: string, ahead: number, remote: string | null) => string; gitPublishTo: (remote: string | null) => string; gitRateLimited: (clock: string) => string; gitRowCurrent: string; gitRowSwitching: string; gitRunsOn: string; gitRunsOnHelpLabel: string; gitRunsOnLocal: string; gitRunsOnLocalFact: string; gitRunsOnMachine: string; gitRunsOnMachineFact: string; gitRunsOnServer: string; gitRunsOnServerFact: string; gitSearching: string; gitSearchLabel: string; gitSearchPlaceholder: string; gitSectionBranches: string; gitSectionMine: string; gitSectionOther: string; gitSectionPullRequests: string; gitSectionReview: string; gitStartAsWorktree: string; gitStartBranch: string; gitStartBranchLabel: (name: string) => string; gitStartCheckedOutElsewhere: (path: string) => string; gitStartingWorktree: string; gitStartNoWorktree: string; gitStartTheWorktree: string; gitStartWorktree: string; gitStartWorktreeLabel: (name: string) => string; gitSync: string; gitSyncCancel: string; gitSyncDialog: string; gitSyncing: string; gitSyncKeepsChanges: string; gitSyncLater: string; gitSyncSummary: (behind: number, ahead: number, upstream: string) => string; gitSyncWith: (upstream: string | null) => string; gitToPull: (count: number) => string; gitToPush: (count: number) => string; gitUnavailable: string; gitUpdatedAge: (age: string, duration: boolean) => string; gitUpToDate: (upstream: string) => string; gitWhereLabel: string; gitWhereTitle: (place: string, isolation: string | undefined, branch: string | undefined) => string; gitWorktreeBranchLabel: string; gitWorktreeBranchPlaceholder: string; gitWorktreeShort: string }`): The git labels.

**Returns** `string`

Source: [ui/src/git/headless/sync.ts:32](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/sync.ts#L32)

### `syncTooltip`

Function.

The chip's tooltip (and accessible name): the counts, then what a click does.

```ts
function syncTooltip(
  status: GitStatus,
  action: GitSyncAction | null,
  state: { busy: boolean; running: boolean },
  labels: { gitAhead: (count: number) => string; gitApproved: string; gitAuthorLabel: (author: string) => string; gitBehind: (count: number) => string; gitBranch: string; gitBranchButton: (branch: string) => string; gitBranchChipLabel: (branch: string) => string; gitBranchDetached: (commit: string) => string; gitBranchHint: string; gitBranchPlaceholder: string; gitBranchSwitch: string; gitBranchSwitchLater: string; gitChangesRequested: string; gitChangesTooltip: string; gitChecksLabel: (checks: Checks) => string; gitChecksText: (checks: Checks) => string; gitCommitsAhead: (count: number, base: string | null) => string; gitCommitsBehind: (count: number) => string; gitCopyBranch: string; gitDefaultBranch: string; gitDontAskAgain: string; gitDraft: string; gitDriftLabel: (ahead: number, behind: number) => string; gitEnvironmentSettings: string; gitFactsThen: (facts: string, action: string) => string; gitFilesUnit: (count: number) => ' file' | ' files'; gitFolderBackToRoots: string; gitFolderCancel: string; gitFolderCreate: string; gitFolderCreating: string; gitFolderDefault: string; gitFolderDefaultTitle: (host: string) => string; gitFolderEmpty: string; gitFolderFilter: string; gitFolderFilterLabel: string; gitFolderNew: string; gitFolderNewName: string; gitFolderNewNameLabel: (parent: string) => string; gitFolderNoMatch: string; gitFolderOpenPath: (path: string) => string; gitFolderPathLabel: string; gitFolderPickerLabel: (host: string) => string; gitFolderReading: string; gitFolderRoots: string; gitFolderSearchDeeper: (query: string) => string; gitFolderSearching: string; gitFolderSearchNone: string; gitFolderSearchResults: string; gitFolderSearchTruncated: string; gitFolderTitle: (folder: string, host: string) => string; gitFolderUse: (name: string) => string; gitFork: string; gitFromHere: string; gitHostLocalDescription: string; gitHostServerDescription: string; gitImportArchived: string; gitImportCancel: string; gitImportChange: string; gitImportClone: string; gitImportCloning: string; gitImportConnecting: string; gitImportField: string; gitImportHintAfter: string; gitImportHintBefore: string; gitImportHintCode: string; gitImportInto: string; gitImportInvalid: string; gitImportPlaceholder: string; gitImportPreview: (label: string, branch: string | undefined, destination: string) => string; gitImportPrivate: string; gitImportProgress: (phase: string, percent: number) => string; gitImportStars: (stars: number) => string; gitImportStop: string; gitImportTitle: string; gitImportViewOnGithub: string; gitIsolation: string; gitIsolationDefault: string; gitLastCommitAge: (age: string, duration: boolean) => string; gitListLabel: string; gitLoadingBranches: string; gitLocal: string; gitLocalLabel: string; gitMachineDescription: (name: string) => string; gitMachineOffline: (name: string) => string; gitMachineStatus: (status: string) => string; gitMenuLabel: string; gitMore: (count: number) => string; gitMoreSearchHint: string; gitMoveBack: string; gitMoveBranch: string; gitMoveCancel: string; gitMoveChangeFolder: string; gitMoveConfirm: (name: string) => string; gitMoveConfirmDetail: string; gitMoveCurrent: string; gitMoveDone: string; gitMoveFolder: string; gitMoveKeepFolder: string; gitMoveLoading: string; gitMoveMainCheckout: string; gitMoveMoving: string; gitMoveNone: string; gitMoveOffline: string; gitMovePickFolder: (name: string) => string; gitMoveRemoveWorktree: string; gitMovesThisChat: string; gitMoveSubmit: string; gitMoveTitle: string; gitMoveWhere: string; gitMoveWorktreeKept: (reason: string | undefined) => string; gitNoGh: string; gitNoMatches: string; gitOpenOnGitHub: string; gitOpenPullRequest: (number: number) => string; gitPrDraft: string; gitPrTooltip: (pr: { draft: boolean; number: number; title: string }) => string; gitPublish: string; gitPublishBranch: (branch: string) => string; gitPublishDialog: string; gitPublishing: string; gitPublishLater: string; gitPublishSummary: (branch: string, ahead: number, remote: string | null) => string; gitPublishTo: (remote: string | null) => string; gitRateLimited: (clock: string) => string; gitRowCurrent: string; gitRowSwitching: string; gitRunsOn: string; gitRunsOnHelpLabel: string; gitRunsOnLocal: string; gitRunsOnLocalFact: string; gitRunsOnMachine: string; gitRunsOnMachineFact: string; gitRunsOnServer: string; gitRunsOnServerFact: string; gitSearching: string; gitSearchLabel: string; gitSearchPlaceholder: string; gitSectionBranches: string; gitSectionMine: string; gitSectionOther: string; gitSectionPullRequests: string; gitSectionReview: string; gitStartAsWorktree: string; gitStartBranch: string; gitStartBranchLabel: (name: string) => string; gitStartCheckedOutElsewhere: (path: string) => string; gitStartingWorktree: string; gitStartNoWorktree: string; gitStartTheWorktree: string; gitStartWorktree: string; gitStartWorktreeLabel: (name: string) => string; gitSync: string; gitSyncCancel: string; gitSyncDialog: string; gitSyncing: string; gitSyncKeepsChanges: string; gitSyncLater: string; gitSyncSummary: (behind: number, ahead: number, upstream: string) => string; gitSyncWith: (upstream: string | null) => string; gitToPull: (count: number) => string; gitToPush: (count: number) => string; gitUnavailable: string; gitUpdatedAge: (age: string, duration: boolean) => string; gitUpToDate: (upstream: string) => string; gitWhereLabel: string; gitWhereTitle: (place: string, isolation: string | undefined, branch: string | undefined) => string; gitWorktreeBranchLabel: string; gitWorktreeBranchPlaceholder: string; gitWorktreeShort: string },
): string
```

**Parameters**

- `status` (`GitStatus`): The checkout's status.
- `action` (`GitSyncAction | null`): [`syncAction`](https://zidane.si/docs/reference/ui-git-headless.md#syncAction) of it.
- `state` (`{ busy: boolean; running: boolean }`): The agent is working (`running`), a sync is in flight (`busy`).
- `labels` (`{ gitAhead: (count: number) => string; gitApproved: string; gitAuthorLabel: (author: string) => string; gitBehind: (count: number) => string; gitBranch: string; gitBranchButton: (branch: string) => string; gitBranchChipLabel: (branch: string) => string; gitBranchDetached: (commit: string) => string; gitBranchHint: string; gitBranchPlaceholder: string; gitBranchSwitch: string; gitBranchSwitchLater: string; gitChangesRequested: string; gitChangesTooltip: string; gitChecksLabel: (checks: Checks) => string; gitChecksText: (checks: Checks) => string; gitCommitsAhead: (count: number, base: string | null) => string; gitCommitsBehind: (count: number) => string; gitCopyBranch: string; gitDefaultBranch: string; gitDontAskAgain: string; gitDraft: string; gitDriftLabel: (ahead: number, behind: number) => string; gitEnvironmentSettings: string; gitFactsThen: (facts: string, action: string) => string; gitFilesUnit: (count: number) => ' file' | ' files'; gitFolderBackToRoots: string; gitFolderCancel: string; gitFolderCreate: string; gitFolderCreating: string; gitFolderDefault: string; gitFolderDefaultTitle: (host: string) => string; gitFolderEmpty: string; gitFolderFilter: string; gitFolderFilterLabel: string; gitFolderNew: string; gitFolderNewName: string; gitFolderNewNameLabel: (parent: string) => string; gitFolderNoMatch: string; gitFolderOpenPath: (path: string) => string; gitFolderPathLabel: string; gitFolderPickerLabel: (host: string) => string; gitFolderReading: string; gitFolderRoots: string; gitFolderSearchDeeper: (query: string) => string; gitFolderSearching: string; gitFolderSearchNone: string; gitFolderSearchResults: string; gitFolderSearchTruncated: string; gitFolderTitle: (folder: string, host: string) => string; gitFolderUse: (name: string) => string; gitFork: string; gitFromHere: string; gitHostLocalDescription: string; gitHostServerDescription: string; gitImportArchived: string; gitImportCancel: string; gitImportChange: string; gitImportClone: string; gitImportCloning: string; gitImportConnecting: string; gitImportField: string; gitImportHintAfter: string; gitImportHintBefore: string; gitImportHintCode: string; gitImportInto: string; gitImportInvalid: string; gitImportPlaceholder: string; gitImportPreview: (label: string, branch: string | undefined, destination: string) => string; gitImportPrivate: string; gitImportProgress: (phase: string, percent: number) => string; gitImportStars: (stars: number) => string; gitImportStop: string; gitImportTitle: string; gitImportViewOnGithub: string; gitIsolation: string; gitIsolationDefault: string; gitLastCommitAge: (age: string, duration: boolean) => string; gitListLabel: string; gitLoadingBranches: string; gitLocal: string; gitLocalLabel: string; gitMachineDescription: (name: string) => string; gitMachineOffline: (name: string) => string; gitMachineStatus: (status: string) => string; gitMenuLabel: string; gitMore: (count: number) => string; gitMoreSearchHint: string; gitMoveBack: string; gitMoveBranch: string; gitMoveCancel: string; gitMoveChangeFolder: string; gitMoveConfirm: (name: string) => string; gitMoveConfirmDetail: string; gitMoveCurrent: string; gitMoveDone: string; gitMoveFolder: string; gitMoveKeepFolder: string; gitMoveLoading: string; gitMoveMainCheckout: string; gitMoveMoving: string; gitMoveNone: string; gitMoveOffline: string; gitMovePickFolder: (name: string) => string; gitMoveRemoveWorktree: string; gitMovesThisChat: string; gitMoveSubmit: string; gitMoveTitle: string; gitMoveWhere: string; gitMoveWorktreeKept: (reason: string | undefined) => string; gitNoGh: string; gitNoMatches: string; gitOpenOnGitHub: string; gitOpenPullRequest: (number: number) => string; gitPrDraft: string; gitPrTooltip: (pr: { draft: boolean; number: number; title: string }) => string; gitPublish: string; gitPublishBranch: (branch: string) => string; gitPublishDialog: string; gitPublishing: string; gitPublishLater: string; gitPublishSummary: (branch: string, ahead: number, remote: string | null) => string; gitPublishTo: (remote: string | null) => string; gitRateLimited: (clock: string) => string; gitRowCurrent: string; gitRowSwitching: string; gitRunsOn: string; gitRunsOnHelpLabel: string; gitRunsOnLocal: string; gitRunsOnLocalFact: string; gitRunsOnMachine: string; gitRunsOnMachineFact: string; gitRunsOnServer: string; gitRunsOnServerFact: string; gitSearching: string; gitSearchLabel: string; gitSearchPlaceholder: string; gitSectionBranches: string; gitSectionMine: string; gitSectionOther: string; gitSectionPullRequests: string; gitSectionReview: string; gitStartAsWorktree: string; gitStartBranch: string; gitStartBranchLabel: (name: string) => string; gitStartCheckedOutElsewhere: (path: string) => string; gitStartingWorktree: string; gitStartNoWorktree: string; gitStartTheWorktree: string; gitStartWorktree: string; gitStartWorktreeLabel: (name: string) => string; gitSync: string; gitSyncCancel: string; gitSyncDialog: string; gitSyncing: string; gitSyncKeepsChanges: string; gitSyncLater: string; gitSyncSummary: (behind: number, ahead: number, upstream: string) => string; gitSyncWith: (upstream: string | null) => string; gitToPull: (count: number) => string; gitToPush: (count: number) => string; gitUnavailable: string; gitUpdatedAge: (age: string, duration: boolean) => string; gitUpToDate: (upstream: string) => string; gitWhereLabel: string; gitWhereTitle: (place: string, isolation: string | undefined, branch: string | undefined) => string; gitWorktreeBranchLabel: string; gitWorktreeBranchPlaceholder: string; gitWorktreeShort: string }`): The git labels.

**Returns** `string`

Source: [ui/src/git/headless/sync.ts:45](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/sync.ts#L45)

### `withMachines`

Function.

A machine's kinds after this host's, grouped by machine; an offline machine's stay listed,
unavailable with the reason.

```ts
function withMachines(
  descriptors: readonly EnvironmentDescriptor[],
): EnvironmentDescriptor[]
```

**Parameters**

- `descriptors` (`readonly EnvironmentDescriptor[]`): The kinds the host lists.

**Returns** `EnvironmentDescriptor[]`

Source: [ui/src/git/headless/environment.ts:55](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/environment.ts#L55)

## Constants

### `DEFAULT_GIT_LABELS`

Constant.

The default English strings of the git components.

```ts
const DEFAULT_GIT_LABELS: { gitAhead: (count: number) => string; gitApproved: string; gitAuthorLabel: (author: string) => string; gitBehind: (count: number) => string; gitBranch: string; gitBranchButton: (branch: string) => string; gitBranchChipLabel: (branch: string) => string; gitBranchDetached: (commit: string) => string; gitBranchHint: string; gitBranchPlaceholder: string; gitBranchSwitch: string; gitBranchSwitchLater: string; gitChangesRequested: string; gitChangesTooltip: string; gitChecksLabel: (checks: Checks) => string; gitChecksText: (checks: Checks) => string; gitCommitsAhead: (count: number, base: string | null) => string; gitCommitsBehind: (count: number) => string; gitCopyBranch: string; gitDefaultBranch: string; gitDontAskAgain: string; gitDraft: string; gitDriftLabel: (ahead: number, behind: number) => string; gitEnvironmentSettings: string; gitFactsThen: (facts: string, action: string) => string; gitFilesUnit: (count: number) => ' file' | ' files'; gitFolderBackToRoots: string; gitFolderCancel: string; gitFolderCreate: string; gitFolderCreating: string; gitFolderDefault: string; gitFolderDefaultTitle: (host: string) => string; gitFolderEmpty: string; gitFolderFilter: string; gitFolderFilterLabel: string; gitFolderNew: string; gitFolderNewName: string; gitFolderNewNameLabel: (parent: string) => string; gitFolderNoMatch: string; gitFolderOpenPath: (path: string) => string; gitFolderPathLabel: string; gitFolderPickerLabel: (host: string) => string; gitFolderReading: string; gitFolderRoots: string; gitFolderSearchDeeper: (query: string) => string; gitFolderSearching: string; gitFolderSearchNone: string; gitFolderSearchResults: string; gitFolderSearchTruncated: string; gitFolderTitle: (folder: string, host: string) => string; gitFolderUse: (name: string) => string; gitFork: string; gitFromHere: string; gitHostLocalDescription: string; gitHostServerDescription: string; gitImportArchived: string; gitImportCancel: string; gitImportChange: string; gitImportClone: string; gitImportCloning: string; gitImportConnecting: string; gitImportField: string; gitImportHintAfter: string; gitImportHintBefore: string; gitImportHintCode: string; gitImportInto: string; gitImportInvalid: string; gitImportPlaceholder: string; gitImportPreview: (label: string, branch: string | undefined, destination: string) => string; gitImportPrivate: string; gitImportProgress: (phase: string, percent: number) => string; gitImportStars: (stars: number) => string; gitImportStop: string; gitImportTitle: string; gitImportViewOnGithub: string; gitIsolation: string; gitIsolationDefault: string; gitLastCommitAge: (age: string, duration: boolean) => string; gitListLabel: string; gitLoadingBranches: string; gitLocal: string; gitLocalLabel: string; gitMachineDescription: (name: string) => string; gitMachineOffline: (name: string) => string; gitMachineStatus: (status: string) => string; gitMenuLabel: string; gitMore: (count: number) => string; gitMoreSearchHint: string; gitMoveBack: string; gitMoveBranch: string; gitMoveCancel: string; gitMoveChangeFolder: string; gitMoveConfirm: (name: string) => string; gitMoveConfirmDetail: string; gitMoveCurrent: string; gitMoveDone: string; gitMoveFolder: string; gitMoveKeepFolder: string; gitMoveLoading: string; gitMoveMainCheckout: string; gitMoveMoving: string; gitMoveNone: string; gitMoveOffline: string; gitMovePickFolder: (name: string) => string; gitMoveRemoveWorktree: string; gitMovesThisChat: string; gitMoveSubmit: string; gitMoveTitle: string; gitMoveWhere: string; gitMoveWorktreeKept: (reason: string | undefined) => string; gitNoGh: string; gitNoMatches: string; gitOpenOnGitHub: string; gitOpenPullRequest: (number: number) => string; gitPrDraft: string; gitPrTooltip: (pr: { draft: boolean; number: number; title: string }) => string; gitPublish: string; gitPublishBranch: (branch: string) => string; gitPublishDialog: string; gitPublishing: string; gitPublishLater: string; gitPublishSummary: (branch: string, ahead: number, remote: string | null) => string; gitPublishTo: (remote: string | null) => string; gitRateLimited: (clock: string) => string; gitRowCurrent: string; gitRowSwitching: string; gitRunsOn: string; gitRunsOnHelpLabel: string; gitRunsOnLocal: string; gitRunsOnLocalFact: string; gitRunsOnMachine: string; gitRunsOnMachineFact: string; gitRunsOnServer: string; gitRunsOnServerFact: string; gitSearching: string; gitSearchLabel: string; gitSearchPlaceholder: string; gitSectionBranches: string; gitSectionMine: string; gitSectionOther: string; gitSectionPullRequests: string; gitSectionReview: string; gitStartAsWorktree: string; gitStartBranch: string; gitStartBranchLabel: (name: string) => string; gitStartCheckedOutElsewhere: (path: string) => string; gitStartingWorktree: string; gitStartNoWorktree: string; gitStartTheWorktree: string; gitStartWorktree: string; gitStartWorktreeLabel: (name: string) => string; gitSync: string; gitSyncCancel: string; gitSyncDialog: string; gitSyncing: string; gitSyncKeepsChanges: string; gitSyncLater: string; gitSyncSummary: (behind: number, ahead: number, upstream: string) => string; gitSyncWith: (upstream: string | null) => string; gitToPull: (count: number) => string; gitToPush: (count: number) => string; gitUnavailable: string; gitUpdatedAge: (age: string, duration: boolean) => string; gitUpToDate: (upstream: string) => string; gitWhereLabel: string; gitWhereTitle: (place: string, isolation: string | undefined, branch: string | undefined) => string; gitWorktreeBranchLabel: string; gitWorktreeBranchPlaceholder: string; gitWorktreeShort: string }
```

Source: [ui/src/git/headless/labels.ts:15](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/labels.ts#L15)

### `SWITCHER_SECTIONS`

Constant.

The sections in order, and how many rows each shows until searched or expanded.

```ts
const SWITCHER_SECTIONS: readonly { cap: number; id: SwitcherSectionId }[]
```

Source: [ui/src/git/headless/switcher.ts:21](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L21)

## Interfaces

### `DraftEnvironment`

Interface.

What the user picked in a draft; `null` where it is used = the configured default.

```ts
interface DraftEnvironment
```

**Properties**

- `branch` (`string`): Typed branch; empty = the suggested one.
- `checkout?` (`EnvironmentCheckout`): Work on `branch` as it is (a pull request's or a ticket's branch) rather than cutting it: set by a panel's
  "Open in worktree". Picking another environment or typing a branch drops it.
- `kind` (`string`): The environment kind (`local`, `worktree`, `local@laptop`, …).

Source: [ui/src/git/headless/environment.ts:17](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/environment.ts#L17)

### `DraftRemoteClone`

Interface.

The local project's repository, as a new session on a server would clone it.

```ts
interface DraftRemoteClone
```

**Properties**

- `input` (`string`): What the server clones: this computer's `origin` URL, as written.
- `name` (`string`): The folder it lands in: the repository's name.
- `parent` (`string`): Where that folder goes: the server's first workspace root.
- `state` (`'off' | 'clone' | 'exists'`): `clone`: the server clones it on send. `exists`: a folder of that name is already there (used as it is when
  it holds the same repository). `off`: the server takes no clones: nothing is cloned, the send uses its first root.

Source: [ui/src/git/headless/remote-clone.ts:17](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/remote-clone.ts#L17)

### `GitBranch`

Interface.

A local branch: when it last moved, and how it stands against the default branch.

```ts
interface GitBranch
```

**Properties**

- `isDefault` (`boolean`): It is the repository's default branch.
- `name` (`string`): The branch name.
- `stats?` (`{ added: number; ahead: number; behind: number; removed: number }`): Against the default branch. Absent: not computed (a repository with many branches computes the recent ones).
- `updatedAt` (`number`): Last commit time (epoch ms).

Source: [ui/src/git/headless/host.ts:17](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L17)

### `GitBranchPullRequest`

Interface.

The current branch's open (or draft) pull request.

```ts
interface GitBranchPullRequest
```

**Properties**

- `draft` (`boolean`): A draft.
- `number` (`number`): The pull request's number.
- `title` (`string`): Its title (may be empty).
- `url` (`string`): Its page.

Source: [ui/src/git/headless/host.ts:118](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L118)

### `GitClone`

Interface.

Importing a repository: parse what was pasted, pick where it lands, clone it.

```ts
interface GitClone
```

**Properties**

- `cancel?` (`() => Promise<void>`): Stops the clone in flight; the host removes the half-cloned folder. Absent: a clone runs to its end.
- `clone` (`(input: string, parent: string) => Promise<GitCloneResult>`): Clones `input` into a new folder of `parent`.
- `defaultParent` (`() => Promise<string>`): Where the next clone lands by default.
- `info?` (`(input: string) => Promise<GitRepoInfo | null>`): What a repository is (a GitHub one's description, stars, avatar, preview image); `null` when unknown. Absent: the dialog shows the parse alone.
- `onProgress?` (`(onProgress: (progress: GitCloneProgress) => void) => () => void`): Calls `onProgress` while a clone runs. Returns the unsubscribe. Absent: no progress bar figures.
- `parse` (`(input: string) => GitRepoSpec | null`): Reads a git or forge URL (or `owner/repo`): exactly what `clone` would clone; `null` when it is not one.

Source: [ui/src/git/headless/host.ts:186](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L186)

### `GitCloneProgress`

Interface.

A clone's progress, as git reports it.

```ts
interface GitCloneProgress
```

**Properties**

- `percent` (`number`): 0 to 100.
- `phase` (`string`): `Receiving objects`, `Resolving deltas`, …

Source: [ui/src/git/headless/host.ts:174](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L174)

### `GitCreateFolderQuery`

Interface.

Where `GitHost.createFolder` creates a folder.

```ts
interface GitCreateFolderQuery
```

**Properties**

- `hostId?` (`string`): The saved server (hosts that reach several).
- `name` (`string`): Its name: one path segment.
- `parent` (`string`): The folder it goes in.

Source: [ui/src/git/headless/host.ts:276](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L276)

### `GitEnvironmentQuery`

Interface.

What `GitHost.environments` lists kinds for.

```ts
interface GitEnvironmentQuery
```

**Properties**

- `cwd?` (`string`): The folder a new session would start in.
- `hostId?` (`string`): The saved server the session would run on (absent: this host).

Source: [ui/src/git/headless/host.ts:221](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L221)

### `GitFolderAllows`

Interface.

What a remote host lets clients do in its folders.

```ts
interface GitFolderAllows
```

**Properties**

- `clone` (`boolean`): Clone a repository there (`GitHost.cloneOnServer`).
- `createFolders` (`boolean`): Create a folder (`GitHost.createFolder`).
- `searchFolders?` (`boolean`): Search the folders there (`GitHost.searchFolders`). Absent: offered when the host has `searchFolders`.

Source: [ui/src/git/headless/host.ts:249](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L249)

### `GitFolderEntry`

Interface.

One folder in a [`GitFolderListing`](https://zidane.si/docs/reference/ui-git-headless.md#GitFolderListing).

```ts
interface GitFolderEntry
```

**Properties**

- `isGitRepo` (`boolean`): Holds a `.git`.
- `name` (`string`): Folder name.
- `path` (`string`): Its path.

Source: [ui/src/git/headless/host.ts:239](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L239)

### `GitFolderListing`

Interface.

The folders in one folder of a remote host.

```ts
interface GitFolderListing
```

**Properties**

- `allows?` (`GitFolderAllows`): What the host lets clients do there. Absent: the host does not say (a shared machine): neither is offered.
- `dirs` (`readonly GitFolderEntry[]`): Its folders, sorted by name.
- `parent` (`string | null`): The folder above, or `null` at a root.
- `path` (`string`): The listed folder.
- `roots` (`readonly string[]`): The roots a session's folder must be inside.

Source: [ui/src/git/headless/host.ts:259](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L259)

### `GitFolderQuery`

Interface.

Where `GitHost.listFolders` lists.

```ts
interface GitFolderQuery
```

**Properties**

- `hostId?` (`string`): The saved server whose folders to list (hosts that reach several).
- `machineId?` (`string`): A machine shared with that host: its folders instead.
- `path?` (`string`): The folder to list. Absent: the first root.

Source: [ui/src/git/headless/host.ts:229](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L229)

### `GitFolderSearchQuery`

Interface.

What `GitHost.searchFolders` looks for.

```ts
interface GitFolderSearchQuery
```

**Properties**

- `hostId?` (`string`): The saved server (hosts that reach several).
- `path?` (`string`): Where to search, and below it. Absent: every root.
- `query` (`string`): Part of a folder's name, any case.

Source: [ui/src/git/headless/host.ts:289](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L289)

### `GitHost`

Interface.

The git area's host. Leave a member out and what needs it is not shown.

```ts
interface GitHost
```

**Properties**

- `clone?` (`GitClone`): Clones a repository into a new folder. Absent: no repository import.
- `branches?` (`(cwd: string) => Promise<readonly GitBranch[]>`): Local branches, most recently committed first. Absent: no branch menu.
- `branchPullRequest?` (`(cwd: string, branch: string, fresh?: boolean) => Promise<GitBranchPullRequest | null>`): The open pull request of `branch`, or `null`. `fresh`: past any cache the host keeps. Absent: not shown.
- `checkout?` (`(cwd: string, target: GitCheckoutTarget, sessionId?: string | null) => Promise<GitCheckoutResult>`): Switches the checkout. Never forced: git's refusal comes back as the error. Absent: no branch menu.
- `cloneOnServer?` (`(hostId: string, input: string, parent: string) => Promise<GitCloneResult>`): Clones `input` into a new folder of `parent` on a saved server. Absent: no clone on send.
- `createBranch?` (`(cwd: string, name: string, sessionId?: string | null) => Promise<GitCheckoutResult>`): Starts a branch from the current checkout and switches to it. Absent: a typed name is not offered to start.
- `createFolder?` (`(query: GitCreateFolderQuery) => Promise<GitCreateFolderResult>`): Creates a folder on a remote host (not on a shared machine). Absent: no "New folder" in the folder picker.
- `environments?` (`(query: GitEnvironmentQuery) => Promise<readonly EnvironmentDescriptor[]>`): The environment kinds a new session can run in. Absent: the app supplies them itself.
- `listFolders?` (`(query: GitFolderQuery) => Promise<GitFolderResult>`): The folders of a remote host. Absent: no remote folder picker.
- `moveSession?` (`(sessionId: string, target: GitMoveTarget) => Promise<GitMoveResult>`): Moves an idle session to another environment of its host, in `target.cwd` (a folder on the target; required for a
  machine's kinds). Nothing is copied; the session's terminals and background tasks stop. Absent: no "Move to…".
- `originUrl?` (`(cwd: string) => Promise<string | null>`): The `origin` URL of the checkout holding `cwd` on this computer; `null` outside git or without `origin`. Absent: no clone on send.
- `pickFolder?` (`() => Promise<string | null>`): Picks a folder on this computer (a native dialog); `null` when cancelled. Absent: no local folder picking.
- `pullRequests?` (`(query: GitPullRequestQuery) => Promise<GitPullRequestList>`): Open pull requests: waiting on you, yours, then recent others. Absent: the branch menu lists branches only.
- `searchFolders?` (`(query: GitFolderSearchQuery) => Promise<GitFolderSearchResult>`): Searches a remote host's folders by name (not a shared machine's). Absent: the folder picker filters the folder it shows only.
- `startWorktree?` (`(sessionId: string, branch?: string) => Promise<GitActionResult>`): Moves a local session into a new git worktree on `branch` (absent: the suggested one). Absent: no "Start a worktree".
- `status?` (`(cwd: string) => Promise<GitStatus | null>`): Where the checkout stands; `null` outside a git checkout. Absent: not shown.
- `subscribeActivity?` (`(sessionId: string, onChange: () => void) => () => void`): Calls `onChange` when a session's own work may have changed its checkout (a tool call finished, a command ended
  in one of its terminals). Returns the unsubscribe. Absent: the status refreshes on ref moves, focus and a timer.
- `subscribeEnvironments?` (`(query: GitEnvironmentQuery, onChange: () => void) => () => void`): Calls `onChange` when what `GitHost.environments` lists for `query` may have changed (environment settings
  edited, a reconnect). Returns the unsubscribe. Absent: the kinds are read once per folder and host.
- `subscribeRefs?` (`(cwd: string, onChange: () => void) => () => void`): Calls `onChange` when the checkout's refs move (a commit, fetch, push, switch). Returns the unsubscribe. Absent: lists refresh when reopened.
- `sync?` (`(cwd: string, sessionId?: string | null) => Promise<GitSyncResult>`): Pulls (merging) then pushes the current branch, or publishes it when it has no upstream. Absent: no sync.

Source: [ui/src/git/headless/host.ts:303](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L303)

### `GitMoveTarget`

Interface.

Where `GitHost.moveSession` moves a session.

```ts
interface GitMoveTarget
```

**Properties**

- `branch?` (`string`): The branch, for a kind that takes one. Absent: the suggested one.
- `cwd?` (`string`): The folder on the target. Absent: the session keeps its folder (not for a machine's kinds).
- `kind` (`string`): The environment kind (`local`, `worktree`, `local@gpu`, …).
- `removeOldWorktree?` (`boolean`): Remove the worktree the session leaves, when it has no uncommitted changes (the branch stays). Only for a session
  in a worktree; one that would keep the worktree as its folder goes to the main checkout. Absent: kept.

Source: [ui/src/git/headless/host.ts:202](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L202)

### `GitPullRequest`

Interface.

An open pull request.

```ts
interface GitPullRequest
```

**Properties**

- `additions` (`number`): Lines added.
- `author` (`string`): Its author's login.
- `branch` (`string`): Its head branch.
- `checks` (`'pending' | 'pass' | 'fail' | null`): The checks' verdict, `null` when there are none.
- `deletions` (`number`): Lines removed.
- `draft` (`boolean`): A draft.
- `files` (`number`): Files changed.
- `fork` (`boolean`): Opened from a fork (checked out by number, never by branch name).
- `group` (`'other' | 'mine' | 'review'`): Yours, waiting on your review, or anyone else's.
- `local` (`boolean`): Its branch exists locally (a plain switch; otherwise a checkout by number).
- `number` (`number`): The pull request's number.
- `review` (`'required' | 'approved' | 'changes' | null`): The review verdict, `null` when there is none.
- `title` (`string`): Its title.
- `updatedAt` (`number`): Last update (epoch ms).
- `url` (`string`): Its page.

Source: [ui/src/git/headless/host.ts:29](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L29)

### `GitPullRequestQuery`

Interface.

What `GitHost.pullRequests` lists.

```ts
interface GitPullRequestQuery
```

**Properties**

- `cwd` (`string`): The checkout.
- `fresh?` (`boolean`): Past any cache the host keeps.
- `search?` (`string`): Searches every open pull request (number, title, branch, author). Absent: the recent ones.

Source: [ui/src/git/headless/host.ts:63](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L63)

### `GitRepoInfo`

Interface.

What the import dialog shows about a GitHub repository before cloning it (`GitClone.info`).

```ts
interface GitRepoInfo
```

**Properties**

- `archived?` (`boolean`): Read-only on GitHub.
- `avatarUrl` (`string`): The owner's avatar.
- `defaultBranch` (`string`): The branch a clone checks out.
- `description?` (`string`): Its description.
- `imageUrl` (`string`): The preview image GitHub draws for links to it.
- `language?` (`string`): Its main language.
- `owner` (`string`): The owner, as GitHub spells it.
- `private?` (`boolean`): Only people with access see it.
- `repo` (`string`): The repository, as GitHub spells it.
- `stars` (`number`): Its stars.
- `url` (`string`): Its page.

Source: [ui/src/git/headless/host.ts:148](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L148)

### `GitRepoSpec`

Interface.

What a pasted repository is, as `GitClone.parse` reads it.

```ts
interface GitRepoSpec
```

**Properties**

- `branch?` (`string`): A branch named in a web URL, cloned instead of the default one.
- `cloneUrl` (`string`): What `git clone` receives.
- `label` (`string`): `owner/repo` on a known forge, else host and path.
- `name` (`string`): The folder it lands in: the repository's last path segment.

Source: [ui/src/git/headless/host.ts:136](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L136)

### `GitStatus`

Interface.

Where a checkout stands.

```ts
interface GitStatus
```

**Properties**

- `ahead` (`number`): Commits on HEAD not on the base (the upstream, else the default branch).
- `behind` (`number`): Commits on the base not on HEAD.
- `branch` (`string`): Current branch; the short commit when `detached`.
- `changes` (`{ added: number; files: number; removed: number }`): Uncommitted changes against HEAD, untracked files included.
- `defaultBranch` (`string | null`): `origin/main`-style ref; `null` when none resolves.
- `detached` (`boolean`): HEAD is not on a branch.
- `publishRemote` (`string | null`): A remote the branch can be published to, when it has no upstream yet.
- `upstream` (`string | null`): The branch's remote copy; `null` when it has none.

Source: [ui/src/git/headless/host.ts:98](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L98)

### `MoveChoice`

Interface.

One kind a session can move to.

```ts
interface MoveChoice
```

**Properties**

- `descriptor` (`EnvironmentDescriptor`): The descriptor the host listed.
- `name` (`string`): What the menu and the confirmation call it: the machine's name for a machine's kind, else the kind's label.
- `needsFolder` (`boolean`): A folder must be picked on the target: a machine's kind, or the session's folder is on a machine.
- `pickable` (`boolean`): It can be picked now.
- `reason?` (`string`): Why it cannot (an offline machine, an unavailable kind).

Source: [ui/src/git/headless/move.ts:47](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/move.ts#L47)

### `MoveSessionSubject`

Interface.

The session being moved.

```ts
interface MoveSessionSubject
```

**Properties**

- `cwd` (`string`): Its folder (`''` for a chat without one).
- `hasTurns?` (`boolean`): It has turns: the move is confirmed first (the agent keeps its history). Default: `true`.
- `hostId?` (`string`): The saved server it is on; absent: this computer.
- `kind?` (`string`): Its environment kind now; absent: `local`.
- `sessionId` (`string`): The session's key.

Source: [ui/src/git/headless/move.ts:12](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/move.ts#L12)

### `SwitcherCache`

Interface.

The branch menu's last lists per folder, so a reopened menu shows them while it refreshes.

```ts
interface SwitcherCache
```

**Properties**

- `branches` (`(cwd: string) => readonly GitBranch[] | undefined`): The branches last listed for `cwd`.
- `hasPullRequests` (`(cwd: string) => boolean`): Whether pull requests were listed for `cwd`.
- `pullRequests` (`(cwd: string) => readonly GitPullRequest[] | null | undefined`): The pull requests last listed for `cwd`, `null` when the host could not reach them.
- `setBranches` (`(cwd: string, list: readonly GitBranch[]) => void`): Keeps the branches listed for `cwd`.
- `setPullRequests` (`(cwd: string, list: readonly GitPullRequest[] | null) => void`): Keeps the pull requests listed for `cwd`.

Source: [ui/src/git/headless/switcher.ts:175](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L175)

### `SwitcherSection`

Interface.

A section as shown: every row it holds, the ones shown, and how many wait behind "more".

```ts
interface SwitcherSection
```

**Properties**

- `all` (`SwitcherEntry[]`): Every row it holds for the query.
- `cap` (`number`): Rows shown until searched or expanded.
- `hidden` (`number`): Rows behind "more".
- `id` (`SwitcherSectionId`): Which section.
- `shown` (`SwitcherEntry[]`): The rows shown.

Source: [ui/src/git/headless/switcher.ts:29](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L29)

## Types

### `EnvironmentMachine`

Type.

A machine shared with the draft's host, as an environment descriptor names it.

```ts
type EnvironmentMachine = NonNullable<EnvironmentDescriptor['machine']>
```

Source: [ui/src/git/headless/environment.ts:30](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/environment.ts#L30)

### `GitActionResult`

Type.

What a call that only succeeds or fails answered.

```ts
type GitActionResult = { ok: true } | { error: GitHostError; ok: false }
```

Source: [ui/src/git/headless/host.ts:91](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L91)

### `GitCheckoutResult`

Type.

What a switch answered. A branch another worktree holds says where, and the chats in that checkout.

```ts
type GitCheckoutResult =
  | { ok: true }
  | { error: GitHostError; ok: false; worktree?: { chats: readonly string[]; path: string } }
```

Source: [ui/src/git/headless/host.ts:94](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L94)

### `GitCheckoutTarget`

Type.

What to switch to: a local branch, or a pull request by number.

```ts
type GitCheckoutTarget = { branch: string } | { pullRequest: number }
```

Source: [ui/src/git/headless/host.ts:81](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L81)

### `GitCloneResult`

Type.

What a clone answered. `existed`: the folder already held that repository, so it was opened, not cloned.

```ts
type GitCloneResult =
  | { existed?: boolean; ok: true; path: string }
  | { cancelled: true; ok: false }
  | { error: GitHostError; ok: false }
```

Source: [ui/src/git/headless/host.ts:182](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L182)

### `GitCreateFolderResult`

Type.

What `GitHost.createFolder` answered.

```ts
type GitCreateFolderResult =
  | { folder: GitFolderEntry; ok: true }
  | { error: GitHostError; ok: false }
```

Source: [ui/src/git/headless/host.ts:286](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L286)

### `GitFolderResult`

Type.

What `GitHost.listFolders` answered.

```ts
type GitFolderResult =
  | { listing: GitFolderListing; ok: true }
  | { error: GitHostError; ok: false }
```

Source: [ui/src/git/headless/host.ts:273](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L273)

### `GitFolderSearchResult`

Type.

What `GitHost.searchFolders` answered. `truncated`: the host's bounds cut the search short.

```ts
type GitFolderSearchResult =
  | { ok: true; results: readonly GitFolderEntry[]; truncated: boolean }
  | { error: GitHostError; ok: false }
```

Source: [ui/src/git/headless/host.ts:299](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L299)

### `GitHostError`

Type.

Why a host call failed, for the components to word through their labels.

```ts
type GitHostError = { code: 'unavailable' } | { code: 'failed'; message: string }
```

Source: [ui/src/git/headless/host.ts:84](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L84)

### `GitLabels`

Type.

The shape of the git label dictionary.

```ts
type GitLabels = typeof DEFAULT_GIT_LABELS
```

Source: [ui/src/git/headless/labels.ts:219](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/labels.ts#L219)

### `GitMoveResult`

Type.

What `GitHost.moveSession` answered. `oldWorktree`: what happened to the worktree it was asked to remove.

```ts
type GitMoveResult =
  | { ok: true; oldWorktree?: { reason?: string; removed: boolean } }
  | { error: GitHostError; ok: false }
```

Source: [ui/src/git/headless/host.ts:217](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L217)

### `GitPullRequestList`

Type.

The pull requests of a checkout, or why there are none to show.

```ts
type GitPullRequestList =
  | { items: readonly GitPullRequest[]; kind: 'list' }
  | { kind: 'unavailable' }
  | { kind: 'rate-limited'; retryAt: number }
```

Source: [ui/src/git/headless/host.ts:73](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L73)

### `GitSyncAction`

Type.

What a click on the sync chip does.

```ts
type GitSyncAction = 'sync' | 'publish'
```

Source: [ui/src/git/headless/sync.ts:13](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/sync.ts#L13)

### `GitSyncResult`

Type.

What a sync (pull, merging, then push) or a publish answered.

```ts
type GitSyncResult =
  | { ok: true; published: boolean; pulled: number; pushed: number }
  | { conflicts?: readonly string[]; error: GitHostError; ok: false }
```

Source: [ui/src/git/headless/host.ts:130](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/host.ts#L130)

### `SwitcherEntry`

Type.

A row of the branch menu.

```ts
type SwitcherEntry =
  | { kind: 'pr'; pr: GitPullRequest }
  | { kind: 'branch'; row: GitBranch }
  | { kind: 'create'; name: string; worktree: boolean }
```

Source: [ui/src/git/headless/switcher.ts:12](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L12)

### `SwitcherSectionId`

Type.

A section of the branch menu.

```ts
type SwitcherSectionId = GitPullRequest['group'] | 'branches'
```

Source: [ui/src/git/headless/switcher.ts:18](https://github.com/Tahul/zidane/blob/main/ui/src/git/headless/switcher.ts#L18)