docs: add OSC-7 working-directory tracking documentation #2211
Conversation
|
|
WalkthroughA new FAQ section was added to the documentation, addressing how to make new tabs or splits inherit the shell’s current directory in Wave. The section explains the use of the OSC 7 escape sequence for tracking and propagating the working directory, and provides shell-specific configuration instructions for Bash, Zsh, and Fish. It also describes how to verify the functionality using 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
docs/docs/index.mdx (1)
70-76: Alphabetise or group reference links consistentlyThe new “Tracking Your Shell’s Working Directory” entry is inserted between Configuration and Custom Widgets, which keeps the list roughly alphabetical by title, but other sections historically group items by topic rather than strict alpha order. Double-check that the ordering logic you want is applied consistently across the whole list so future additions remain predictable.
docs/docs/track-cwd.mdx (3)
40-46: Zsh snippet: emit on prompt as wellHooking only
chpwdmeans the OSC 7 sequence isn’t sent when a command (e.g.,git checkout) changes the directory, or when you first get a prompt after Wave starts in a non-interactive shell startup. Consider also attaching toprecmd:add-zsh-hook precmd _wave_emit_cwdThat guarantees the escape is sent before every prompt.
58-65: Fish snippet: avoid duplicate emissionsBecause the
--on-variable PWDhandler already fires at startup, the explicit call to_wave_emit_cwdright after the function definition can double-emit the sequence. You can drop the explicit call:-# Emit on startup -_wave_emit_cwdMinor, but avoids redundant output.
67-88:wsh getmetaexample: clarify BlockId placeholderThe placeholder
<block-id>could be mistaken for literally requiring angle brackets. Add back-ticks or an explanatory note, e.g.:wsh getmeta --block <BLOCK_ID> # replace <BLOCK_ID> without the <>Small docs polish that prevents copy-paste errors.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/docs/index.mdx(1 hunks)docs/docs/track-cwd.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
docs/docs/track-cwd.mdx (1)
Learnt from: esimkowitz
PR: wavetermdev/waveterm#1790
File: cmd/wsh/cmd/wshcmd-readfile.go:34-34
Timestamp: 2025-01-22T01:04:20.614Z
Learning: Path sanitization in Wave Terminal is handled by individual fileshare client implementations rather than at the command level, as different file systems may have different path requirements and formats.
🔇 Additional comments (1)
docs/docs/track-cwd.mdx (1)
52-56: Fish version reference appears inaccurateFish is currently at major version 3; version 4.0.0 is not yet released. Stating that “Fish 4.0.0 and later emit OSC 7 by default” may confuse readers. Please verify the minimum version that ships OSC 7 (it’s 3.7+ at time of writing) or phrase it generically (“Fish releases after 3.7”).
docs/docs/track-cwd.mdx
Outdated
| ```bash | ||
| # Emit OSC 7 on each prompt | ||
| export PROMPT_COMMAND='printf "\033]7;file://$HOSTNAME$PWD\007"' | ||
| ``` | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Bash snippet: encode spaces + quote $PWD
printf "\033]7;file://$HOSTNAME$PWD\007" works but breaks when the working directory contains spaces or other URI-reserved chars. Consider URL-encoding the path (as you already do in the Zsh sample) or at least quoting $PWD.
-export PROMPT_COMMAND='printf "\033]7;file://$HOSTNAME$PWD\007"'
+export PROMPT_COMMAND='printf "\033]7;file://%s%s\007" "$HOSTNAME" "${PWD// /%20}"'This keeps the examples consistent across shells and avoids silent failures in edge cases.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```bash | |
| # Emit OSC 7 on each prompt | |
| export PROMPT_COMMAND='printf "\033]7;file://$HOSTNAME$PWD\007"' | |
| ``` | |
| # Emit OSC 7 on each prompt | |
| export PROMPT_COMMAND='printf "\033]7;file://%s%s\007" "$HOSTNAME" "${PWD// /%20}"' |
🤖 Prompt for AI Agents
In docs/docs/track-cwd.mdx around lines 29 to 33, the Bash snippet uses printf
with an unquoted $PWD, which can break if the working directory contains spaces
or URI-reserved characters. Fix this by quoting $PWD or applying URL encoding to
it, similar to the Zsh example, to ensure the path is correctly handled and the
example is consistent across shells.
- Updated Bash snippet to use a helper function for interactive shell checks and proper redirection to /dev/tty. - Enhanced Zsh snippet with improved command formatting and added a hook for precmd to ensure directory updates before each prompt. - Modified Fish snippet to align with Bash and Zsh examples by adding redirection to /dev/tty. - Updated inline comments to better explain the purpose of the changes.
- Added a new FAQ section with step-by-step guidance and shell-specific code examples. - Corrected configuration link from './config.mdx' to './config'. - Removed the obsolete 'track-cwd.mdx' document
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/docs/faq.mdx (2)
66-73: Variable name inconsistency may break hostname substitution
$HOST(used in Z sh) is not guaranteed to be set on all systems, whereas the Bash snippet uses$HOSTNAME. For portability and consistency, prefer$HOSTNAME(available by default in both Bash and Z sh) or fall back if unset:printf "\033]7;file://%s%s\007" "${HOSTNAME:-$HOST}" "${PWD// /%20}" > /dev/tty
88-100: Clarify verification instructions to prevent confusionStep 2 mentions “open a new tab (Alt T / Cmd T, Alt N / Cmd N)”, but earlier shortcuts list Alt N / Cmd N for terminal blocks and Alt T / Cmd T for browser tabs. Consider explicitly stating which shortcut applies to Wave terminal blocks to avoid readers thinking they pressed the wrong keys.
Example tweak:
After configuring, open a new terminal block (
Alt N/Cmd N) or split the current pane (Cmd D/Cmd Shift D)…
- Improved PROMPT_COMMAND handling to avoid clobbering existing values - Corrected Zsh snippet by replacing $HOST with $HOSTNAME - Added inline comments to better explain behavior and prevent unintended output
Background & Motivation
After installing Wave Terminal, new tabs and splits always started in my home folder instead of the current project directory, contrary to expectations from other terminals I've used. For context, I use
bashfor my shell.The existing documentation did not provide guidance about the required OSC 7 setup, so I had to dig into GitHub issues and source code to discover that Wave relies on a terminal escape sequence to track the shell’s working directory. This confusion represents a barrier for first-time users.
Description
This PR introduces a new documentation page—Tracking Your Shell’s Working Directory—which:
cmd:cwdmetadata in sync with your shell.By making this enhancement, users can:
ERRCWD invalid cwderrors in some shell configurations.Changes
docs/docs/track-cwd.mdx(new page to enable OSC 7).docs/docs/index.mdx(linked the new page under Other References).Related Issues
Testing & Review
Local build
cd waveterm yarn task docsiteContent review
I have followed the contributing guidelines and used a conventional commit message.