Local repository setup

Important

If you are making only minor changes to an article, you DO NOT need to complete this step and can continue directly to the minor/infrequent changes workflow.

Major contributors and Microsoft employees are encouraged to complete this step, which enables you to use the major/long-running changes workflow. Even if you have write permissions in the main repository, it is highly recommended (and this guide assumes) that you will fork and clone the repository, where you will have read/write permissions to store your proposed changes.

Overview

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

If you're new to GitHub, watch the video below 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. In order to make changes, you must submit a pull request to the repository. To facilitate this process, you first need your own personal copy of the repository, in which you will have write access. A GitHub "fork" serves that purpose, and only needs to be created one time.

  1. Navigate to the main repository's GitHub page and click the Fork button in the upper right.
  2. If 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 clone 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 used by Git Bash is typically c:\users\<your Windows user account>\<repository-name>. Clone 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 PC or need to contribute from multiple PCs, you’ll need to clone your fork to that computer as well.
  • 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 using Git Credential Manager, or you can supply a GitHub personal access token each time you clone.

Choose one option below to specify the credentials during the "clone" 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 authenticaton much easier, as you don't need to recall your Personal Access Token when re-establishing authenticated connections/remotes with GitHub.

Clone option 1: Authenticate using the Git Credential Manager

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

    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 clone, 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-name. Your fork is referenced using your personal GitHub user account: github.com/GitHubUsername/repo-name

    git clone https://github.com/<your-GitHub-user-account>/<repo-name>-pr.git
    

    For example, your clone command could look similar to this:

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

    GitHub Login

  4. When 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 only need to do this once per computer.

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

Clone option 2: Authenticate using a GitHub Personal Access Token

  1. Copy the Personal Access Token that you got from https://github.com/settings/tokens. 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 using the same as specified in <repo-name>.

    git clone https://[your GitHub user name]:[token]@github.com/<your GitHub user name>/<repo-name>-pr.git
    

    For example, you clone command could look similar to this:

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

Note: Since 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\<your Windows user account>\<repository-name>(-pr).

3. Set remote for upstream repository

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

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

        cd <repo-name>
        git remote add upstream https://github.com/<github-org-name>/<repo-name>.git
        git fetch upstream

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

        cd <repo-name>
        git remote add upstream https://[your GitHub user name]:[token]@github.com/<github-org-name>/<repo-name>.git
        git fetch upstream

Next steps

  • Continue to the GitHub contribution workflows page to learn more about adding and updating content.
  • If you didn't already, please review the items in the previous "Overview" topics at the beginnig of this section.