# rupa/z architecture

> Architecture diagram of the GitHub repository rupa/z, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rupa/z
- Repository: https://github.com/rupa/z

## Overview

Z is a shell utility that learns directory usage and lets users jump to matching directories by frecency, rank, or recency. Its documented workflow is: shell prompt hooks maintain a data file; the user invokes `z` with optional regexes and flags; Z selects or lists matching directories and may change the shell’s current directory. Completion is a separate documented capability. Source excerpts were unavailable, so relationships below are supported by the README only.

Main entry points: [`z.sh`](https://github.com/rupa/z/blob/master/z.sh) (Z command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tracking["Directory tracking"]
  node_prompt_hook["Prompt hook<br/>[z.sh]"]
  node_directory_tracker["Directory tracker<br/>[z.sh]"]
  node_directory_data[("Directory data<br/>[z.sh]")]
end

subgraph group_navigation["Directory navigation"]
  node_z_command["Z command<br/>[z.sh]"]
  node_matching["Regex matching<br/>[z.sh]"]
  node_frecency["Frecency ranking<br/>[z.sh]"]
  node_result_action["Result action<br/>[z.sh]"]
end

subgraph group_completion["Shell completion"]
  node_tab_completion["Tab completion<br/>[z.sh]"]
end

node_user(("User"))
node_shell["Interactive shell"]

node_user -->|"invokes"| node_z_command
node_shell -->|"runs prompt hook"| node_prompt_hook
node_prompt_hook -->|"tracks directories"| node_directory_tracker
node_directory_tracker -->|"updates"| node_directory_data
node_z_command -->|"reads"| node_directory_data
node_z_command -->|"passes queries"| node_matching
node_matching -->|"ranks matches"| node_frecency
node_z_command -->|"selects or lists"| node_result_action
node_result_action -->|"changes directory"| node_shell
node_user -->|"requests completion"| node_tab_completion
node_tab_completion -->|"completes matches"| node_matching

click node_prompt_hook "https://github.com/rupa/z/blob/master/z.sh"
click node_directory_tracker "https://github.com/rupa/z/blob/master/z.sh"
click node_directory_data "https://github.com/rupa/z/blob/master/z.sh"
click node_z_command "https://github.com/rupa/z/blob/master/z.sh"
click node_matching "https://github.com/rupa/z/blob/master/z.sh"
click node_frecency "https://github.com/rupa/z/blob/master/z.sh"
click node_result_action "https://github.com/rupa/z/blob/master/z.sh"
click node_tab_completion "https://github.com/rupa/z/blob/master/z.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_prompt_hook,node_directory_tracker,node_directory_data,node_user toneBlue
class node_z_command,node_matching,node_frecency,node_result_action toneAmber
class node_tab_completion toneMint
class node_shell toneIndigo
```

## Components

### Directory tracking

- [Prompt hook](https://github.com/rupa/z/blob/master/z.sh): `z.sh`
- [Directory tracker](https://github.com/rupa/z/blob/master/z.sh): `z.sh`
- [Directory data](https://github.com/rupa/z/blob/master/z.sh): `z.sh`

### Directory navigation

- [Z command](https://github.com/rupa/z/blob/master/z.sh): `z.sh`
- [Regex matching](https://github.com/rupa/z/blob/master/z.sh): `z.sh`
- [Frecency ranking](https://github.com/rupa/z/blob/master/z.sh): `z.sh`
- [Result action](https://github.com/rupa/z/blob/master/z.sh): `z.sh`

### Shell completion

- [Tab completion](https://github.com/rupa/z/blob/master/z.sh): `z.sh`

### Other components

- **User**
- **Interactive shell**

## Connections

- User → Z command: invokes (evidence: `README`)
- Interactive shell → Prompt hook: runs prompt hook (evidence: `README`)
- Prompt hook → Directory tracker: tracks directories (evidence: `README`)
- Directory tracker → Directory data: updates (evidence: `README`)
- Z command → Directory data: reads (evidence: `README`)
- Z command → Regex matching: passes queries (evidence: `README`)
- Regex matching → Frecency ranking: ranks matches (evidence: `README`)
- Z command → Result action: selects or lists (evidence: `README`)
- Result action → Interactive shell: changes directory (evidence: `README`)
- User → Tab completion: requests completion (evidence: `README`)
- Tab completion → Regex matching: completes matches (evidence: `README`)
