Skip to content

Latest commit

 

History

History
136 lines (105 loc) · 7.21 KB

README.md

File metadata and controls

136 lines (105 loc) · 7.21 KB
Raw

wsl-alias

Create aliases of Linux commands to access them from Windows command line or PowerShell!

This is a simple Windows batch script and bash command wrapper that allows you to pass commands to your WSL (Windows Subsystem for Linux) from Windows and adds a few sweet features like aliases and automatic mounting. What that means is you can install PHP, NodeJS, etc. in your WSL and use them from Windows!

If you still don't understand what that means, here are a few examples (all commands are executed from the Windows PowerShell):

> cd C:\Users\User\Documents\repo
> b git commit -m "commit message"

> b apt-get install php-cli
> b wsl-alias add php php
> php -v

> cd Z:\Projects
> b pwd
/mnt/z/Projects

Features

Here's a quick overview of the features:

  • pass commands to WSL without escaping them
  • use Linux programs and scripts as if they were installed in Windows
  • translates your current Windows path into the WSL path (for all drives)
  • translates Windows paths in command arguments to WSL paths (relative and absolute) - thanks to hustlahusky
  • a single file with environment variables and code that will be loaded when executing commands or entering an interactive shell (solves this)
  • automatically mount the drives that WSL doesn't - with different filesystems and even network drives (solves this)

Installation

First of all, make sure you're running the Spring Creators update or newer and have installed Ubuntu on Windows 10 (or another distribution) from the Windows Store. Next, start up wsl (using the command bash or wsl) on Windows 10 as the default user and run this command:

bash <(curl -o- https://raw.githubusercontent.com/leongrdic/wsl-alias/v2.4/install.sh)

The install script will clone this repository and put it into your home directory with right permissions and help you configure access to the mount command withougt a password. You will be asked to choose the default alias (command that will actually call your default shell). You can just leave it empty, which sets it to b.

Finally you will get a message from the installer with a path that you should copy and put into your user environment variable on Windows. (here's a beautiful tutorial)

All you have to do now is open the command line or PowerShell and start typing:

b          # opens an interactive shell
b [cmd]    # executes the command cmd in WSL

note: if you chose a different default alias, use it instead of b

Aliases

Aliases allow you to call Linux commands from Windows. They pass all the arguments and the current directory and allow you to benefit of the auto-mount feature.

Use the command wsl-alias inside WSL as following:

wsl-alias list                       # lists all aliases
wsl-alias add [name] [command]       # adds a new alias
wsl-alias remove [name]              # removes an existing alias

Make sure you don't remove the default alias (the one you specified during installation) or you might have to reinstall wsl-alias. This is because the command wsl-alias only works when you're accessing WSL using one of the existing aliases.

env.sh script

You can use the shell script ~/.wsl-alias/env.sh to define environment variables, mount drives or run other scripts every time you use any of your aliases. For example you can include the nvm initialization code or ssh-agent setup there.

This script also directly serves as a replacement for .bashrc, of course only for user-added commands and variables. (note they will only be accessible when using one of your aliases)

The $wslalias_interactive variable provides a way to find out if the user has passed any arguments with the default alias

$wslalias_interactive == "0"     # a command was passed
$wslalias_interactive == "1"     # no commands passed

This might be useful if, for example, you want to set up a new ssh-agent only if the shell is interactive.

Setting an environment variable:

export variable="value"

Auto mounting

When you call any alias, your current directory is taken from Windows and translated into a WSL path (e.g. /mnt/c/Users). Windows already does this but not for all drives. That's where wsl-alias comes in - we check if the drive isn't already mounted and do it without prompting you for the root password!

Because WSL only lives as long as its last background process, your drive could get unmounted after each command (if there are no background wsl processes running). That's why we provide you with a way to always mount your drive, whether you're entering the interactive shell (using the default alias) or just running a command - add the following line to the env.sh file:

sudo mount -o uid=[USER_UID],gid=[USER_GID] -t drvfs [DRIVE_LETTER]: /mnt/[DRIVE_LETTER]

Avoid mounting drives on each alias run

You can use an approach like this one (props to that guy) to make WSL always run in background so that you always have a background wsl process running.

Escaping commands

PowerShell

b echo "a \""b\"" c"     # prints: a "b" c
b echo "a 'b' c"         # prints: a 'b' c
b echo 'a \"b\" c'       # prints: a "b" c
b echo 'a ''b'' c'       # prints: a 'b' c

cmd

b echo "a \"b\" c"       # prints: a "b" c
b echo "a 'b' c"       # prints: a 'b' c
b echo 'a "b" c'       # prints: a "b" c
# not possible to escape single quotes inside single quotes

PowerShell is recommended because of better syntax support, but both should do for basic functionality.

Limitations

Unfortunately you can't pass all symbols through wsl-alias. Those include redirectors (>, >>, <, etc.), separators (;, &&, etc.). But you can always open an interactive shell and execute commands just like you would on Linux!

Troubleshooting

The most common problems...

  1. are you running Windows 10 version 1803 A.K.A. Spring Creators Update (build 17046 or later)?
  2. have you updated the PATH environment variable in Windows?
  3. did you install wsl-alias as the default WSL user?
  4. did you accidentally remove the default alias?
  5. is bash installed in WSL? (while bash is required, wsl-alias can work with any other default shell)

Reinstallation or uninstallation

If you want to reinstall wsl-alias simply run the installer command again.

To uninstall just remove the ~/.wsl-alias directory like so:

rm -rf ~/.wsl-alias

Security

wsl-alias sets the permission of the /mnt directory to 777, so you can create mountpoints for new drives without explicit permission. This shouldn't be considered a security risk, except if you have some important data in that directory protected with the Linux permissions.

An optional entry to /etc/sudoers can be set while installing to allow wsl-alias to allow mounting a drive (access to the mount and umount binaries) without typing a password.

If you find any security related bugs, please open an issue or better yet contact me personally. I do not guarantee that this code is 100% secure and it should be used at your own risk.