Local repository setup

Important

If you're making only minor changes to an article, you do not need to complete the steps in this article. You 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, where you will have read/write permissions to store your proposed changes.

Overview

After you know which repository you want to contribute to, you will first create a fork of the repository. After forking, you will create a clone/copy of it on your computer, and then configure your Git Bash credentials. These are all typically one-time setup activities.

If you're new to GitHub, watch the following video for a conceptual overview of the forking and cloning process:

1. Create a GitHub fork of the main repository

All main Docs repositories provide read-only access, which means you cannot make changes directly on content in the repositories. To make changes, you must submit a pull request to the repository. To facilitate this process, you first need your own copy of the repository, in which you will have write access. A GitHub fork serves that purpose. You create it only one time.

  1. Go to the main repository's GitHub page and click the Fork button on the upper right.
  2. If you're prompted, select your GitHub account as the destination where the fork should be created. This creates a copy of the repository within your GitHub account.

GitHub profile example

2. Create a clone of your forked repository

You will use the clone command to pull a copy of a repository (your fork) down to your device. Here are some helpful tips and info to review before you start the cloning operation:

  • The clone command performs several actions, including creating a directory in your local file system to store the repository, initializing the repository, and copying the GitHub repository down to the new directory. The default repository location that Git Bash uses is typically c:\users\<Windows-user-account>\<repo>. The clone command also sets up a read/write connection back to your fork called a remote, which defaults to the name "origin."
  • Cloning is a one-time-per-computer operation. If you get a new computer or you need to contribute from multiple computers, you’ll need to clone your fork to those too.
  • As with many Git commands, cloning requires GitHub credentials in order to read/write from/to a remote repository. You can provide credentials one time by using Git Credential Manager, or you can supply a GitHub personal access token each time you clone.

Choose one of the following options to specify the credentials during the cloning operation, to be used whenever Git Bash needs to authenticate with GitHub.

Note

If you installed the latest version of Git for Windows and accepted the default installation, Git Credential Manager is enabled by default. Git Credential Manager makes authentication much easier, because you don't need to recall your personal access token when re-establishing authenticated connections and remotes with GitHub.

Clone option 1: Authenticate by using Git Credential Manager

  1. Start Git Bash.
  2. At the command prompt, enter the following command, which will create a directory on your computer by using the name as specified in <repo>.

    Tip

    You can get your fork's GitHub URL for the clone command from the Clone or download button in the GitHub UI:

    Clone or download

    Be sure to specify the path to your fork during the cloning process, not the main repository from which you created the fork. Otherwise, you won’t be able to contribute changes. The main repository is referenced with an organization name such as Azure, Microsoft, or MicrosoftDocs: github.com/MicrosoftDocs/<repo>. Your fork is referenced through your personal GitHub user account: github.com/<GitHub-username>/<repo>.

    git clone https://github.com/<GitHub-username>/<repo>.git
    

    For example, your clone command looks similar to this:

    git clone https://github.com/smithj/IntuneDocs-pr.git  
    
  3. When you're prompted, enter your GitHub credentials.

    GitHub Login

  4. When you're prompted, enter your two-factor authentication code.

    GitHub two-factor authentication

    Note

    Your credentials will be saved and used to authenticate future GitHub requests. You should need to do this only once per computer.

Now skip ahead to the Set remote for upstream repository section.

Clone option 2: Authenticate by using a GitHub personal access token

  1. Copy the personal access token that you got from the Personal access tokens page on GitHub. You likely saved your personal access token when you set up your GitHub account.
  2. Start Git Bash.
  3. At the command prompt, enter the following command, which will create a directory on your computer by using the name as specified in <repo>.

    git clone https://<GitHub-username>:<token>@github.com/<GitHub-username>/<repo>.git
    

    For example, your clone command looks similar to this:

    git clone https://smithj:b428654321d613773d423ef2f173ddf4a312345@github.com/smithj/IntuneDocs-pr.git  
    

Note

Because the clone command also configures the remote for "origin," your access token will be saved as part of the remote.

If you're using the default location, your local copy of the repository will be stored in c:\users\<Windows-user-account>\<repo>.

3. Set the remote for the upstream repository

Just as the cloning procedure automatically created a read/write remote connection to your fork named "origin," you need to set up a read-only remote connection to the main repository named "upstream." You'll use this connection to keep your local repository in sync with the latest changes made by others. You use the git remote command to do this. You use the fetch command to get the branch info from the upstream repository, for later use.

If you're using Git Credential Manager, use the following commands:

        cd <repo>
        git remote add upstream https://github.com/<organization>/<repo>.git
        git fetch upstream

If you're using a GitHub personal access token, use the following commands:

        cd <repo>
        git remote add upstream https://<GitHub-username>:<token>@github.com/<organization>/<repo>.git
        git fetch upstream

Next steps

  • Continue to the GitHub contribution workflow article to learn more about adding and updating content.
  • If you didn't already, please review the "Overview" articles at the beginning of this guide.