Merge branch 'master' into live

Author: craigloewen-msft

WSL/docfx.json

@@ -20,6 +20,7 @@
       {
         "files": [
           "**/*.png",
+          "**/*.gif",
           "**/*.jpg"
         ],
         "exclude": [

WSL/media/git-versions.gif

@@ -16,6 +16,12 @@
       href: install-on-server.md
     - name: Create a user account & password
       href: user-support.md
+- name: Tutorials
+  items: 
+    - name: Get started with VS Code
+      href: tutorials/wsl-vscode.md
+    - name: Get started with Git
+      href: tutorials/wsl-git.md
 - name: How-to
   items:
     - name: Interoperability commands

WSL/media/vscode-remote-command-palette.png

@@ -0,0 +1,80 @@
+---
+title: Get started using Git on Windows Subsystem for Linux
+description: Learn how to set up Git for version control on the Windows Subsystem for Linux.
+keywords: wsl, windows, windowssubsystem, gnu, linux, bash, git, github, version control
+ms.date: 06/04/2020
+ms.topic: article
+ms.localizationpriority: medium
+---
+
+# Get started using Git on Windows Subsystem for Linux
+
+Git is the most commonly used version control system. With Git, you can track changes you make to files, so you have a record of what has been done, and have the ability to revert to earlier versions of the files if needed. Git also makes collaboration easier, allowing changes by multiple people to all be merged into one source.
+
+## Git can be installed on Windows AND on WSL
+
+An important consideration: when you enable WSL and install a Linux distribution, you are installing a new file system, separated from the Windows NTFS C:\ drive on your machine. In Linux, drives are not given letters. They are given mount points. The root of your file system `/` is the mount point of your root partition, or folder, in the case of WSL. Not everything under `/` is the same drive. For example, on my laptop, I've installed two version of Ubuntu (20.04 and 18.01), as well as Debian. If I open those distributions, select the root directory with the command `cd ~`, and then enter the command `explorer.exe .`, Windows File Explorer will open and show me the directory path for that distribution.
+
+| Linux distro | Windows Path to access home folder |
+| ----------- | ----------- |
+| Ubuntu 20.04 | `\\wsl$\Ubuntu-20.04\home\username` |
+| Ubuntu 18.01 | `\\wsl$\Ubuntu-18.04\home\username` |
+| Debian | `\\wsl$\Debian\home\username` |
+| Windows PowerShell | `C:\Users\username` |
+
+> [!TIP]
+> If you are seeking to access the Windows file directory from your WSL distribution command line, instead of `C:\Users\username`, the directory would be accessed using `/mnt/c/Users/username`, because the Linux distribution views your Windows file system as a mounted drive.
+
+You will need to install Git on each file system that you intend to use it with.
+
+![Showing Git versions by distro](../media/git-versions.gif)
+
+## Installing Git
+
+Git comes already installed with most of the Windows Subsystem for Linux distributions, however, you may want to update to the latest version and you will need to set up your git config file.
+
+To install Git, see the [Git Download for Linux](https://git-scm.com/download/linux) site. Each Linux distribution has their own package manager and install command. For example, to install Git on the Alpine distribution, use: `apk add git`. You also may want to [install Git for Windows](https://git-scm.com/download/win) if you haven't already.
+
+## Git config file setup
+
+To set up your Git config file, open a command line for the distribution you're working in and enter: `git config --global user.name "Your Name"` and then, `git config --global user.email "[email protected]"`. Replacing the content in quotations with the name and email address that you used to create your Git account.
+
+> [!TIP]
+> If you don't yet have a Git account, you can [sign-up for one on GitHub](https://github.com/join). If you've never worked with Git before, [GitHub Guides](https://guides.github.com/) can help you get started. If you need to edit your git config, you can do so with a built-in text editor like nano: `nano ~/.gitconfig`.
+
+We recommend that you [secure your account with two-factor authentication (2FA)](https://help.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa).
+
+## Git Credential Manager setup
+
+Git Credential Manager enables you to authenticate a remote Git server, even if you have a complex authentication pattern like two-factor authentication, Azure Active Directory, or using SSH remote URLs that require an SSH key password for every git push. Git Credential Manager integrates into the authentication flow for services like GitHub and, once you're authenticated to your hosting provider, requests a new authentication token. It then stores the token securely in the [Windows Credential Manager](https://support.microsoft.com/help/4026814/windows-accessing-credential-manager). After the first time, you can use git to talk to your hosting provider without needing to re-authenticate. It will just access the token in the Windows Credential Manager.
+
+To set up Git Credential Manager for use with a WSL distribution, open your distribution and enter this command:
+
+```Bash
+git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe"
+```
+
+Now any git operation you perform within your WSL distribution will use the credential manager. If you already have credentials cached for a host, it will access them from the credential manager. If not, you'll receive a dialog response requesting your credentials, even if you're in a Linux console.
+
+## Adding a Git Ignore file
+
+We recommend adding a [.gitignore file](https://help.github.com/en/articles/ignoring-files) to your projects. GitHub offers [a collection of useful .gitignore templates](https://github.com/github/gitignore) with recommended .gitignore file setups organized according to your use-case.
+
+If you choose to [create a new repo using the GitHub website](https://help.github.com/articles/create-a-repo), there are check boxes available to initialize your repo with a README file, .gitignore file set up for your specific project type, and options to add a license if you need one.
+
+## Git and VS Code
+
+Visual Studio Code comes with built-in support for Git, including a source control tab that will show your changes and handle a variety of git commands for you. Learn more about [VS Code's Git support](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support).
+
+## Git line endings
+
+If you are working with the same repository folder between Windows, WSL, or a container, be sure to set up consistent line endings.
+
+Since Windows and Linux use different default line endings, Git may report a large number of modified files that have no differences aside from their line endings. To prevent this from happening, you can disable line ending conversion using a `.gitattributes` file or globally on the Windows side. See this [VS Code doc about resolving Git line ending issues](https://code.visualstudio.com/docs/remote/troubleshooting#_resolving-git-line-ending-issues-in-containers-resulting-in-many-modified-files).
+
+## Additional resources
+
+* [WSL & VS Code](./wsl-vscode.md)
+* [GitHub Learning Lab: Online courses](https://lab.github.com/)
+* [Git Visualization Tool](http://git-school.github.io/visualizing-git/)
+* [Git Tools - Credential Storage](https://git-scm.com/book/it/v2/Git-Tools-Credential-Storage)

WSL/media/vscode-remote-wsl-extensions.png

@@ -0,0 +1,109 @@
+---
+title: Get started using VS Code with Windows Subsystem for Linux
+description: Learn how to set up VS Code to author and debug code using the Windows Subsystem for Linux.
+keywords: wsl, windows, windowssubsystem, gnu, linux, bash, vs code, remote extension, debug, path, visual studio
+ms.date: 05/28/2020
+ms.topic: article
+ms.localizationpriority: medium
+---
+
+# Get started using Visual Studio Code with Windows Subsystem for Linux
+
+Visual Studio Code, along with the Remote - WSL extension, enables you to use WSL as your full-time development environment directly from VS Code. You can:
+
+* develop in a Linux-based environment
+* use Linux-specific toolchains and utilities
+* run and debug your Linux-based applications from the comfort of Windows while maintaining access to productivity tools like Outlook and Office
+* use the VS Code built-in terminal to run your Linux distribution of choice
+* take advantage of VS Code features like [Intellisense code completion](https://code.visualstudio.com/docs/editor/intellisense), [linting](https://code.visualstudio.com/docs/python/linting), [debug support](https://code.visualstudio.com/docs/nodejs/nodejs-debugging), [code snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets), and [unit testing](https://code.visualstudio.com/docs/python/testing)
+* easily manage your version control with VS Code's built-in [Git support](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support)
+* run commands and VS Code extensions directly on your WSL projects
+* edit files in your Linux or mounted Windows filesystem (for example /mnt/c) without worrying about pathing issues, binary compatibility, or other cross-OS challenges
+
+## Install VS Code and the Remote WSL extension
+
+* Visit the [VS Code install page](https://code.visualstudio.com/download) and select the 32 or 64 bit installer. Install Visual Studio Code on Windows (not in your WSL file system).
+
+* When prompted to **Select Additional Tasks** during installation, be sure to check the **Add to PATH** option so you can easily open a folder in WSL using the code command.
+
+* Install the [Remote Development extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack). This extension pack includes the Remote - WSL extension, in addition to the Remote - SSH, and Remote - Containers extensions, enabling you to open any folder in a container, on a remote machine, or in WSL.
+
+> [!IMPORTANT]
+> In order to install the Remote-WSL extension, you will need the [1.35 May release](https://code.visualstudio.com/updates/v1_35) version or later of VS Code. We do not recommend using WSL in VS Code without the Remote-WSL extension as you will lose support for auto-complete, debugging, linting, etc. Fun fact: this WSL extension is installed in $HOME/.vscode-server/extensions.
+
+## Update your Linux distribution
+
+Some WSL Linux distributions are lacking libraries that are required by the VS Code server to start up. You can add additional libraries into your Linux distribution by using its package manager.
+
+For example, to update Debian or Ubuntu, use:
+
+```bash
+sudo apt-get update
+```
+
+To add wget (to retrieve content from web servers) and ca-certificates (to allow SSL-based applications to check for the authenticity of SSL connections), enter:
+
+```bash
+sudo apt-get install wget ca-certificates
+```
+
+## Open a WSL project in Visual Studio Code
+
+### From the command-line
+
+To open a project from your WSL distribution, open the distribution's command line and enter: `code .`
+
+![Open WSL project with VS Code remote server](../media/wsl-open-vs-code.gif)
+
+### From VS Code
+
+You can also access more VS Code Remote options by using the shortcut: `CTRL+SHIFT+P` in VS Code to bring up the command palette. If you then type `VSCODE-REMOTE` you will see all of the VS Code Remote options available, allowing you to reopen the folder in a remote session, specify which distribution you want to open in, and more.
+
+![VS Code's command palette](../media/vscode-remote-command-palette.png)
+
+## Extensions inside of VS Code Remote
+
+The Remote-WSL extension splits VS Code into a “client-server” architecture, with the client (the user interface) running on your Windows machine and the server (your code, Git, plugins, etc) running remotely.
+
+When running VS Code Remote, selecting the 'Extensions' tab will display a list of extensions split between your local machine and your WSL distribution.
+
+Installing a local extension, like a [theme](https://marketplace.visualstudio.com/search?target=VSCode&category=Themes&sortBy=Installs),  only needs to be installed once.
+
+Some extensions, like the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) or anything that handles things like linting or debugging, must be installed separately on each remote WSL distributions. VS Code will display a warning icon ⚠, along with a green "Install in WSL" button, if you have an extension locally installed that is not installed on your WSL Remote.
+
+![VS Code with Remote - WSL extensions vs local extensions](../media/vscode-remote-wsl-extensions.png)
+
+For further information, see the VS Code docs:
+
+* When VS Code Remote is started in WSL, no shell startup scripts are run. See this [advanced environment setup script article](https://code.visualstudio.com/docs/remote/wsl#_advanced-environment-setup-script) for more info on how to run additional commands or modify the environment.
+
+* Having problems launching VS Code from your WSL command line? This [troubleshooting guide](https://code.visualstudio.com/docs/remote/troubleshooting#_fixing-problems-with-the-code-command-not-working) includes tips on changing path variables, resolving extension errors about missing dependencies, resolving Git line ending issues, installing a local VSIX on a remote machine, launching a browser window, blocker localhost port, web sockets not working, errors storing extension data, and more.
+
+## Install Git (optional)
+
+If you plan to collaborate with others, or host your project on an open-source site (like GitHub), VS Code supports [version control with Git](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support). The Source Control tab in VS Code tracks all of your changes and has common Git commands (add, commit, push, pull) built right into the UI.
+
+To install Git, see [set up Git to work with Windows Subsystem for Linux](./wsl-git.md).
+
+## Install Windows Terminal (optional)
+
+The new Windows Terminal enables multiple tabs (quickly switch between Command Prompt, PowerShell, or multiple Linux distributions), custom key bindings (create your own shortcut keys for opening or closing tabs, copy+paste, etc.), emojis ☺, and custom themes (color schemes, font styles and sizes, background image/blur/transparency). Learn more in the [Windows Terminal docs](https://docs.microsoft.com/windows/terminal).
+
+1. Get [Windows Terminal in the Microsoft Store](https://www.microsoft.com/store/apps/9n0dx20hk701): By installing via the store, updates are handled automatically.
+
+2. Once installed, open Windows Terminal and select **Settings** to customize your terminal using the `profile.json` file.
+
+## Additional Resources
+
+* [VS Code Remote Development](https://code.visualstudio.com/docs/remote/remote-overview)
+* [Remote development tips and tricks](https://code.visualstudio.com/docs/remote/troubleshooting)
+* [Remote development with WSL tutorial](https://code.visualstudio.com/remote-tutorials/wsl/getting-started)
+* [Using Docker with WSL 2 and VS Code](https://code.visualstudio.com/blogs/2020/03/02/docker-in-wsl2)
+* [Using C++ and WSL in VS Code](https://code.visualstudio.com/docs/cpp/config-wsl)
+* [Remote R Service for Linux](https://docs.microsoft.com/visualstudio/rtvs/setting-up-remote-r-service-on-linux?view=vs-2017)
+
+A few additional extensions you may want to consider include:
+
+* [Keymaps from other editors](https://marketplace.visualstudio.com/search?target=VSCode&category=Keymaps&sortBy=Downloads): These extensions can help your environment feel right at home if you're transitioning from another text editor (like Atom, Sublime, Vim, eMacs, Notepad++, etc).
+* [Settings Sync](https://marketplace.visualstudio.com/items?itemName=Shan.code-settings-sync): Enables you to synchronize your VS Code settings across different installations using GitHub. If you work on different machines, this helps keep your environment consistent across them.
+* [Debugger for Chrome](https://code.visualstudio.com/blogs/2016/02/23/introducing-chrome-debugger-for-vs-code): Once you finish developing on the server side with Linux, you'll need to develop and test the client side. This extension integrates your VS Code editor with your Chrome browser debugging service, making things a bit more efficient.