From cd9b722de6a9e806e0a3522b38c17442569d17a2 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 22:30:08 +0000 Subject: [PATCH 1/3] docs: document Warp file locations across macOS/Windows/Linux Adds a new reference page that lays out every Warp config, data, and state path across all three platforms and both release channels, plus fixes related pages whose Windows/Linux paths were inaccurate or incomplete: - New: terminal/settings/file-locations covering data_dir, config_local_dir, state_dir, ~/.warp, ~/.agents, and the WSL symlink workflow Windows + WSL users actually need. - Tab Configs page now lists per-OS tab_configs directories instead of only showing the macOS path. - Custom Themes background_image note now points at the per-OS themes directory instead of just ~/.warp/themes. - Uninstall doc fixes a Linux XDG_STATE_HOME -> XDG_DATA_HOME typo for themes/launch configs, calls out ~/.warp on Windows, and corrects the Windows Preview path to WarpPreview. - Settings file overview cross-links the new reference page. - Sidebar adds the new page under the Settings file group. Co-Authored-By: Oz --- .../logging-out-and-uninstalling.mdx | 34 ++-- .../terminal/appearance/custom-themes.mdx | 8 +- .../docs/terminal/settings/file-locations.mdx | 151 ++++++++++++++++++ src/content/docs/terminal/settings/index.mdx | 3 + .../docs/terminal/windows/tab-configs.mdx | 23 ++- src/sidebar.ts | 1 + 6 files changed, 201 insertions(+), 19 deletions(-) create mode 100644 src/content/docs/terminal/settings/file-locations.mdx diff --git a/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx b/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx index cce2b243..8cfb596c 100644 --- a/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx +++ b/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx @@ -90,10 +90,12 @@ If you're using Warp Preview, replace "Warp-Stable" with "Warp-Preview" in the c ```powershell # Remove Warp settings in the Windows Registry Remove-Item -Path "HKCU:\Software\Warp.dev\Warp" -Recurse -Force - # Remove Warp user files, logs, database, Codebase Context, and MCP logs + # Remove Warp settings, keybindings, logs, database, Codebase Context, and MCP logs Remove-Item -Path "$env:LOCALAPPDATA\warp\Warp" -Recurse -Force - # Remove Warp themes and launch configurations + # Remove Warp themes, tab configs, workflows, and launch configurations Remove-Item -Path "$env:APPDATA\warp\Warp" -Recurse -Force + # Remove MCP server config and bundled skills (shared across Stable and Preview) + Remove-Item -Path "$env:USERPROFILE\.warp" -Recurse -Force ``` **For Warp Preview users:** @@ -101,10 +103,11 @@ If you're using Warp Preview, replace "Warp-Stable" with "Warp-Preview" in the c ```powershell # Remove Warp Preview settings in the Windows Registry Remove-Item -Path "HKCU:\Software\Warp.dev\Warp-Preview" -Recurse -Force - # Remove Warp Preview user files, logs, database, Codebase Context, and MCP logs - Remove-Item -Path "$env:LOCALAPPDATA\warp\Warp-Preview" -Recurse -Force - # Remove Warp Preview themes and launch configurations - Remove-Item -Path "$env:APPDATA\warp\Warp-Preview" -Recurse -Force + # Remove Warp Preview settings, keybindings, logs, database, Codebase Context, and MCP logs + Remove-Item -Path "$env:LOCALAPPDATA\warp\WarpPreview" -Recurse -Force + # Remove Warp Preview themes, tab configs, workflows, and launch configurations + Remove-Item -Path "$env:APPDATA\warp\WarpPreview" -Recurse -Force + # Note: Removing $env:USERPROFILE\.warp also removes Stable's MCP config and skills. ``` @@ -126,12 +129,14 @@ If you're using Warp Preview, replace "Warp-Stable" with "Warp-Preview" in the c **Removing Warp settings, files, logs, and database** ```bash - # Remove Warp settings files + # Remove Warp settings and keybindings files rm -r ${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal - # Remove Warp user files, logs, database, Codebase Context, and MCP logs + # Remove Warp logs, database, Codebase Context, and MCP logs rm -r ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal - # Remove Warp themes and launch configurations - rm -r ${XDG_STATE_HOME:-$HOME/.local/share}/warp-terminal + # Remove Warp themes, tab configs, workflows, and launch configurations + rm -r ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal + # Remove MCP server config and bundled skills (shared across Stable and Preview) + rm -r $HOME/.warp ``` **For Warp Preview users:** @@ -150,12 +155,13 @@ If you're using Warp Preview, replace "Warp-Stable" with "Warp-Preview" in the c * Uninstall Warp Preview using the same package manager that you used to install it. ```bash - # Remove Warp Preview settings files + # Remove Warp Preview settings and keybindings files rm -r ${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal-preview - # Remove Warp Preview user files, logs, database, Codebase Context, and MCP logs + # Remove Warp Preview logs, database, Codebase Context, and MCP logs rm -r ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal-preview - # Remove Warp Preview themes and launch configurations - rm -r ${XDG_STATE_HOME:-$HOME/.local/share}/warp-terminal-preview + # Remove Warp Preview themes, tab configs, workflows, and launch configurations + rm -r ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal-preview + # Note: Removing $HOME/.warp also removes Stable's MCP config and skills. ``` diff --git a/src/content/docs/terminal/appearance/custom-themes.mdx b/src/content/docs/terminal/appearance/custom-themes.mdx index 6a083b48..1b6beeb5 100644 --- a/src/content/docs/terminal/appearance/custom-themes.mdx +++ b/src/content/docs/terminal/appearance/custom-themes.mdx @@ -170,8 +170,12 @@ foreground: '#839496' ############################################################### SEE BELOW background_image: - # the path is relative to ~/.warp/themes/ - # the full path to the picture is: ~/.warp/themes/warp.jpg + # The path is relative to your platform's themes directory: + # macOS: ~/.warp/themes/ + # Windows: %APPDATA%\warp\Warp\data\themes\ + # Linux: ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/themes/ + # For example, on macOS the full path to the picture below is: + # ~/.warp/themes/warp.jpg path: warp.jpg # the opacity value is required and can range from 0-100 opacity: 60 diff --git a/src/content/docs/terminal/settings/file-locations.mdx b/src/content/docs/terminal/settings/file-locations.mdx new file mode 100644 index 00000000..ea1edbbf --- /dev/null +++ b/src/content/docs/terminal/settings/file-locations.mdx @@ -0,0 +1,151 @@ +--- +title: File and folder locations +description: >- + Reference for where Warp stores config, themes, tab configs, settings, + keybindings, logs, and other files on macOS, Windows, and Linux. +sidebar: + label: "File locations" +--- +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +This reference lists every directory and file Warp reads or writes on disk, organized by platform and Warp release channel. Use it when you want to back up your config, edit a file directly, debug a missing setting, or symlink Warp's configuration from another shell (for example, [WSL](#symlinking-warps-config-from-wsl)). + +## How Warp organizes files + +Warp groups its files into three buckets, and the directory each bucket maps to depends on your platform. Knowing the bucket explains why two files that feel related (themes and settings, for example) live in different roots on Windows and Linux but the same root on macOS. + +* **Portable user data** - Files you'd want to copy to a new machine, such as themes, tab configs, workflows, and launch configurations. +* **Non-portable config** - Local-only configuration that doesn't make sense to roam, such as `settings.toml` and `keybindings.yaml`. +* **Non-portable state** - Machine-specific state like logs, the local database, and the Codebase Context index. + +In addition, a small set of cross-cutting files always live under `~/.warp/` (or `~/.warp-/` on macOS Preview) on every platform — currently MCP server config and bundled skills. These intentionally sit in the home directory so they're easy to reference from shell config, version control, or other tools. + +## File locations by platform + +The tables below cover the **Stable** channel. For **Preview**, see [Preview channel paths](#preview-channel-paths). + + + + On macOS, Stable keeps every Warp-authored file under `~/.warp/`. Preview uses `~/.warp-preview/` for everything except the cross-platform `~/.warp/` carve-out. + + **Portable user data** + + * **Themes** - `~/.warp/themes/` + * **Tab configs** - `~/.warp/tab_configs/` + * **Default tab configs** (shipped, user-editable) - `~/.warp/default_tab_configs/` + * **Workflows** (local) - `~/.warp/workflows/` + * **Launch configurations** - `~/.warp/launch_configurations/` + + **Non-portable config** + + * **Settings file** - `~/.warp/settings.toml` + * **Keybindings** - `~/.warp/keybindings.yaml` + * **User preferences** (legacy) - macOS `defaults` domain `dev.warp.Warp-Stable` + + **Non-portable state** + + * **Logs** - `~/Library/Logs/warp.log*` + * **Crash reports** - `~/Library/Logs/DiagnosticReports/` (Warp `.ips` files) + * **Database, Codebase Context index, MCP logs** - `~/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/` + + **Cross-platform (always in your home directory)** + + * **MCP server config** - `~/.warp/.mcp.json` + * **Bundled skills** - `~/.warp/skills/` + * **Agent config** - `~/.agents/` + + + On Windows, Warp follows the platform conventions used by the [`directories`](https://docs.rs/directories) crate, which splits user data across `%APPDATA%` (Roaming) and `%LOCALAPPDATA%` (Local). Themes and tab configs are portable and live in Roaming, while settings, logs, and the local database are machine-specific and live in Local. Two separate `data\` directories exist as a result — one under each root — so check the full path when locating files. + + **Portable user data** (`%APPDATA%\warp\Warp\data\`, Roaming) + + * **Themes** - `%APPDATA%\warp\Warp\data\themes\` + * **Tab configs** - `%APPDATA%\warp\Warp\data\tab_configs\` + * **Default tab configs** (shipped, user-editable) - `%APPDATA%\warp\Warp\data\default_tab_configs\` + * **Workflows** (local) - `%APPDATA%\warp\Warp\data\workflows\` + * **Launch configurations** - `%APPDATA%\warp\Warp\data\launch_configurations\` + + **Non-portable config** (`%LOCALAPPDATA%\warp\Warp\config\`) + + * **Settings file** - `%LOCALAPPDATA%\warp\Warp\config\settings.toml` + * **Keybindings** - `%LOCALAPPDATA%\warp\Warp\config\keybindings.yaml` + * **User preferences** (legacy) - Windows Registry key `HKCU:\Software\Warp.dev\Warp` + + **Non-portable state** (`%LOCALAPPDATA%\warp\Warp\data\`) + + * **Logs** - `%LOCALAPPDATA%\warp\Warp\data\logs\warp.log*` + * **Database, Codebase Context index, MCP logs** - other subdirectories under `%LOCALAPPDATA%\warp\Warp\data\` + * **Cache** - `%LOCALAPPDATA%\warp\Warp\cache\` + + **Cross-platform (always in your home directory)** + + * **MCP server config** - `%USERPROFILE%\.warp\.mcp.json` + * **Bundled skills** - `%USERPROFILE%\.warp\skills\` + * **Agent config** - `%USERPROFILE%\.agents\` + + + On Linux, Warp follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). Each path below uses the standard XDG environment variable with its default fallback. + + **Portable user data** (`${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/`) + + * **Themes** - `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/themes/` + * **Tab configs** - `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/tab_configs/` + * **Default tab configs** (shipped, user-editable) - `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/default_tab_configs/` + * **Workflows** (local) - `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/workflows/` + * **Launch configurations** - `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/launch_configurations/` + + **Non-portable config** (`${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal/`) + + * **Settings file** - `${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal/settings.toml` + * **Keybindings** - `${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal/keybindings.yaml` + + **Non-portable state** (`${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/`) + + * **Logs** - `${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/warp.log*` + * **Database, Codebase Context index, MCP logs** - other files under `${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/` + * **Cache** - `${XDG_CACHE_HOME:-$HOME/.cache}/warp-terminal/` + + **Cross-platform (always in your home directory)** + + * **MCP server config** - `~/.warp/.mcp.json` + * **Bundled skills** - `~/.warp/skills/` + * **Agent config** - `~/.agents/` + + + +## Preview channel paths + +Preview uses a separate set of directories so it never overwrites your Stable config: + +* **macOS** - Replace `~/.warp/` with `~/.warp-preview/` and `Warp-Stable` with `Warp-Preview` in the macOS paths above. The cross-platform `~/.warp/` carve-out (MCP config, skills) is shared with Stable. +* **Windows** - Replace `\warp\Warp\` with `\warp\WarpPreview\` in every path. Logs become `%LOCALAPPDATA%\warp\WarpPreview\data\logs\warp_preview.log*`. The Registry key is `HKCU:\Software\Warp.dev\Warp-Preview`. +* **Linux** - Append `-preview` to each `warp-terminal` directory (for example, `~/.config/warp-terminal-preview/settings.toml`). Logs become `${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal-preview/warp_preview.log*`. + +## Symlinking Warp's config from WSL + +If you run Warp on Windows and also use WSL, you can share Warp's portable config with your WSL `$HOME` so that tools running inside WSL can read the same themes and tab configs. Because Warp splits portable data (Roaming) and non-portable config (Local) into two separate roots, you'll need a symlink per root rather than a single top-level link. + +From a WSL shell: + +```bash +# Portable data: themes, tab configs, workflows, launch configurations. +ln -s "/mnt/c/Users/$USER/AppData/Roaming/warp/Warp/data" ~/.warp-windows-data + +# Local config: settings.toml, keybindings.yaml. +ln -s "/mnt/c/Users/$USER/AppData/Local/warp/Warp/config" ~/.warp-windows-config +``` + +`~/.warp/` (MCP config, skills) and `~/.agents/` are already shared because both Windows and WSL use the same user home directory layout for those files. + +:::note +Warp on Windows does not currently load config from `~/.warp/tab_configs/` or `~/.warp/themes/` — those paths only work on macOS. If you have config files in those home-directory paths from a different machine, copy or symlink them into the Windows `%APPDATA%\warp\Warp\data\` directory before they take effect. +::: + +## Related pages + +* [Settings file](/terminal/settings/) - Format, hot-reload behavior, and common examples for `settings.toml`. +* [All settings reference](/terminal/settings/all-settings/) - Every setting available in `settings.toml`, organized by section. +* [Keyboard shortcuts](/getting-started/keyboard-shortcuts/) - How to view and remap shortcuts, including the `keybindings.yaml` file. +* [Tab Configs](/terminal/windows/tab-configs/) - TOML format and schema for tab config files in `tab_configs/`. +* [Custom themes](/terminal/appearance/custom-themes/) - YAML format and image conventions for themes in `themes/`. +* [Uninstalling Warp](/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling/) - Commands for removing all of these files when uninstalling. diff --git a/src/content/docs/terminal/settings/index.mdx b/src/content/docs/terminal/settings/index.mdx index d01ee9b9..90173895 100644 --- a/src/content/docs/terminal/settings/index.mdx +++ b/src/content/docs/terminal/settings/index.mdx @@ -38,6 +38,8 @@ Depending on your platform and Warp release channel, `settings.toml` is located * Stable — `%LOCALAPPDATA%\warp\Warp\config\settings.toml` * Preview — `%LOCALAPPDATA%\warp\WarpPreview\config\settings.toml` +For the locations of every other Warp file — themes, tab configs, keybindings, logs, the local database, and more — see [File and folder locations](/terminal/settings/file-locations/). + ## Settings file format The file uses [TOML v1.1](https://toml.io/en/v1.1.0) syntax. Settings are organized into **sections** (TOML tables) that group related options — for example, `[appearance.text]` contains font settings and `[agents.profiles]` contains agent permission settings. @@ -170,6 +172,7 @@ Confirm you're editing the correct file for your platform and Warp release chann ## Related pages * [All settings reference](/terminal/settings/all-settings/) — Complete list of every available setting with descriptions, types, and defaults +* [File and folder locations](/terminal/settings/file-locations/) — Where Warp stores every config, data, and state file across macOS, Windows, and Linux * [Customizing Warp](/getting-started/quickstart/customizing-warp/) — Overview of all customization options * [Custom themes](/terminal/appearance/custom-themes/) — Create and load custom YAML or Base16 themes * [Keyboard shortcuts](/getting-started/keyboard-shortcuts/) — Customize keybindings diff --git a/src/content/docs/terminal/windows/tab-configs.mdx b/src/content/docs/terminal/windows/tab-configs.mdx index 13106e5d..9fa8a34c 100644 --- a/src/content/docs/terminal/windows/tab-configs.mdx +++ b/src/content/docs/terminal/windows/tab-configs.mdx @@ -4,6 +4,7 @@ description: >- Tab Configs let you define reusable tab setups — including directory, startup commands, pane layout, shell, and theme — in a simple TOML file. --- +import { Tabs, TabItem } from '@astrojs/starlight/components'; import VideoEmbed from '@components/VideoEmbed.astro'; Tab Configs let you define reusable tab setups — including directory, startup commands, pane layout, shell, and theme — in a simple TOML file. Select a Tab Config from the `+` menu to open a fully configured tab with a single click. @@ -12,18 +13,34 @@ Tab Configs let you define reusable tab setups — including directory, startup ## How Tab Configs work -Each Tab Config is a `.toml` file stored in `~/.warp/tab_configs/`. Every file defines a single tab layout with optional pane splits, startup commands, and parameterized inputs. Tab Configs appear in the `+` menu alongside your existing tabs, so you can launch a preconfigured workspace instantly. +Each Tab Config is a `.toml` file stored in Warp's `tab_configs` directory. Every file defines a single tab layout with optional pane splits, startup commands, and parameterized inputs. Tab Configs appear in the `+` menu alongside your existing tabs, so you can launch a preconfigured workspace instantly. + +The `tab_configs` directory lives in a different location on each platform: + + + + `~/.warp/tab_configs/` (Stable) or `~/.warp-preview/tab_configs/` (Preview). + + + `%APPDATA%\warp\Warp\data\tab_configs\` (Stable) or `%APPDATA%\warp\WarpPreview\data\tab_configs\` (Preview). + + + `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/tab_configs/` (Stable) or `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal-preview/tab_configs/` (Preview). + + + +For the full list of Warp file locations, see [File and folder locations](/terminal/settings/file-locations/). ## Creating a Tab Config ### From the UI 1. Click the **+** button in the tab bar to open the new-tab menu. -2. Click **+ New tab config**. Warp creates a new `.toml` file in `~/.warp/tab_configs/` and opens it for editing. +2. Click **+ New tab config**. Warp creates a new `.toml` file in the `tab_configs` directory and opens it for editing. ### Manually -1. Create a new `.toml` file in `~/.warp/tab_configs/`. Use snake_case for the file name (e.g., `dev_server.toml`). +1. Create a new `.toml` file in the `tab_configs` directory shown above. Use snake_case for the file name (e.g., `dev_server.toml`). 2. Define the tab layout using the schema below, then save the file. The new config appears in the `+` menu automatically. ### Save an existing tab as a Tab Config diff --git a/src/sidebar.ts b/src/sidebar.ts index 4fdd0297..f64c9e80 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -145,6 +145,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ items: [ { slug: 'terminal/settings', label: 'Overview' }, { slug: 'terminal/settings/all-settings', label: 'All settings reference' }, + { slug: 'terminal/settings/file-locations', label: 'File locations' }, ], }, { From c9d630ce16ea354c844cbcf7543f27e16069e607 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 22:39:29 +0000 Subject: [PATCH 2/3] docs: address review feedback on file-locations - Drop the inaccurate 'or ~/.warp-/ on macOS Preview' note from the cross-platform carve-out: Stable and Preview both use ~/.warp/ for MCP config and bundled skills per warp_home_config_dir_name() in warp_core/src/paths.rs. Other channels (OSS, Dev, etc.) get a suffix. - Rework the WSL symlink section: WSL $HOME is separate from Windows %USERPROFILE%, so ~/.warp/ and ~/.agents/ are not shared automatically. Use a WIN_USER variable instead of $USER (the WSL Linux account name, often different from the Windows profile), and document additional symlinks for ~/.warp and ~/.agents so users can share them too. Co-Authored-By: Oz --- .../docs/terminal/settings/file-locations.mdx | 26 +++++++++++++------ 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/src/content/docs/terminal/settings/file-locations.mdx b/src/content/docs/terminal/settings/file-locations.mdx index ea1edbbf..01997f62 100644 --- a/src/content/docs/terminal/settings/file-locations.mdx +++ b/src/content/docs/terminal/settings/file-locations.mdx @@ -18,7 +18,7 @@ Warp groups its files into three buckets, and the directory each bucket maps to * **Non-portable config** - Local-only configuration that doesn't make sense to roam, such as `settings.toml` and `keybindings.yaml`. * **Non-portable state** - Machine-specific state like logs, the local database, and the Codebase Context index. -In addition, a small set of cross-cutting files always live under `~/.warp/` (or `~/.warp-/` on macOS Preview) on every platform — currently MCP server config and bundled skills. These intentionally sit in the home directory so they're easy to reference from shell config, version control, or other tools. +In addition, a small set of cross-cutting files always live under `~/.warp/` on every platform and channel — currently MCP server config and bundled skills. Stable and Preview share `~/.warp/` for these files (other channels like OSS use a suffixed directory such as `~/.warp-oss/`). They intentionally sit in the home directory so they're easy to reference from shell config, version control, or other tools. ## File locations by platform @@ -123,19 +123,29 @@ Preview uses a separate set of directories so it never overwrites your Stable co ## Symlinking Warp's config from WSL -If you run Warp on Windows and also use WSL, you can share Warp's portable config with your WSL `$HOME` so that tools running inside WSL can read the same themes and tab configs. Because Warp splits portable data (Roaming) and non-portable config (Local) into two separate roots, you'll need a symlink per root rather than a single top-level link. +If you run Warp on Windows and also use WSL, you can share Warp's config with your WSL `$HOME` so that tools running inside WSL can read the same themes, tab configs, settings, MCP servers, and agent config. WSL `$HOME` (typically `/home//`) is a separate filesystem from your Windows profile (`%USERPROFILE%`, typically `C:\Users\\`), so nothing is shared automatically — every Warp directory you want to share needs its own symlink. -From a WSL shell: +Windows splits Warp's data across four roots (Roaming AppData, Local AppData, and two home-directory paths) and your WSL Linux username is usually different from your Windows account name, so do this from a WSL shell: ```bash -# Portable data: themes, tab configs, workflows, launch configurations. -ln -s "/mnt/c/Users/$USER/AppData/Roaming/warp/Warp/data" ~/.warp-windows-data +# Set this once to your Windows username. Find it from WSL with: +# cmd.exe /C 'echo %USERNAME%' 2>/dev/null | tr -d '\r' +WIN_USER=YourWindowsUserName -# Local config: settings.toml, keybindings.yaml. -ln -s "/mnt/c/Users/$USER/AppData/Local/warp/Warp/config" ~/.warp-windows-config +# Portable data: themes, tab configs, workflows, launch configurations (Roaming AppData). +ln -s "/mnt/c/Users/$WIN_USER/AppData/Roaming/warp/Warp/data" ~/.warp-windows-data + +# Local config: settings.toml, keybindings.yaml (Local AppData). +ln -s "/mnt/c/Users/$WIN_USER/AppData/Local/warp/Warp/config" ~/.warp-windows-config + +# Cross-platform carve-outs: MCP server config and bundled skills. +ln -s "/mnt/c/Users/$WIN_USER/.warp" ~/.warp + +# Agent config (.agents). +ln -s "/mnt/c/Users/$WIN_USER/.agents" ~/.agents ``` -`~/.warp/` (MCP config, skills) and `~/.agents/` are already shared because both Windows and WSL use the same user home directory layout for those files. +If `~/.warp` or `~/.agents` already exist in WSL, remove or back them up before creating the symlinks. To resolve `%USERPROFILE%` programmatically instead of hard-coding the Windows username, use `wslpath "$(cmd.exe /C 'echo %USERPROFILE%' 2>/dev/null | tr -d '\r')"` from WSL. :::note Warp on Windows does not currently load config from `~/.warp/tab_configs/` or `~/.warp/themes/` — those paths only work on macOS. If you have config files in those home-directory paths from a different machine, copy or symlink them into the Windows `%APPDATA%\warp\Warp\data\` directory before they take effect. From adb1dd6f932fd1fce228ec9e505620b5ff6187a9 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 19 May 2026 23:32:41 +0000 Subject: [PATCH 3/3] docs: fix Windows Preview registry key, clarify ~/.warp carve-out and WSL setup Addresses review feedback on PR #110: - Fix the Windows Preview Registry key in two places: it is HKCU:\\Software\\Warp.dev\\WarpPreview (no hyphen). The hyphenated Warp-Preview form is the macOS bundle identifier (dev.warp.Warp-Preview), not the Windows app name. Confirmed against script/windows/bundle.ps1 ($APP_NAME = 'WarpPreview') and registry_backed.rs (Software\\Warp.dev\\). - Reword the cross-cutting carve-out paragraph in file-locations.mdx so it states explicitly that both Stable and Preview share ~/.warp/ for MCP config and skills, and only channels like OSS use a suffixed directory. - Rewrite the WSL section to promote wslpath + %USERPROFILE% resolution as the primary approach (instead of hard-coding the Windows username) and call out that WSL $HOME is a separate Linux filesystem from %USERPROFILE%, so ~/.warp and ~/.agents on the WSL side are not automatically the same as their Windows-side counterparts. Co-Authored-By: Oz --- .../logging-out-and-uninstalling.mdx | 2 +- .../docs/terminal/settings/file-locations.mdx | 34 ++++++++++--------- 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx b/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx index 8cfb596c..9cf0926d 100644 --- a/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx +++ b/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx @@ -102,7 +102,7 @@ If you're using Warp Preview, replace "Warp-Stable" with "Warp-Preview" in the c ```powershell # Remove Warp Preview settings in the Windows Registry - Remove-Item -Path "HKCU:\Software\Warp.dev\Warp-Preview" -Recurse -Force + Remove-Item -Path "HKCU:\Software\Warp.dev\WarpPreview" -Recurse -Force # Remove Warp Preview settings, keybindings, logs, database, Codebase Context, and MCP logs Remove-Item -Path "$env:LOCALAPPDATA\warp\WarpPreview" -Recurse -Force # Remove Warp Preview themes, tab configs, workflows, and launch configurations diff --git a/src/content/docs/terminal/settings/file-locations.mdx b/src/content/docs/terminal/settings/file-locations.mdx index 01997f62..628b4131 100644 --- a/src/content/docs/terminal/settings/file-locations.mdx +++ b/src/content/docs/terminal/settings/file-locations.mdx @@ -18,7 +18,7 @@ Warp groups its files into three buckets, and the directory each bucket maps to * **Non-portable config** - Local-only configuration that doesn't make sense to roam, such as `settings.toml` and `keybindings.yaml`. * **Non-portable state** - Machine-specific state like logs, the local database, and the Codebase Context index. -In addition, a small set of cross-cutting files always live under `~/.warp/` on every platform and channel — currently MCP server config and bundled skills. Stable and Preview share `~/.warp/` for these files (other channels like OSS use a suffixed directory such as `~/.warp-oss/`). They intentionally sit in the home directory so they're easy to reference from shell config, version control, or other tools. +In addition, a small set of cross-cutting files always live in your home directory on every platform — currently MCP server config and bundled skills. Both Stable and Preview share the same `~/.warp/` directory for these files (Preview does **not** use `~/.warp-preview/` for MCP config or skills, so installing Preview alongside Stable shares the same MCP servers and skills). Other release channels do use a channel-suffixed directory — for example, `~/.warp-oss/` for OSS. These files sit in the home directory so they're easy to reference from shell config, version control, or other tools. ## File locations by platform @@ -117,35 +117,37 @@ The tables below cover the **Stable** channel. For **Preview**, see [Preview cha Preview uses a separate set of directories so it never overwrites your Stable config: -* **macOS** - Replace `~/.warp/` with `~/.warp-preview/` and `Warp-Stable` with `Warp-Preview` in the macOS paths above. The cross-platform `~/.warp/` carve-out (MCP config, skills) is shared with Stable. -* **Windows** - Replace `\warp\Warp\` with `\warp\WarpPreview\` in every path. Logs become `%LOCALAPPDATA%\warp\WarpPreview\data\logs\warp_preview.log*`. The Registry key is `HKCU:\Software\Warp.dev\Warp-Preview`. -* **Linux** - Append `-preview` to each `warp-terminal` directory (for example, `~/.config/warp-terminal-preview/settings.toml`). Logs become `${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal-preview/warp_preview.log*`. +* **macOS** - Replace `~/.warp/` with `~/.warp-preview/` and `Warp-Stable` with `Warp-Preview` in the macOS paths above. The cross-platform `~/.warp/` carve-out (MCP config, skills) is shared with Stable and does not get a `-preview` suffix. +* **Windows** - Replace `\warp\Warp\` with `\warp\WarpPreview\` in every path. Logs become `%LOCALAPPDATA%\warp\WarpPreview\data\logs\warp_preview.log*`. The Registry key is `HKCU:\Software\Warp.dev\WarpPreview` (no hyphen — `Warp-Preview` is the macOS bundle identifier, not the Windows app name). The cross-platform `%USERPROFILE%\.warp\` carve-out (MCP config, skills) is shared with Stable. +* **Linux** - Append `-preview` to each `warp-terminal` directory (for example, `~/.config/warp-terminal-preview/settings.toml`). Logs become `${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal-preview/warp_preview.log*`. The cross-platform `~/.warp/` carve-out (MCP config, skills) is shared with Stable. ## Symlinking Warp's config from WSL -If you run Warp on Windows and also use WSL, you can share Warp's config with your WSL `$HOME` so that tools running inside WSL can read the same themes, tab configs, settings, MCP servers, and agent config. WSL `$HOME` (typically `/home//`) is a separate filesystem from your Windows profile (`%USERPROFILE%`, typically `C:\Users\\`), so nothing is shared automatically — every Warp directory you want to share needs its own symlink. +If you run Warp on Windows and also use WSL, you can share Warp's config with your WSL `$HOME` so that tools running inside WSL can read the same themes, tab configs, settings, MCP servers, and agent config. WSL `$HOME` (typically `/home//`) is a separate Linux filesystem from your Windows profile (`%USERPROFILE%`, typically `C:\Users\\`), so `~/.warp/` and `~/.agents/` inside WSL are **not** automatically the same as the Windows-side directories with those names — every Warp directory you want to share needs its own symlink that points back to the Windows path. -Windows splits Warp's data across four roots (Roaming AppData, Local AppData, and two home-directory paths) and your WSL Linux username is usually different from your Windows account name, so do this from a WSL shell: +Your WSL Linux username (`$USER`) is also usually different from your Windows account name, so don't assume `/mnt/c/Users/$USER` resolves to your Windows profile. Resolve `%USERPROFILE%` through `cmd.exe` and convert it with `wslpath` instead, then run the symlinks from a WSL shell: ```bash -# Set this once to your Windows username. Find it from WSL with: -# cmd.exe /C 'echo %USERNAME%' 2>/dev/null | tr -d '\r' -WIN_USER=YourWindowsUserName +# Resolve the Windows %USERPROFILE% (e.g. C:\Users\Alex) into a WSL path +# (e.g. /mnt/c/Users/Alex). Avoids hard-coding the Windows username or +# assuming it matches your WSL $USER. +WIN_HOME=$(wslpath "$(cmd.exe /C 'echo %USERPROFILE%' 2>/dev/null | tr -d '\r')") # Portable data: themes, tab configs, workflows, launch configurations (Roaming AppData). -ln -s "/mnt/c/Users/$WIN_USER/AppData/Roaming/warp/Warp/data" ~/.warp-windows-data +ln -s "$WIN_HOME/AppData/Roaming/warp/Warp/data" ~/.warp-windows-data # Local config: settings.toml, keybindings.yaml (Local AppData). -ln -s "/mnt/c/Users/$WIN_USER/AppData/Local/warp/Warp/config" ~/.warp-windows-config +ln -s "$WIN_HOME/AppData/Local/warp/Warp/config" ~/.warp-windows-config -# Cross-platform carve-outs: MCP server config and bundled skills. -ln -s "/mnt/c/Users/$WIN_USER/.warp" ~/.warp +# Cross-platform carve-outs that live under Windows %USERPROFILE%: +# MCP server config and bundled skills (Windows-side ~/.warp). +ln -s "$WIN_HOME/.warp" ~/.warp -# Agent config (.agents). -ln -s "/mnt/c/Users/$WIN_USER/.agents" ~/.agents +# Agent config (Windows-side ~/.agents). +ln -s "$WIN_HOME/.agents" ~/.agents ``` -If `~/.warp` or `~/.agents` already exist in WSL, remove or back them up before creating the symlinks. To resolve `%USERPROFILE%` programmatically instead of hard-coding the Windows username, use `wslpath "$(cmd.exe /C 'echo %USERPROFILE%' 2>/dev/null | tr -d '\r')"` from WSL. +If `~/.warp` or `~/.agents` already exist in WSL, remove or back them up first — otherwise `ln` will create the link inside the existing directory instead of replacing it. If you prefer to hard-code the Windows username instead of using `wslpath`, find it from WSL with `cmd.exe /C 'echo %USERNAME%' 2>/dev/null | tr -d '\r'` and replace `$WIN_HOME` above with `/mnt/c/Users/`. :::note Warp on Windows does not currently load config from `~/.warp/tab_configs/` or `~/.warp/themes/` — those paths only work on macOS. If you have config files in those home-directory paths from a different machine, copy or symlink them into the Windows `%APPDATA%\warp\Warp\data\` directory before they take effect.