Utility: cd - change current location

Status: Built + QEMU-verified (osdev test files 11/11) - a shell built-in; the current location lives in the shell session, which resolves relative / . / .. paths to an absolute path before calling fs (validates the target via STAT). On hierarchical GSFS (docs/persistence.md). Trails CLAUDE.md; does not amend it.

1. What it is

cd moves the current location - the single pointer that says where you are. Because GSFS is hierarchical, "where you are" is one address: a drive + directory. cd takes a full drive-qualified path, so it is the only location pointer - there is no separate "current drive" verb (no mount, no drives use; see 15_drives.md §3.1/§3.2 for why those POSIX reflexes were dropped). cd is kept as a verb (universal, not cryptic).

2. Usage

cd 0.4.0 - change current directory

usage:
  cd <path>           move to <path>
  cd                  go home, /users/default - the same as `home` (in a script, $home)
  cd ..               go up one folder (`..` works in any path: read ../notes.txt)
  cd -                move to the previous directory
  cd version          print the version
  cd help             print this message

<path> = [index:]label/path | /abs | rel | ..   (see docs/drives.md §4.1)

Examples:

cd 1:data/projects   current = drive 1 (data), dir /projects
cd /etc              current drive, absolute path
cd ../bin            relative, up one
cd archive           the 'archive' drive's root

3. The current location (session state)

The current location lives in the shell session - the shell prefixes it onto relative paths before sending requests to fs, so fs always receives a resolved address. A session starts in its home, /users/default/ (docs/filesystem-layout.md 6), which drives flash makes. The prompt is a plain gsh> and does not show it; pwd does (62_pwd.md). The session also remembers the previous location (a one-slot history) so cd - can toggle back. Both are session state: they do not persist across boots in the first cut. A persistent "start here" working default is deferred (15_drives.md §5/§3.2) - decided alongside multi-drive, not invented now.

4. Implementation

A shell built-in: it resolves the target, Stats it through fs (op 12) to confirm it exists and is a directory, and updates the session pointer. Read-only on disk. cd - reuses the saved previous absolute path and runs the same stat-validated switch (so a since-deleted previous directory errors loudly rather than silently failing); each successful cd saves the directory it left, so cd - twice returns you where you started. A successful cd prints the new location; cd with no argument goes home, and cd / to the root, which is never stat'd because the root always exists.

5. Later (separate doc so it can grow)

• cd with no argument is done: it goes home, /users/default/ (changed 2026-10-13 from /, with the layout, docs/filesystem-layout.md 6). There is no ~: in a script, home is the reserved word $home, which cannot collide with a folder named home. At the prompt $home is not expanded - variables are a script feature, and a typed line is not a script - so cd alone is the way home there. .. goes up one folder, in cd and in every path (read ../notes.txt). It is kept as it is, not renamed (cd up was considered, 2026-10-13): Unix, DOS and Windows all spell it .., so it is already known, and a word like up could be the name of a real folder where .. cannot. Tab-completion of path components is done too (complete_path, 0_conventions.md rule 9).

6. Conformance

Conforms: cd help (usage with a real example per row) and cd version (number + creator credit) per 0_conventions.md (the shared help_block helper).

Conforms to rule 10 (0_conventions.md §1.10) since 2026-10-13 (backlog/fixed/89). It found 2026-10-09 that the fs handle was lent no notice; every fs handle the shell makes is now lent the command's watch (gs::call::Watch), so the command says [q] quit once it has run 2 s, and q, Q or ESC leaves the location unchanged (osdev test quit measures cd /q/tree/a on a slowed fs).