Skip to content

Commit

Permalink
docs(README): Add fish installation instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
chvolkmann committed Feb 14, 2021
1 parent 474657c commit e8bb540
Showing 1 changed file with 32 additions and 2 deletions.
34 changes: 32 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,59 +3,83 @@
Open a file in your locally running VS Code instance from any terminal.

## Motivation

VS Code supports opening files with the terminal using `code /path/to/file`. While this is possible in **WSL sessions** and **remote SSH sessions** if the integrated terminal is used, it is currently not possible for arbitrary terminals. Say, you have just SSH'd into a remote server using your favorite terminal and would like to open a webserver config file in your local VS Code instance.

You would have to get to VS Code, connect to your server through a remote session and find the file in VS Code's file browser.
This utility enables you to call `code .` instead, just as you would in a WSL session.

## Installation

### Requirements

Requires Python 3 and a **Linux** machine you want to connect to. Tested under Python 3.8, but slightly lower should work fine.

### VS Code Server

You need to set up VS Code Server before using this utility. For this, connect to your target in a remote SSH session.
Afterwards, you should have a folder `.vscode-server` in your home directory.

### Shell Integration

If you are familiar with `virtualenv`, `conda`, etc., this will be familiar.

#### Bash

Execute this and place it in your `.bashrc`

```bash
source activate.sh
```

#### Fish

Fish users can alternatively install an accompanying [fish plugin](https://github.com/chvolkmann/code-connect-fish-plugin).

```fish
fisher install chvolkmann/code-connect-fish-plugin
```

If you want to do it manually, execute this and place it in your `config.fish`

```fish
source activate.fish
```


## Usage

First, run

```bash
code-connect
```

This will provide you with the `code` command from your server's VS Code Server installation. It also sets the environment variable `VSCODE_IPC_HOOK_CLI` to a valid IPC socket.

Then you're free to use

```bash
code /path/to/file
```

Note that you need to have an active instance of VS Code running.

### Deactivating

To unlink the `code` executable and unset the environment variable, use

```bash
code-disconnect
```

And to disable `code-connect` and unset the aliases, use

```bash
deactivate
```

## How it works

VS Code uses datagram sockets to communicate between a terminal and the rendering window.

The integrated terminal as well as the WSL terminal spawn an IPC socket. You also create one when manually attaching a remote SSH session. These sockets can be found in the folder VS Code Server.
Expand All @@ -70,20 +94,25 @@ VS Code communicates the presence of an active IPC connection with the environme
You can verify this by opening a connection to your remote machine. In one case, you use VS Code's integrated terminal. In the other case, you use any other terminal.

Run

```bash
echo $VSCODE_IPC_HOOK_CLI
```

which displays an output in the integrated terminal, but not on the other one.

In order, every socket is checked to see if it is listening. For this, the following snippet based on [this answer on StackOverflow](https://unix.stackexchange.com/a/556790) was used.

```bash
socat -u OPEN:/dev/null UNIX-CONNECT:/path/to/socket
```

This returns `0` if and only if there's something listening.

The script `code_connect.py` does all of the above steps and outputs a string to stdout. Currently, output for **bash** and **fish** is supported.

Sample output (bash):

```bash
export VSCODE_IPC_HOOK_CLI="/run/user/1000/vscode-ipc-dd85cff3-04c7-4ca6-9c06-229acd73008c.sock"
alias code="/home/user/.vscode-server/bin/622cb03f7e070a9670c94bae1a45d78d7181fbd4/bin/code"
Expand All @@ -92,4 +121,5 @@ alias code="/home/user/.vscode-server/bin/622cb03f7e070a9670c94bae1a45d78d7181fb
`code-connect` is an alias sourcing the output of `code_connect.py` into the current shell session.

## Credit
- Based on an [answer on StackOverflow](https://stackoverflow.com/a/60949722) by [stabledog](https://stackoverflow.com/users/237059/Stabledog)

- Based on an [answer on StackOverflow](https://stackoverflow.com/a/60949722) by [stabledog](https://stackoverflow.com/users/237059/Stabledog)

0 comments on commit e8bb540

Please sign in to comment.