Install content authoring tools

This article describes the steps to interactively install Git client tools and Visual Studio Code.

If you prefer to install the client tools for Mac using Homebrew, or Windows PowerShell, see additional tool installation options.

Important

If you're making only minor changes to an article, you do not need to complete the steps in this article and can continue directly to the minor/infrequent changes workflow.

Major contributors and Microsoft employees are encouraged to complete these steps, which enable you to use the major/long-running changes workflow. Even if you have write permissions in the main repository, we highly recommend (and this guide assumes) that you fork and clone the repository, so that you have read/write permissions to store your proposed changes in your fork.

Install Git client tools on Windows

Install the latest version of Software Freedom Conservancy's Git client tools. The install includes the Git version control system and Git Bash, the command-line app that you use to interact with your local Git repository.

Note

If you prefer a graphical user interface (GUI) over a command-line interface (CLI), see Software Freedom Conservancy's available GUI Clients page, GitHub's GitHub Desktop, or Visual Studio Code for some popular options.

  1. Download Git for Windows.

  2. You can accept all default settings, unless you want different behavior.

    Git Setup page for selecting components

    Git Setup page for selecting text editor

    Git Setup page for adjusting PATH variable

    Git Setup page for HTTPS transport

    Git Setup page for line ending conversions

    Git Setup page for terminal emulator

    Git Setup page for extra options

    Git Setup page for completing setup

  3. If Git Bash is not already running, in the Windows start menu, locate Git Bash, and launch the application.

    Launch git bash

  4. Configure your user.name and user.email in Git Bash

    This step is a one-time setup, only needed once per machine, even if you use multiple repositories. This step is to make sure that you are listed correctly as a contributor.

    Configure the two properties user.name and user.email. The user.name value needs to match the username handle that you set up in your GitHub profile. The user.email value needs to match your email address.

    git config --global user.name "johndoe"
    git config --global user.email "email@domain.com"
    
  5. List and review your local settings to ensure the user.name and user.email values are correct.

    git config --list
    
  6. In the next article, you will Set up a local Git repository.

    Additional Git resources are available here: Git terminology | Git basics | Learning Git and GitHub

Understand Markdown editors

Markdown is a lightweight markup language that is both easy to read and easy to learn. Therefore, it has rapidly become an industry standard. To write articles in Markdown, we recommend that you first download and install a Markdown editor. Visual Studio Code is the preferred tool for editing Markdown at Microsoft. Atom is another popular tool for editing Markdown.

Markdown text is saved into files with .md extension.

Additional details on how to write with Markdown, including Markdown basics and the features supported by OPS custom Markdown extensions, are covered later in the How to use Markdown article.

Visual Studio Code

Visual Studio Code, also known as VS Code, is a lightweight editor that works on Windows, Linux, and Mac. It includes git integration, and support for extensions.

  1. Download and install VS Code.

  2. Launch Visual Studio Code

    Launch Visual Studio Code

    Tip

    To launch VS Code and open the current folder, run the command code . in the command line or bash shell. If the current folder is part of a local git repo, the github integration appears in Visual Studio Code automatically.

Next steps

Now you are ready to Set up a local Git repository.

For Mac Homebrew and PowerShell command-line options for these tools, see additional tool installation options.