|
| 1 | +# WSL2 + Windows Filesystem |
| 2 | + |
| 3 | +Charter works well under WSL2, but projects that live on the Windows filesystem (`/mnt/c/...`) require awareness of a few cross-filesystem differences. This guide covers installation, path considerations, and common gotchas. |
| 4 | + |
| 5 | +## Install |
| 6 | + |
| 7 | +### Linux-native path (recommended) |
| 8 | + |
| 9 | +For best performance and fewest surprises, keep your project on a Linux-native path: |
| 10 | + |
| 11 | +```bash |
| 12 | +mkdir -p ~/projects && cd ~/projects |
| 13 | +git clone <your-repo> |
| 14 | +cd <your-repo> |
| 15 | +pnpm add -Dw @stackbilt/cli # works without extra flags |
| 16 | +``` |
| 17 | + |
| 18 | +Linux-native paths avoid the NTFS translation layer entirely. File watches (`wrangler dev`, `vitest --watch`) are faster, and atomic renames work correctly. |
| 19 | + |
| 20 | +### Windows filesystem path (`/mnt/c/...`) |
| 21 | + |
| 22 | +If your project must stay on the Windows filesystem (shared with Windows-native editors, corporate policies, etc.), pnpm installs may fail with: |
| 23 | + |
| 24 | +``` |
| 25 | +ERR_PNPM_EACCES EACCES: permission denied, rename |
| 26 | + '...node_modules/.pnpm/..._tmp_...' -> '...' |
| 27 | +``` |
| 28 | + |
| 29 | +This is a known WSL2/NTFS limitation with atomic renames. Use `--force` to work around it: |
| 30 | + |
| 31 | +```bash |
| 32 | +cd /mnt/c/Users/<you>/projects/<repo> |
| 33 | +pnpm add -Dw @stackbilt/cli --force |
| 34 | +``` |
| 35 | + |
| 36 | +npm and yarn are not affected by this issue: |
| 37 | + |
| 38 | +```bash |
| 39 | +npm install --save-dev @stackbilt/cli |
| 40 | +``` |
| 41 | + |
| 42 | +## Path considerations |
| 43 | + |
| 44 | +WSL2 exposes the Windows filesystem under `/mnt/c/`, `/mnt/d/`, etc. Charter resolves paths relative to the working directory, so everything works transparently as long as you stay consistent. |
| 45 | + |
| 46 | +| Context | Example path | |
| 47 | +|---------|-------------| |
| 48 | +| Linux-native | `~/projects/my-app/.ai/core.adf` | |
| 49 | +| Windows mount | `/mnt/c/Users/you/projects/my-app/.ai/core.adf` | |
| 50 | +| Windows (from Explorer) | `C:\Users\you\projects\my-app\.ai\core.adf` | |
| 51 | + |
| 52 | +A few things to keep in mind: |
| 53 | + |
| 54 | +- **Stay on one side.** Do not mix `/mnt/c/` paths and `C:\` paths in the same workflow. Charter and git both expect POSIX paths inside WSL2. |
| 55 | +- **Symlinks across filesystems.** Symlinks from a Linux-native path into `/mnt/c/` (or vice versa) can behave unexpectedly. Keep `.ai/`, `.charter/`, and `node_modules/` on the same filesystem as the project root. |
| 56 | +- **VS Code Remote - WSL.** When using VS Code with the WSL extension, the integrated terminal runs inside WSL2 and sees POSIX paths. This is the expected setup for Charter. |
| 57 | + |
| 58 | +## Common gotchas |
| 59 | + |
| 60 | +### Line endings |
| 61 | + |
| 62 | +Windows uses `\r\n`; Linux uses `\n`. Git's `core.autocrlf` setting controls conversion at checkout. ADF files should use `\n` (LF) to avoid parse issues. |
| 63 | + |
| 64 | +Recommended `.gitattributes` entry: |
| 65 | + |
| 66 | +```gitattributes |
| 67 | +*.adf text eol=lf |
| 68 | +``` |
| 69 | + |
| 70 | +If ADF files already have `\r\n` endings, fix them once: |
| 71 | + |
| 72 | +```bash |
| 73 | +# Inside WSL2 |
| 74 | +find .ai -name '*.adf' -exec dos2unix {} + |
| 75 | +git add .ai/ |
| 76 | +git commit -m "fix: normalize ADF line endings to LF" |
| 77 | +``` |
| 78 | + |
| 79 | +### File permissions |
| 80 | + |
| 81 | +NTFS does not support Unix permission bits. Files on `/mnt/c/` may appear with `0777` permissions, and `chmod` has no effect. This is cosmetic -- Charter does not check file permissions -- but it can produce noisy `git diff` output. |
| 82 | + |
| 83 | +To suppress permission noise in git: |
| 84 | + |
| 85 | +```bash |
| 86 | +git config core.fileMode false |
| 87 | +``` |
| 88 | + |
| 89 | +### Performance |
| 90 | + |
| 91 | +File I/O on `/mnt/c/` is significantly slower than on the Linux-native filesystem due to the 9P protocol translation layer. Operations that touch many files (`pnpm install`, `charter drift`, `vitest`) will be noticeably faster on a Linux-native path. |
| 92 | + |
| 93 | +If you need the project on the Windows side for other tools, consider keeping a Linux-native working copy and syncing with git: |
| 94 | + |
| 95 | +```bash |
| 96 | +# Clone to Linux-native path for development |
| 97 | +git clone /mnt/c/Users/you/projects/my-app ~/projects/my-app |
| 98 | +cd ~/projects/my-app |
| 99 | +pnpm install |
| 100 | +npx charter doctor |
| 101 | +``` |
| 102 | + |
| 103 | +## Verify the setup |
| 104 | + |
| 105 | +After installing, confirm Charter is working: |
| 106 | + |
| 107 | +```bash |
| 108 | +npx charter doctor |
| 109 | +npx charter --version |
| 110 | +``` |
| 111 | + |
| 112 | +If `doctor` reports all checks passing, you are good to go. See [Getting Started](./getting-started.md) for next steps. |
0 commit comments