Reference: project tree

Neutral description of the project tree window: what it shows, what it hides, and the keys it answers to.

Opening

Route	Condition
`F9`	Always
Window ▸ Project tree	Always

Neither requires a file to be open. Both bring the existing tree forward when one is already open: there is at most one tree window.

Root

Property	Value
Rooted at	The directory the editor was started in (`os.Getwd()`)
Search	That directory only. Parent directories are not searched, the same rule `.turbo-rust/settings.toml` follows.
Window title	The base name of that directory
Root row	Not shown; the first row is the first entry inside the project

What is listed

Rule	Detail
Order	Directories first, then files; each group sorted by name
Hidden	`.git` only
Shown	Every other entry, dot-entries included — `.turbo-rust`, `.gitignore`, `.qlty`
Reading	A directory is read the first time it is expanded, and not before
Unreadable directory	Shows as expanded and empty; the rest of the tree is unaffected

Markers

Marker	Meaning
`▶`	A directory that is closed
`▼`	A directory that is open
(two spaces)	A file — indented by a marker's width so names line up

Each level of depth adds two more spaces of indentation.

Keys

Handled when the tree window has the focus.

Key	Action
`↑` `↓`	Previous / next row
`PgUp` `PgDn`	A screenful at a time
`Home` `End`	First / last row
`→`	Expand a closed directory; otherwise move to the next row
`←`	Collapse an open directory; otherwise move to the directory this row is in
`Enter`	Open a file; expand or collapse a directory
`F5`, `Ctrl-R`	Re-read the project

The editor's own shortcuts apply as usual: F6 moves to the next window, Ctrl-W closes the tree, Alt-X leaves.

Mouse

Action	Effect
Click a row	Move the highlight to it
Click the highlighted row	Act on it, as `Enter` does
Wheel up / down	Move the highlight three rows

Refreshing

Trigger	Effect
`F5` or `Ctrl-R`	Re-reads every directory that has been opened
Saving a file	The same, automatically
Expanding a directory	Reads that directory, if it has not been read

Refreshing keeps the shape of the tree: a directory that was open stays open, one that has been deleted takes its branch with it, and directories nobody has opened stay unread. The highlight stays on the same entry, or on the nearest remaining row when that entry has gone.

The tree does not watch the filesystem. A file created by a terminal window, or by git checkout, appears only after a refresh.

Colours

Theme key	What it colours
`tree.text`	A file's name, and the tree's background
`tree.directory`	A directory's name
`tree.selected`	The highlighted row, when the tree has the focus
`tree.unfocused`	The highlighted row, when it does not

These do not fall back to the list.* keys: dotted fallback runs along the dots and stops at default. See Theme file format.

Errors

Message	Cause
`Cannot tell which directory this is: …`	The working directory could not be read
`reading …: …`	The project directory could not be read
`… is not a directory`	The root resolved to a file

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102


# Reference: project tree

> Neutral description of the project tree window: what it shows, what it hides, and the keys it answers to.

## Opening

| Route | Condition |
| --- | --- |
| `F9` | Always |
| **Window ▸ Project tree** | Always |

Neither requires a file to be open. Both bring the existing tree forward when one is already open: there is at most one tree window.

## Root

| Property | Value |
| --- | --- |
| Rooted at | The directory the editor was started in (`os.Getwd()`) |
| Search | That directory only. Parent directories are **not** searched, the same rule `.turbo-rust/settings.toml` follows. |
| Window title | The base name of that directory |
| Root row | Not shown; the first row is the first entry inside the project |

## What is listed

| Rule | Detail |
| --- | --- |
| Order | Directories first, then files; each group sorted by name |
| Hidden | `.git` only |
| Shown | Every other entry, dot-entries included — `.turbo-rust`, `.gitignore`, `.qlty` |
| Reading | A directory is read the first time it is expanded, and not before |
| Unreadable directory | Shows as expanded and empty; the rest of the tree is unaffected |

## Markers

| Marker | Meaning |
| --- | --- |
| `▶ ` | A directory that is closed |
| `▼ ` | A directory that is open |
| (two spaces) | A file — indented by a marker's width so names line up |

Each level of depth adds two more spaces of indentation.

## Keys

Handled when the tree window has the focus.

| Key | Action |
| --- | --- |
| `↑` `↓` | Previous / next row |
| `PgUp` `PgDn` | A screenful at a time |
| `Home` `End` | First / last row |
| `→` | Expand a closed directory; otherwise move to the next row |
| `←` | Collapse an open directory; otherwise move to the directory this row is in |
| `Enter` | Open a file; expand or collapse a directory |
| `F5`, `Ctrl-R` | Re-read the project |

The editor's own shortcuts apply as usual: `F6` moves to the next window, `Ctrl-W` closes the tree, `Alt-X` leaves.

## Mouse

| Action | Effect |
| --- | --- |
| Click a row | Move the highlight to it |
| Click the highlighted row | Act on it, as `Enter` does |
| Wheel up / down | Move the highlight three rows |

## Refreshing

| Trigger | Effect |
| --- | --- |
| `F5` or `Ctrl-R` | Re-reads every directory that has been opened |
| Saving a file | The same, automatically |
| Expanding a directory | Reads that directory, if it has not been read |

Refreshing keeps the shape of the tree: a directory that was open stays open, one that has been deleted takes its branch with it, and directories nobody has opened stay unread. The highlight stays on the same entry, or on the nearest remaining row when that entry has gone.

The tree does **not** watch the filesystem. A file created by a terminal window, or by `git checkout`, appears only after a refresh.

## Colours

| Theme key | What it colours |
| --- | --- |
| `tree.text` | A file's name, and the tree's background |
| `tree.directory` | A directory's name |
| `tree.selected` | The highlighted row, when the tree has the focus |
| `tree.unfocused` | The highlighted row, when it does not |

These do not fall back to the `list.*` keys: dotted fallback runs along the dots and stops at `default`. See [Theme file format](themes.md).

## Errors

| Message | Cause |
| --- | --- |
| `Cannot tell which directory this is: …` | The working directory could not be read |
| `reading …: …` | The project directory could not be read |
| `… is not a directory` | The root resolved to a file |

## See also

- [How to browse a project and open files from a tree](../how-to/browse-a-project.md)
- [Project tree](../explanation/project-tree.md)
- [Keyboard](keyboard.md)