From 21f15c43bca501e6de4c71196a2ee56d4dc305b9 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Thu, 4 Aug 2022 12:23:06 -0700 Subject: [PATCH] Fix bad merge in shell-integration.md --- docs/editor/codebasics.md | 9 ++- docs/terminal/shell-integration.md | 126 ++++++++++++++++------------- release-notes/v1_70.md | 2 +- 3 files changed, 77 insertions(+), 60 deletions(-) diff --git a/docs/editor/codebasics.md b/docs/editor/codebasics.md index 03b0fa282d..e6aa704a3a 100644 --- a/docs/editor/codebasics.md +++ b/docs/editor/codebasics.md @@ -344,8 +344,13 @@ To fold and unfold only the regions defined by markers use: * Fold Marker Regions (`kb(editor.foldAllMarkerRegions)`) folds all marker regions. * Unfold Marker Regions (`kb(editor.unfoldAllMarkerRegions)`) unfolds all marker regions. -The command `Create Manual Folding Ranges from Selection` allows to create a folding range from the currently selected lines and collapses it. That range is called a *manual* folding range that goes on top of the ranges computed by folding providers. -Manual folding ranges can be removed again with the command `Remove Manual Folding Ranges`. +### Fold selection + +The command **Create Manual Folding Ranges from Selection** (`kb(editor.createFoldingRangeFromSelection)`) creates a folding range from the currently selected lines and collapses it. That range is called a **manual** folding range that goes on top of the ranges computed by folding providers. + +Manual folding ranges can be removed with the command **Remove Manual Folding Ranges** (`kb(editor.removeManualFoldingRanges)`). + +Manual folding ranges are especially useful for cases when there isn't programming language support for folding. ## Indentation diff --git a/docs/terminal/shell-integration.md b/docs/terminal/shell-integration.md index 140a2d5956..0f8e1a6540 100644 --- a/docs/terminal/shell-integration.md +++ b/docs/terminal/shell-integration.md @@ -10,7 +10,7 @@ MetaDescription: Visual Studio Code's embedded terminal can integrate with some # Terminal Shell Integration -Visual Studio Code has the ability to integrate with common shells, allowing the terminal to understand more about what's actually happening inside the shell. This additional information enables some useful [features](#features) such as working directory and command detection, status decorations, and navigation. +Visual Studio Code has the ability to integrate with common shells, allowing the terminal to understand more about what's actually happening inside the shell. This additional information enables some useful [features](#features) such as working directory detection and command detection, decorations and navigation. Supported shells: @@ -21,73 +21,53 @@ Supported shells: ### Automatic script injection -The standard way to activate shell integration is to set the `terminal.integrated.shellIntegration.enabled` setting to `true`. When enabled, the shell integration script is injected into the shell session via shell arguments and/or environment variables. +By default, the shell integration script should automatically activate on supported shells launched from VS Code. This is done by injecting arguments and/or environment variables when the shell session launches. This automatic injection can be disabled by setting `terminal.integrated.shellIntegration.enabled` to `false`. -This standard, easy way will not work for some advanced use cases like in sub-shells, through ssh (when not using the [Remote - SSH extension](/docs/remote/ssh.md)) or for some complex shell setups. The recommended way to enable shell integration for those is [manual installation](#manual-installation). +This standard, easy way will not work for some advanced use cases like in sub-shells, through a regular `ssh` session (when not using the [Remote - SSH extension](/docs/remote/ssh.md)) or for some complex shell setups. The recommended way to enable shell integration for those is [manual installation](#manual-installation). >**Note**: On Windows, you'll need PowerShell 7 (pwsh) for shell integration support. You can install via [https://aka.ms/PSWindows](https://aka.ms/PSWindows). ### Manual installation -To manually install shell integration, the VS Code shell integration script needs to run during your shell's initialization. Where and how to do this depends on the shell and OS you're using. +To manually install shell integration, the VS Code shell integration script needs to run during your shell's initialization. Where and how to do this depends on the shell and OS you're using. When using manual install it's recommended to set `terminal.integrated.shellIntegration.enabled` to `false`, though not mandatory. -When using manual install it's recommended to set `terminal.integrated.shellIntegration.enabled` to `false`, though not mandatory. +> **Tip:** When using the [Insiders build](https://code.visualstudio.com/insiders), replace `code` with `code-insiders` below. -> ℹ️ The method for calling the script will be simplified in the future (see [vscode#153921](https://github.com/microsoft/vscode/issues/153921)) - -#### Windows +**bash** -The script below contains `` which must be replaced by VS Code's installation directory. This defaults to: +Add the following to your `~/.bashrc` file. Run `code ~/.bashrc` in bash to open the file in VS Code. -- User install: `$env:HOMEPATH\AppData\Local\Programs\Microsoft VS Code\` -- System install: `C:\Program Files\Microsoft VS Code` +```sh +[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)" +``` **pwsh** - Add the following to your [PowerShell profile](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.2), replacing `` with VS Code's installation directory. Run `code $Profile` in pwsh to open the file in VS Code. +Add the following to your [PowerShell profile](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.2). Run `code $Profile` in pwsh to open the file in VS Code. - ```pwsh - if ($env:TERM_PROGRAM -eq "vscode") { - . "\resources\app\out\vs\workbench\contrib\terminal\browser\media\shellIntegration.ps1" - } - ``` - -#### Linux and macOS - -The script below contains `` which must be replaced by VS Code's installation directory. This defaults to: - -- Linux: Find by running `echo $(dirname "$(readlink -f "$(which code)")")/../resources` -- macOS: `/Applications/Visual\ Studio\ Code.app/Contents/Resources` +```pwsh +if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" } +``` -**bash** +**zsh** - Add the following to your `~/.bashrc` file, replacing `` with VS Code's installation directory. Run `code ~/.bashrc` in bash to open the file in VS Code. +Add the following to your `~/.zshrc` file. Run `code ~/.zshrc` in bash to open the file in VS Code. - ```sh - if [ "$TERM_PROGRAM" == "vscode" ]; then - . /app/out/vs/workbench/contrib/terminal/browser/media/shellIntegration-bash.sh - fi - ``` +```sh +[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)" +``` -**pwsh** +#### Portability versus performance - Add the following to your [PowerShell profile](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.2), replacing `` with VS Code's installation directory. Run `code $Profile` in pwsh to open the file in VS Code. +The recommended approach above to install shell integration relies on executing our CLI to find the path to the shell integration script, this is great at it works cross-platform and also with all install types provided `code` in on the `$PATH`. This currently launches Node.js in order to fetch the path though which can add a small delay to shell startup. To reduce this, you can inline the script above by resolving the path ahead of time and adding it directly into your init script. - ```pwsh - if ($env:TERM_PROGRAM -eq "vscode") { - . "/app/out/vs/workbench/contrib/terminal/browser/media/shellIntegration.ps1" - } - ``` +```sh +# Output the executable's path first: +code --locate-shell-integration-path bash -**zsh** - - Add the following to your `~/.zshrc` file. Run `code ~/.zshrc` in bash to open the file in VS Code. - - ```sh - if [[ "$TERM_PROGRAM" == "vscode" ]]; then - . /app/out/vs/workbench/contrib/terminal/browser/media/shellIntegration-rc.zsh - fi - ``` +# Add the result of the above to the source statement: +[[ "$TERM_PROGRAM" == "vscode" ]] && . "/path/to/shell/integration/script.sh" +``` ## Features @@ -103,34 +83,55 @@ The decorations can be interacted with to give some contextual actions like re-r The command decorations can be configured with the following settings: +- `terminal.integrated.shellIntegration.decorationsEnabled` - `terminal.integrated.shellIntegration.decorationIcon` - `terminal.integrated.shellIntegration.decorationIconSuccess` - `terminal.integrated.shellIntegration.decorationIconError` ### Command navigation -The commands detected by shell integration feed into the command navigation feature (`Ctrl/Cmd+Up`, `Ctrl/Cmd+Down`) to give it more reliable command positions. This feature allows for quick navigation between commands and selection of their output. +The commands detected by shell integration feed into the command navigation feature (`kbStyle(Ctrl/Cmd+Up)`, `kbStyle(Ctrl/Cmd+Down)`) to give it more reliable command positions. This feature allows for quick navigation between commands and selection of their output. Hold `kbStyle(Shift)` as well to select from the current position to the command. ### Run recent command The **Terminal: Run Recent Command** command surfaces history from various sources in a Quick Pick, providing similar functionality to a shell's reverse search (`kbstyle(Ctrl+R)`). The sources are the current session's history, previous session history for this shell type and the common shell history file. -![The "run recent command" command shows a quick pick with previously run commands that can be filtered similar to the go to file command](images/shell-integration/recent-command.png) +![The "run recent command" command shows a quick pick with previously run commands that can be filtered similar to the go to file command](images/shell-integration/recent-command.png) Some other functionality of the command: +- By default the search mode is "contiguous search", meaning the search term must exactly match. The button on the right of the search input allows switching to fuzzy search. - In the current session section, there is a clipboard icon in the right of the Quick Pick that will open the command output in an editor. - `kbstyle(Alt)` can be held to write the text to the terminal without running it. - The amount of history stored in the previous session section is determined by the `terminal.integrated.shellIntegration.history` setting. -There is currently no keybinding assigned by default but you can add your own keyboard shortcut. For example, below `Ctrl+Space` is set for `runRecentCommand`: +There is currently no keybinding assigned by default but you can add your own keyboard shortcut. For example, the below replaces `kbstyle(Ctrl+R)` with `runRecentCommand`, with `kbstyle(Ctrl+Alt+R)` available to fallback to the shell's regular behavior: -```json +```jsonc { - "key": "ctrl+space", + "key": "ctrl+r", "command": "workbench.action.terminal.runRecentCommand", "when": "terminalFocus" }, +// Allow ctrl+r again to go to the next command in the quick pick +{ + "key": "ctrl+r", + "command": "workbench.action.quickOpenNavigateNextInViewPicker", + "when": "inQuickOpen && inTerminalRunCommandPicker" +}, +// Fallback to the shell's native ctrl+r +{ + "key": "ctrl+alt+r", + "command": "workbench.action.terminal.sendSequence", + "args": { "text": "\u0012"/*^R*/ }, + "when": "terminalFocus" +}, +// Have ctrl+c close the quick pick +{ + "key": "ctrl+c", + "command": "workbench.action.closeQuickOpen", + "when": "inQuickOpen && inTerminalRunCommandPicker" +} ``` ### Go to recent directory @@ -141,9 +142,21 @@ Similar to the run recent command feature, the **Terminal: Go to Recent Director ### Current working directory detection -Shell integration tells us what the current working directory is. This information was impossible on Windows previously without a bunch of hacks and required polling on macOS and Linux which isn't good for performance. +Shell integration tells VS Code what the current working directory of the shell is. This information is not possible to get on Windows without trying to detect the prompt through regex and required polling on macOS and Linux which isn't good for performance. + +One of the biggest features this enables is enhanced resolving of links in the terminal. Take a link `package.json` for example, when the link is activated while shell integration is disabled this will open a search quick pick with `package.json` as the filter if there are multiple `package.json` files in the workspace. When shell integration is enabled however, it will open the `package.json` file in the current folder directly because the current location is known. This allows the output of `ls` for example to reliabily open the correct file. + +The current working directory is also used to show the directory in the terminal tab, in the run recent command quick pick and for the `"terminal.integrated.splitCwd": "inherited"` feature. + +### Extended PowerShell keybindings + +Windows' console API allows for more keybindings than Linux/macOS terminals, since VS Code's terminal emulates the latter even on Windows there are some PowerShell keybindings that aren't possible using the standard means due to lack of VT encoding such as `kbstyle(Ctrl+Space)`. Shell integration allows VS Code to attach a custom keybindings to send a special sequence to PowerShell which then gets handled in the shell integration script and forwarded to the proper key handler.The following keybindings should work in PowerShell when shell integration is enabled: -The current working directory is used to resolve links against, showing the directory a recent command ran within as well as the `"terminal.integrated.splitCwd": "inherited"` feature. +- `kbstyle(Ctrl+Space)`: Defaults to `MenuComplete` on Windows only +- `kbstyle(Alt+Space)`: Defaults to `SetMark` on all platforms +- `kbstyle(Shift+Enter)`: Defaults to `AddLine` on all platforms +- `kbstyle(Shift+End)`: Defaults to `SelectLine` on all platforms +- `kbstyle(Shift+Home)`: Defaults to `SelectBackwardsLine` on all platforms ## Supported escape sequences @@ -185,7 +198,6 @@ There are several cases where automatic injection doesn't work, here are some co PROMPT_COMMAND=prompt ``` -- `$HISTCONTROL` contains the `erasedups` option, this changes functionality of the `history` command that shell integration depends upon. - Some shell plugins may disable VS Code's shell integration explicitly by unsetting `$VSCODE_SHELL_INTEGRATION` when they initialize. ### Why are command decorations showing when the feature is disabled? @@ -193,7 +205,7 @@ There are several cases where automatic injection doesn't work, here are some co The likely cause of this is that your system has shell integration for another terminal installed that [VS Code understands](#final-term-shell-integration). If you don't want any decorations, you can hide them with the following setting: ```json -"terminal.integrated.shellIntegration.decorationsEnabled": false +"terminal.integrated.shellIntegration.decorationsEnabled": never ``` -Alternatively, you could remove the shell integration script from your shell rc/startup script but you will lose access to command-aware features like [command navigation](#command-navigation). +Alternatively, you could remove the shell integration script from your shell rc/startup script but you will lose access to command-aware features like [command navigation](#command-navigation). \ No newline at end of file diff --git a/release-notes/v1_70.md b/release-notes/v1_70.md index be7ed898a4..73de97ff24 100644 --- a/release-notes/v1_70.md +++ b/release-notes/v1_70.md @@ -26,7 +26,7 @@ Welcome to the July 2022 release of Visual Studio Code. There are many updates i >If you'd like to read these release notes online, go to [Updates](https://code.visualstudio.com/updates) on [code.visualstudio.com](https://code.visualstudio.com). -**Join us live** at the [VS Code team's livestream](https://code.visualstudio.com/livestream) on Thursday, August 4 at 8am Pacific (4pm London) to see a demo of what's new in this release, and ask us questions live. +**Watch the release party:** Listen in as the VS Code team discusses some of the new features. You can find the [recording of the event](https://www.youtube.com/watch?v=wFmAyna4r5E) on our YouTube channel. **Insiders:** Want to try new features as soon as possible? You can download the nightly [Insiders](https://code.visualstudio.com/insiders) build and try the latest updates as soon as they are available.