Edit

Get started using Git on Windows Subsystem for Linux

  • Article

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.04), as well as Debian. If I open those distributions, select the home 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.04 \\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

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. You also will need to set up your git config file.

To install Git, see the Git Download for Linux site. Each Linux distribution has their own package manager and install command.

For the latest stable Git version in Ubuntu/Debian, enter the command:

sudo apt-get install git

Note

You also may want to install Git for Windows 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 set your name with this command (replacing "Your Name" with your preferred username):

git config --global user.name "Your Name"

Set your email with this command (replacing "youremail@domain.com" with the email you prefer):

git config --global user.email "youremail@domain.com"

Tip

If you don't yet have a GitHub account, you can sign-up for one on GitHub. If you've never worked with Git before, GitHub Guides 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).

Git Credential Manager setup

Git Credential Manager (GCM) is a secure Git credential helper built on .NET that can be used with both WSL1 and WSL2. It enables multi-factor authentication support for GitHub repos, Azure DevOps, Azure DevOps Server, and Bitbucket.

GCM 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. 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.

In order to use GCM with WSL you must be on Windows 10 Version 1903 or later. This is the first version of Windows that includes the required wsl.exe tool that GCM uses to interoperate with Git in your WSL distributions.

It is recommended to install the latest Git for Windows in order to share credentials & settings between WSL and the Windows host. Git Credential Manager is included with Git for Windows and the latest version is included in each new Git for Windows release. During the installation, you will be asked to select a credential helper, with GCM set as the default.

If you have a reason not to install Git for Windows, you can install GCM as a Linux application directly in your WSL distribution, but note that doing so means GCM is running as a Linux application and cannot utilize the authentication or credential storage features of the host Windows operating system. See the GCM repo for instructions on how to configure WSL without Git for Windows.

To set up GCM for use with a WSL distribution, open your distribution and enter this command:

If GIT installed is >= v2.39.0

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

else if GIT installed is >= v2.36.1

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe"

else if version is < v2.36.1 enter this command:

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager-core.exe"

Note

Using GCM as a credential helper for a WSL Git installation means that any configuration set in WSL Git is NOT respected by GCM (by default). This is because GCM is running as a Windows application, and therefore will use the Git for Windows installation to query configuration. This means things like proxy settings for GCM need to be set in Git for Windows as well as WSL Git as they are stored in different files (%USERPROFILE%\.gitconfig vs \\wsl$\distro\home\$USER\.gitconfig). You can configure WSL so that GCM will use the WSL Git configuration, but this means that proxy settings will be unique to the specific WSL installation and not shared with others or the Windows host.

Git with SSH

Git Credential Manager only works with HTTP(S) remotes. You can still use Git with SSH:

Additional configuration for Azure

If you intend to work with Azure Repos or Azure DevOps, some additional configuration is required:

git config --global credential.https://dev.azure.com.useHttpPath true

Now any git operation you perform within your WSL distribution will use GCM. 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.

Tip

If you are using a GPG key for code signing security, you may need to associate your GPG key with your GitHub email.

Adding a Git Ignore file

We recommend adding a .gitignore file to your projects. GitHub offers a collection of useful .gitignore templates with recommended .gitignore file setups organized according to your use-case. For example, here is GitHub's default gitignore template for a Node.js project.

If you choose to create a new repo using the GitHub website, 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.

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.

Additional resources