# WSL

Source: https://athas.dev/docs/wsl

Open and edit Windows Subsystem for Linux projects

Athas supports Windows Subsystem for Linux projects on Windows.

WSL projects use Linux paths inside the selected distribution, while Athas keeps
the workspace identity as a `wsl://` path such as `wsl://Ubuntu/home/me/project`.

## Requirements

- Windows with WSL installed
- At least one installed WSL distribution
- Project files stored inside the distribution filesystem, such as
  `/home/me/project`

Athas discovers distributions with `wsl --list --verbose`, the same WSL command
documented in [Microsoft's WSL command reference](https://learn.microsoft.com/en-us/windows/wsl/basic-commands).
Microsoft also recommends storing Linux project files inside the Linux filesystem
instead of editing them from `/mnt/c` when working with Linux tools; see
[Working across Windows and Linux file systems](https://learn.microsoft.com/en-us/windows/wsl/filesystems).

## Open a WSL Project

1. Open the project picker
2. Select a WSL distribution
3. Enter the Linux project path, such as `/home/me/project`
4. Open the project

The project opens as a normal Athas workspace. Recent WSL projects and project
tabs restore across restarts.

## Files

WSL workspaces support the normal file actions:

- Browse folders and files
- Open and save files
- Create files and folders
- Rename, move, duplicate, and delete paths
- Follow symlinks inside the same distribution
- Reveal files in Windows Explorer through the WSL UNC path

Athas keeps WSL paths inside the selected distribution. Moving files between a
WSL distribution and a local Windows folder is not treated as a rename.

## Search

Quick Open, file-tree search, and content search work against the WSL project
through Athas' WSL file provider.

## Terminal

When a terminal is created from a WSL workspace, Athas starts `wsl.exe` with the
matching distribution and Linux working directory. WSL distributions also appear
as selectable terminal shells on Windows.

## Git

Git repositories inside WSL workspaces work with Athas' Git views:

- Repository discovery
- Status
- Diffs
- Staging and unstaging
- Commits
- Branches, tags, stashes, blame, and history

Git paths are resolved through the WSL filesystem bridge while the editor keeps
display paths in `wsl://` form.

## Paths

Athas displays WSL project paths as:

```text
wsl://<distribution>/<linux-path>
```

Examples:

```text
wsl://Ubuntu/home/me/project
wsl://Debian/etc/nginx
```

Use Linux paths when opening projects or entering terminal working directories.
Use Windows paths only for local Windows projects.

## Troubleshoot a distribution

Confirm the distribution starts from Windows with `wsl -d <distribution>` and that the Linux path exists for your user. Keep Windows and Linux paths distinct. See [Terminal](https://athas.dev/docs/terminal) for shell profiles and [Troubleshooting](https://athas.dev/docs/troubleshooting) for reports.