Set up Git repository locally for documentation
This article describes the steps to set up a git repository on your local machine, with the intent to contribute to Microsoft documentation. Contributors may use a locally cloned repository to add new articles, do major edits on existing articles, or change artwork.
You run these one-time setup activities to start contributing:
- Determine the appropriate repository
- Fork the repository to your GitHub account
- Choose a local folder for the cloned files
- Clone the repository to your local machine
- Configure the upstream remote value
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 quick changes workflow.
To contribute to Microsoft's documentation site, you can make and edit Markdown files locally by cloning the corresponding documentation repository. Microsoft requires you to fork the appropriate repository into your own GitHub account so that you have read/write permissions there to store your proposed changes. Then you use pull requests to merge changes into the read-only central shared repository.
If you're new to GitHub, watch the following video for a conceptual overview of the forking and cloning process:
Determine the repository
If you are unsure of which repository to use, then visit the article on docs.microsoft.com using your web browser. Select the Edit link (pencil icon) on the upper right of the article.
That link takes you to github.com location for the corresponding Markdown file in the appropriate repository. Note the URL to view the repository name.
For example, these popular repositories are available for public contributions:
- Azure documentation https://github.com/MicrosoftDocs/azure-docs
- SQL Server documentation https://github.com/MicrosoftDocs/sql-docs
- Visual Studio documentation https://github.com/MicrosoftDocs/visualstudio-docs
- .NET Documentation https://github.com/dotnet/docs
- Azure .Net SDK documentation https://github.com/azure/azure-docs-sdk-dotnet
- ConfigMgr documentation https://github.com/MicrosoftDocs/SCCMdocs
Fork the repository
Using the appropriate repository, create a fork of the repository into your own GitHub account by using the GitHub website.
A personal fork is required since all main documentation repositories provide read-only access. To make changes, you must submit a pull request from your fork into the main repository. To facilitate this process, you first need your own copy of the repository, in which you have write access. A GitHub fork serves that purpose.
Go to the main repository's GitHub page and click the Fork button on the upper right.
If you are prompted, select your GitHub account tile as the destination where the fork should be created. This prompt creates a copy of the repository within your GitHub account, known as a fork.
Choose a local folder
Make a local folder to hold a copy of the repository locally. Some of the repositories can be large; up to 5 GB for azure-docs for example. Choose a location with available disk space.
Choose a folder name should be easy for you to remember and type. For example, consider a root folder
C:\docs\or make a folder in your user profile directory
Avoid choosing a local folder path that is nested inside of another git repository folder location. While it is acceptable to store the git cloned folders adjacent to each other, nesting git folders inside one another causes errors for the file tracking.
Launch Git Bash
The default location that Git Bash starts in is typically the home directory (~) or
/c/users/<Windows-user-account>/on Windows OS.
To determine the current directory, type
pwdat the $ prompt.
Change directory (cd) into the folder that you created for hosting the repository locally. Note that Git Bash uses the Linux convention of forward-slashes instead of back-slashes for folder paths.
Create a local clone
Using Git Bash, prepare to run the clone command to pull a copy of a repository (your fork) down to your device on the current directory.
Authenticate by using Git Credential Manager
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.
Run the clone command, by providing the repository name. Cloning downloads (clone) the forked repository on your local computer.
You can get your fork's GitHub URL for the clone command from the Clone or download button in the GitHub UI:
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 cannot contribute changes. Your fork is referenced through your personal GitHub user account, such as
git clone https://github.com/<github-username>/<repo>.git
Your clone command should look similar to this example:
git clone https://github.com/smithj/azure-docs.git
When you're prompted, enter your GitHub credentials.
When you're prompted, enter your two-factor authentication code.
Your credentials will be saved and used to authenticate future GitHub requests. You only need to do this authentication once per computer.
The clone command runs and downloads a copy of the repository files from your fork into a new folder on the local disk. A new folder is made within the current folder. It may take a few minutes, depending on the repository size. You can explore the folder to see the structure once it is finished.
Configure remote upstream
After cloning the repository, set up a read-only remote connection to the main repository named upstream. You use the upstream URL to keep your local repository in sync with the latest changes made by others. The git remote command is used to set the configuration value. You use the fetch command to refresh the branch info from the upstream repository.
If you're using Git Credential Manager, use the following commands. Replace the <repo> and <organization> placeholders.
cd <repo> git remote add upstream https://github.com/<organization>/<repo>.git git fetch upstream
View the configured values and confirm the URLs are correct. Ensure the origin URLs point to your personal fork. Ensure the upstream URLs point to the main repository, such as MicrosoftDocs or Azure.
git remote -v
Example remote output is shown. A fictitious git account named MyGitAccount is configured with a personal access token to access the repo azure-docs:
origin https://github.com/MyGitAccount/azure-docs.git (fetch) origin https://github.com/MyGitAccount/azure-docs.git(push) upstream https://github.com/MicrosoftDocs/azure-docs.git (fetch) upstream https://github.com/MicrosoftDocs/azure-docs.git (push)
If you made a mistake, you can remove the remote value. To remove the upstream value, run the command
git remote remove upstream.
- To learn more about adding and updating content, continue to the GitHub contribution workflow.