Skip to content

Commit

Permalink
Add support for commandline args to wt.exe (#4023)
Browse files Browse the repository at this point in the history
## Summary of the Pull Request

Adds support for commandline arguments to the Windows Terminal, in accordance with the spec in #3495

## References

* Original issue: #607
* Original spec: #3495

## PR Checklist
* [x] Closes #607
* [x] I work here
* [x] Tests added/passed
* [ ] We should probably add some docs on these commands
* [x] The spec (#3495) needs to be merged first!

## Detailed Description of the Pull Request / Additional comments

🛑 **STOP** 🛑 - have you read #3495 yet? If you haven't, go do that now.

This PR adds support for three initial sub-commands to the `wt.exe` application:
* `new-tab`: Used to create a new tab.
* `split-pane`: Used to create a new split.
* `focus-tab`: Moves focus to another tab.

These commands are largely POC to prove that the commandlines work. They're not totally finished, but they work well enough. Follow up work items will be filed to track adding support for additional parameters and subcommands

Important scenarios added:
* `wt -d .`: Open a new wt instance in the current working directory #878
* `wt -p <profile name>`: Create a wt instance running the given profile, to unblock  #576, #1357, #2339
* `wt ; new-tab ; split-pane -V`: Launch the terminal with multiple tabs, splits, to unblock #756 

## Validation Steps Performed

* Ran tests
* Played with it a bunch
  • Loading branch information
zadjii-msft authored and msftbot[bot] committed Jan 27, 2020
1 parent f0e6037 commit 830c22b
Show file tree
Hide file tree
Showing 30 changed files with 10,089 additions and 53 deletions.
7,821 changes: 7,821 additions & 0 deletions dep/CLI11/CLI11.hpp

Large diffs are not rendered by default.

5 changes: 5 additions & 0 deletions dep/CLI11/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# CLI11

Taken from [release v1.8.0](https://github.com/CLIUtils/CLI11/releases/tag/v1.8.0), source commit
[13becad](https://github.com/CLIUtils/CLI11/commit/13becaddb657eacd090537719a669d66d393b8b2)

156 changes: 156 additions & 0 deletions doc/user-docs/UsingCommandlineArguments.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
---
author: Mike Griese @zadjii-msft
created on: 2020-01-16
last updated: 2020-01-17
---

# Using the `wt.exe` Commandline

As of [#4023], the Windows Terminal now supports accepting arguments on the
commandline, to enable launching the Terminal in a non-default configuration.
This document serves as a reference for all the parameters you can currently
pass, and gives some examples of how to use the `wt` commandline.

> NOTE: If you're running the Terminal built straight from the repo, you'll need
> to use `wtd.exe` and `wtd` instead of `wt.exe` and `wt`.
1. [Commandline Reference](#Reference)
1. [Commandline Examples](#Examples)

## Reference

### Options

#### `--help,-h,-?,/?,`
Display the help message.

## Subcommands

#### `new-tab`

`new-tab [terminal_parameters]`

Opens a new tab with the given customizations. On its _first_ invocation, also
opens a new window. Subsequent `new-tab` commands will all open new tabs in the
same window.

**Parameters**:
* `[terminal_parameters]`: See [[terminal_parameters]](#terminal_parameters).


#### `split-pane`

`split-pane [--target,-t target-pane] [-H]|[-V] [terminal_parameters]`

Creates a new pane in the currently focused tab by splitting the given pane
vertically or horizontally.

**Parameters**:
* `--target,-t target-pane`: Creates a new split in the given `target-pane`.
Each pane has a unique index (per-tab) which can be used to identify them.
These indicies are assigned in the order the panes were created. If omitted,
defaults to the index of the currently focused pane.
* `-H`, `-V`: Used to indicate which direction to split the pane. `-V` is
"vertically" (think `[|]`), and `-H` is "horizontally" (think `[-]`). If
omitted, defaults to "auto", which splits the current pane in whatever the
larger dimension is. If both `-H` and `-V` are provided, defaults to vertical.
* `[terminal_parameters]`: See [[terminal_parameters]](#terminal_parameters).

#### `focus-tab`

`focus-tab [--target,-t tab-index]|[--next,-n]|[--previous,-p]`

Moves focus to a given tab.

**Parameters**:

* `--target,-t tab-index`: moves focus to the tab at index `tab-index`. If
omitted, defaults to `0` (the first tab). Will display an error if combined
with either of `--next` or `--previous`.
* `-n,--next`: Move focus to the next tab. Will display an error if combined
with either of `--previous` or `--target`.
* `-p,--previous`: Move focus to the previous tab. Will display an error if
combined with either of `--next` or `--target`.


#### `[terminal_parameters]`

Some of the preceding commands are used to create a new terminal instance.
These commands are listed above as accepting `[terminal_parameters]` as a
parameter. For these commands, `[terminal_parameters]` can be any of the
following:

`[--profile,-p profile-name] [--startingDirectory,-d starting-directory] [commandline]`

* `--profile,-p profile-name`: Use the given profile to open the new tab/pane,
where `profile-name` is the `name` or `guid` of a profile. If `profile-name`
does not match _any_ profiles, uses the default.
* `--startingDirectory,-d starting-directory`: Overrides the value of
`startingDirectory` of the specified profile, to start in `starting-directory`
instead.
* `commandline`: A commandline to replace the default commandline of the
selected profile. If the user wants to use a `;` in this commandline, it
should be escaped as `\;`.


## Examples

### Open Windows Terminal in the current directory

```
wt -d .
```

This will launch a new Windows Terminal window in the current working directory.
It will use your default profile, but instead of using the `startingDirectory`
property from that it will use the current path. This is especially useful for
launching the Windows Terminal in a directory you currently have open in an
`explorer.exe` window.

### Opening with multiple panes

If you want to open with multiple panes in the same tab all at once, you can use
the `split-pane` command to create new panes.

Consider the following commandline:

```
wt ; split-pane -p "Windows PowerShell" ; split-pane -H wsl.exe
```

This creates a new Windows Terminal window with one tab, and 3 panes:
* `wt`: Creates the new tab with the default profile
* `split-pane -p "Windows PowerShell"`: This will create a new pane, split from
the parent with the default profile. This pane will open with the "Windows
PowerShell" profile
* `split-pane -H wsl.exe`: This will create a third pane, slit _horizontally_
from the "Windows PowerShell" pane. It will be running the default profile,
and will use `wsl.exe` as the commandline (instead of the default profile's
`commandline`).

### Running a specific linux distro in a specific distro

Say you wanted to open a "Debian" WSL instance in `C:\Users`. According to the
above reference, you might try:

```
wt -d c:\Users wsl -d Debian
```

Unfortunately, this _won't_ work, and will give you an error about "expected
exactly 1 argument to `--startingDirectory`, got 2". This is because we'll
erroneously try to parse the `-d Debian` parameter as a second
`--startingDirectory` value. This is unexpected, and is a bug currently tracked
in [#4277].

As a workaround, you can try the following commandline:

```
wt -d c:\Users -- wsl -d Debian
```

In this commandline, the `--` will indicate to the Terminal that it should treat
everything after that like a commandline.

[#4023]: https://github.com/microsoft/terminal/pull/4023
[#4277]: https://github.com/microsoft/terminal/issues/4277
Loading

0 comments on commit 830c22b

Please sign in to comment.