From a8638ea1f1377b96828753849b9dcc29bed527de Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Thu, 26 Jun 2025 11:45:43 -0400 Subject: [PATCH 1/5] docs: add OSC-7 working-directory tracking documentation --- docs/docs/index.mdx | 1 + docs/docs/track-cwd.mdx | 88 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+) create mode 100644 docs/docs/track-cwd.mdx diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx index ce97b6be9b..dbaf5f9c8b 100644 --- a/docs/docs/index.mdx +++ b/docs/docs/index.mdx @@ -70,6 +70,7 @@ If you have a question, please feel free to ask us in [Discord](https://discord. Other References: - [Configuration](./config) +- [Tracking Your Shell's Working Directory](./track-cwd) - [Custom Widgets](./customwidgets) - [Full wsh reference](./wsh-reference) - [Telemetry](./telemetry) diff --git a/docs/docs/track-cwd.mdx b/docs/docs/track-cwd.mdx new file mode 100644 index 0000000000..6b1ed2e851 --- /dev/null +++ b/docs/docs/track-cwd.mdx @@ -0,0 +1,88 @@ +--- +sidebar_position: 8 +id: "track-cwd" +title: "Tracking Your Shell's Working Directory" +--- + +# Tracking Your Shell's Working Directory + +Wave requires a special terminal escape sequence (OSC 7) to keep its internal working directory (`cmd:cwd`) in sync with your shell’s directory. Without this, new tabs or splits always start in your home directory. + +## Why OSC 7 is needed + +Most terminals emit an OSC 7 escape whenever the shell's current directory changes. Wave listens for these sequences to update its `cmd:cwd` metadata. That metadata is copied to new blocks when you: + +- Open a new tab (Alt T / Cmd T) +- Open a new terminal block (Alt N / Cmd N) +- Split a pane (Cmd D / Cmd Shift D) + +If OSC 7 isn’t enabled, Wave has no way to know your shell’s current directory and falls back to `~`. + +## Enabling OSC 7 in your shell + +Add the following snippets to your shell startup/config file and restart Wave (or source your config). + +### Bash + +Add to `~/.bashrc` or `~/.bash_profile`: + +```bash +# Emit OSC 7 on each prompt +export PROMPT_COMMAND='printf "\033]7;file://$HOSTNAME$PWD\007"' +``` + +### Zsh + +Add to `~/.zshrc`: + +```zsh +# Function to emit OSC 7 +function _wave_emit_cwd() { + printf "\033]7;file://%s%s\007" "$HOST" "${PWD// /%20}" +} + +# Emit when directory changes +autoload -U add-zsh-hook +add-zsh-hook chpwd _wave_emit_cwd + +# Emit once on startup +_wave_emit_cwd +``` + +### Fish + +> **Note:** Fish shell (version 4.0.0 and later) emits the OSC 7 working-directory escape by default. No additional configuration is required. See [Fish Release Notes](https://fishshell.com/docs/current/relnotes.html#improved-terminal-support) for more details. + +If you are running an older fish release, you can add the following to `~/.config/fish/config.fish`: + +```fish +function _wave_emit_cwd --on-variable PWD + printf "\033]7;file://%s%s\007" (hostname) (string replace ' ' '%20' $PWD) +end + +# Emit on startup +_wave_emit_cwd +``` + +## Verifying in Wave + +1. Open a Wave terminal block. +2. `cd` into a project folder, e.g. `cd ~/projects/foo`. +3. Right-click on the block's title bar and select "Copy BlockId" to retrieve the block’s ID. +4. Use the copied BlockId to retrieve the block’s metadata: + + ```bash + # Example: replace with your actual block reference + wsh getmeta --block + ``` + +5. Confirm the output JSON contains a `cmd:cwd` field, for example: + + ```json + { + "cmd:cwd": "/Users/you/projects/foo", + ... + } + ``` + +6. Open a new tab or split the pane—both should start in `/Users/you/projects/foo`. From aebc8d061da6991ddec2414e5327b9985a22c3a3 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Fri, 27 Jun 2025 12:58:14 -0400 Subject: [PATCH 2/5] docs: refine OSC 7 working-directory tracking snippet examples - 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. --- docs/docs/track-cwd.mdx | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/docs/track-cwd.mdx b/docs/docs/track-cwd.mdx index 6b1ed2e851..e2d6a022b2 100644 --- a/docs/docs/track-cwd.mdx +++ b/docs/docs/track-cwd.mdx @@ -27,8 +27,16 @@ Add the following snippets to your shell startup/config file and restart Wave (o Add to `~/.bashrc` or `~/.bash_profile`: ```bash -# Emit OSC 7 on each prompt -export PROMPT_COMMAND='printf "\033]7;file://$HOSTNAME$PWD\007"' +# Emit OSC 7 on each prompt to tell terminal about new working directory +__update_cwd() { + # Only run in interactive shells + [[ $- == *i* ]] || return + # Only run if attached to a terminal + [ -t 1 ] || return\ + # Redirect to tty so output doesn't show in shell + printf "\033]7;file://%s%s\007" "$HOSTNAME" "${PWD// /%20}" > /dev/tty +} +export PROMPT_COMMAND="__update_cwd" ``` ### Zsh @@ -36,17 +44,14 @@ export PROMPT_COMMAND='printf "\033]7;file://$HOSTNAME$PWD\007"' Add to `~/.zshrc`: ```zsh -# Function to emit OSC 7 +# Emit OSC 7 on each prompt to tell terminal about new working directory function _wave_emit_cwd() { - printf "\033]7;file://%s%s\007" "$HOST" "${PWD// /%20}" + printf "\033]7;file://%s%s\007" \ + "$HOST" "${PWD// /%20}" > /dev/tty } - -# Emit when directory changes autoload -U add-zsh-hook -add-zsh-hook chpwd _wave_emit_cwd - -# Emit once on startup -_wave_emit_cwd +add-zsh-hook chpwd _wave_emit_cwd +add-zsh-hook precmd _wave_emit_cwd ``` ### Fish @@ -56,12 +61,10 @@ _wave_emit_cwd If you are running an older fish release, you can add the following to `~/.config/fish/config.fish`: ```fish +# Emit OSC 7 on each prompt to tell terminal about new working directory function _wave_emit_cwd --on-variable PWD - printf "\033]7;file://%s%s\007" (hostname) (string replace ' ' '%20' $PWD) + printf "\033]7;file://%s%s\007" (hostname) (string replace ' ' '%20' $PWD) > /dev/tty end - -# Emit on startup -_wave_emit_cwd ``` ## Verifying in Wave From e465f54cb4341583eaae9fa9609b8b3c9c312a13 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Fri, 27 Jun 2025 16:24:08 -0400 Subject: [PATCH 3/5] docs: move OSC 7 instructions to FAQ - 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 --- docs/docs/faq.mdx | 77 +++++++++++++++++++++++++++++++++- docs/docs/index.mdx | 1 - docs/docs/track-cwd.mdx | 91 ----------------------------------------- 3 files changed, 76 insertions(+), 93 deletions(-) delete mode 100644 docs/docs/track-cwd.mdx diff --git a/docs/docs/faq.mdx b/docs/docs/faq.mdx index 08797f6908..6c4af223ee 100644 --- a/docs/docs/faq.mdx +++ b/docs/docs/faq.mdx @@ -35,13 +35,88 @@ Just remember in JSON, backslashes need to be escaped. So add this to your [sett `wsh` is an internal CLI for extending control over Wave to the command line, you can learn more about it [here](./wsh). To prevent misuse by other applications, `wsh` requires an access token provided by Wave to work and will not function outside of the app. +### How do I make new tabs or splits inherit my shell’s current directory? + +Wave uses a special escape sequence (OSC 7) to track the shell’s working directory and maintain the working directory of new terminal blocks and splits. Wave listens for these sequences to update its `cmd:cwd` metadata. That metadata is copied to new blocks when you: + +- Open a new terminal block (Alt N / Cmd N) +- Split a pane (Cmd D / Cmd Shift D) + +Not all shells emit this escape sequence, so new tabs or splits may start in your home directory instead. To ensure your shell emits the OSC 7 escape sequence, add the following to your shell startup/config file and restart Wave (or source your config). + +#### Bash + +Add to `~/.bashrc` or `~/.bash_profile`: + +```bash +# Emit OSC 7 escape on each prompt, sending directly to the terminal +__update_cwd() { + [[ $- == *i* ]] || return + [ -t 1 ] || return + printf "\033]7;file://%s%s\007" "$HOSTNAME" "${PWD// /%20}" > /dev/tty +} +export PROMPT_COMMAND="__update_cwd" +``` + +#### Zsh + +Add to `~/.zshrc`: + +```zsh +# Emit OSC 7 escape on directory change and prompt +function _wave_emit_cwd() { + printf "\033]7;file://%s%s\007" "$HOST" "${PWD// /%20}" > /dev/tty +} +autoload -U add-zsh-hook +add-zsh-hook chpwd _wave_emit_cwd +add-zsh-hook precmd _wave_emit_cwd +``` + +#### Fish + +> Fish shell (v4.0.0 and later) emits OSC 7 by default—no config required. + +For older Fish versions, add to `~/.config/fish/config.fish`: + +```fish +# Emit OSC 7 on each PWD change +function _wave_emit_cwd --on-variable PWD + printf "\033]7;file://%s%s\007" (hostname) (string replace ' ' '%20' $PWD) > /dev/tty +end +``` + +After configuring, open a new tab or split (Alt T / Cmd T, Alt N / Cmd N, Cmd D / Cmd Shift D) and verify blocks start in your current directory. + +#### Verifying Current Directory Preservation + +1. Open a Wave terminal block. +2. `cd` into a project folder, e.g. `cd ~/projects/foo`. +3. Right-click on the block's title bar and select "Copy BlockId" to retrieve the block’s ID. +4. Use the copied BlockId to retrieve the block’s metadata: + + ```bash + # Example: replace BLOCK_ID with your actual block reference + wsh getmeta --block BLOCK_ID + ``` + +5. Confirm the output JSON contains a `cmd:cwd` field, for example: + + ```json + { + "cmd:cwd": "/Users/you/projects/foo", + ... + } + ``` + +6. Open a new tab or split the pane—both should start in `/Users/you/projects/foo`. + ## Why does Wave warn me about ARM64 translation when it launches? macOS and Windows both have compatibility layers that allow x64 applications to run on ARM computers. This helps more apps run on these systems while developers work to add native ARM support to their applications. However, it comes with significant performance tradeoffs. To get the best experience using Wave, it is recommended that you uninstall Wave and reinstall the version that is natively compiled for your computer. You can find the right version by consulting our [Installation Instructions](./gettingstarted#installation). -You can disable this warning by setting `app:dismissarchitecturewarning=true` in [your configurations](./config.mdx). +You can disable this warning by setting `app:dismissarchitecturewarning=true` in [your configurations](./config). ## How do I join the beta builds of Wave? diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx index dbaf5f9c8b..ce97b6be9b 100644 --- a/docs/docs/index.mdx +++ b/docs/docs/index.mdx @@ -70,7 +70,6 @@ If you have a question, please feel free to ask us in [Discord](https://discord. Other References: - [Configuration](./config) -- [Tracking Your Shell's Working Directory](./track-cwd) - [Custom Widgets](./customwidgets) - [Full wsh reference](./wsh-reference) - [Telemetry](./telemetry) diff --git a/docs/docs/track-cwd.mdx b/docs/docs/track-cwd.mdx deleted file mode 100644 index e2d6a022b2..0000000000 --- a/docs/docs/track-cwd.mdx +++ /dev/null @@ -1,91 +0,0 @@ ---- -sidebar_position: 8 -id: "track-cwd" -title: "Tracking Your Shell's Working Directory" ---- - -# Tracking Your Shell's Working Directory - -Wave requires a special terminal escape sequence (OSC 7) to keep its internal working directory (`cmd:cwd`) in sync with your shell’s directory. Without this, new tabs or splits always start in your home directory. - -## Why OSC 7 is needed - -Most terminals emit an OSC 7 escape whenever the shell's current directory changes. Wave listens for these sequences to update its `cmd:cwd` metadata. That metadata is copied to new blocks when you: - -- Open a new tab (Alt T / Cmd T) -- Open a new terminal block (Alt N / Cmd N) -- Split a pane (Cmd D / Cmd Shift D) - -If OSC 7 isn’t enabled, Wave has no way to know your shell’s current directory and falls back to `~`. - -## Enabling OSC 7 in your shell - -Add the following snippets to your shell startup/config file and restart Wave (or source your config). - -### Bash - -Add to `~/.bashrc` or `~/.bash_profile`: - -```bash -# Emit OSC 7 on each prompt to tell terminal about new working directory -__update_cwd() { - # Only run in interactive shells - [[ $- == *i* ]] || return - # Only run if attached to a terminal - [ -t 1 ] || return\ - # Redirect to tty so output doesn't show in shell - printf "\033]7;file://%s%s\007" "$HOSTNAME" "${PWD// /%20}" > /dev/tty -} -export PROMPT_COMMAND="__update_cwd" -``` - -### Zsh - -Add to `~/.zshrc`: - -```zsh -# Emit OSC 7 on each prompt to tell terminal about new working directory -function _wave_emit_cwd() { - printf "\033]7;file://%s%s\007" \ - "$HOST" "${PWD// /%20}" > /dev/tty -} -autoload -U add-zsh-hook -add-zsh-hook chpwd _wave_emit_cwd -add-zsh-hook precmd _wave_emit_cwd -``` - -### Fish - -> **Note:** Fish shell (version 4.0.0 and later) emits the OSC 7 working-directory escape by default. No additional configuration is required. See [Fish Release Notes](https://fishshell.com/docs/current/relnotes.html#improved-terminal-support) for more details. - -If you are running an older fish release, you can add the following to `~/.config/fish/config.fish`: - -```fish -# Emit OSC 7 on each prompt to tell terminal about new working directory -function _wave_emit_cwd --on-variable PWD - printf "\033]7;file://%s%s\007" (hostname) (string replace ' ' '%20' $PWD) > /dev/tty -end -``` - -## Verifying in Wave - -1. Open a Wave terminal block. -2. `cd` into a project folder, e.g. `cd ~/projects/foo`. -3. Right-click on the block's title bar and select "Copy BlockId" to retrieve the block’s ID. -4. Use the copied BlockId to retrieve the block’s metadata: - - ```bash - # Example: replace with your actual block reference - wsh getmeta --block - ``` - -5. Confirm the output JSON contains a `cmd:cwd` field, for example: - - ```json - { - "cmd:cwd": "/Users/you/projects/foo", - ... - } - ``` - -6. Open a new tab or split the pane—both should start in `/Users/you/projects/foo`. From 5f2468c115c57b51a4f0740e6beb78b9a666fe5e Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Fri, 27 Jun 2025 17:23:46 -0400 Subject: [PATCH 4/5] docs: update terminology from tabs to blocks in FAQ --- docs/docs/faq.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/faq.mdx b/docs/docs/faq.mdx index 6c4af223ee..3ddab4723d 100644 --- a/docs/docs/faq.mdx +++ b/docs/docs/faq.mdx @@ -35,14 +35,14 @@ Just remember in JSON, backslashes need to be escaped. So add this to your [sett `wsh` is an internal CLI for extending control over Wave to the command line, you can learn more about it [here](./wsh). To prevent misuse by other applications, `wsh` requires an access token provided by Wave to work and will not function outside of the app. -### How do I make new tabs or splits inherit my shell’s current directory? +### How do I make new blocks or splits inherit my shell’s current directory? Wave uses a special escape sequence (OSC 7) to track the shell’s working directory and maintain the working directory of new terminal blocks and splits. Wave listens for these sequences to update its `cmd:cwd` metadata. That metadata is copied to new blocks when you: - Open a new terminal block (Alt N / Cmd N) - Split a pane (Cmd D / Cmd Shift D) -Not all shells emit this escape sequence, so new tabs or splits may start in your home directory instead. To ensure your shell emits the OSC 7 escape sequence, add the following to your shell startup/config file and restart Wave (or source your config). +Not all shells emit this escape sequence, so new blocks or splits may start in your home directory instead. To ensure your shell emits the OSC 7 escape sequence, add the following to your shell startup/config file and restart Wave (or source your config). #### Bash @@ -85,7 +85,7 @@ function _wave_emit_cwd --on-variable PWD end ``` -After configuring, open a new tab or split (Alt T / Cmd T, Alt N / Cmd N, Cmd D / Cmd Shift D) and verify blocks start in your current directory. +After configuring, open a new block or split (Alt T / Cmd T, Alt N / Cmd N, Cmd D / Cmd Shift D) and verify blocks start in your current directory. #### Verifying Current Directory Preservation @@ -108,7 +108,7 @@ After configuring, open a new tab or split (Alt T / Cmd T, Alt N / Cmd N, Cmd D } ``` -6. Open a new tab or split the pane—both should start in `/Users/you/projects/foo`. +6. Open a new block or split the pane—both should start in `/Users/you/projects/foo`. ## Why does Wave warn me about ARM64 translation when it launches? From 756e12e9531a6f295b059efafdf03a6771a28bfe Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Fri, 27 Jun 2025 17:25:42 -0400 Subject: [PATCH 5/5] docs: enhance OSC 7 working directory snippets in FAQ - 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 --- docs/docs/faq.mdx | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/docs/faq.mdx b/docs/docs/faq.mdx index 3ddab4723d..37f51385b2 100644 --- a/docs/docs/faq.mdx +++ b/docs/docs/faq.mdx @@ -49,13 +49,20 @@ Not all shells emit this escape sequence, so new blocks or splits may start in y Add to `~/.bashrc` or `~/.bash_profile`: ```bash -# Emit OSC 7 escape on each prompt, sending directly to the terminal +# Emit OSC 7 on each prompt to tell terminal about new working directory __update_cwd() { + # Only run in interactive shells [[ $- == *i* ]] || return + # Only run if attached to a terminal [ -t 1 ] || return + # Redirect to tty so output doesn't show in shell printf "\033]7;file://%s%s\007" "$HOSTNAME" "${PWD// /%20}" > /dev/tty } -export PROMPT_COMMAND="__update_cwd" +if [[ -n "$PROMPT_COMMAND" ]]; then + export PROMPT_COMMAND="__update_cwd; $PROMPT_COMMAND" +else + export PROMPT_COMMAND="__update_cwd" +fi ``` #### Zsh @@ -65,7 +72,7 @@ Add to `~/.zshrc`: ```zsh # Emit OSC 7 escape on directory change and prompt function _wave_emit_cwd() { - printf "\033]7;file://%s%s\007" "$HOST" "${PWD// /%20}" > /dev/tty + printf "\033]7;file://%s%s\007" "$HOSTNAME" "${PWD// /%20}" > /dev/tty } autoload -U add-zsh-hook add-zsh-hook chpwd _wave_emit_cwd