Forks

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Visual Studio 2019 | Visual Studio 2022

Git repo forks are useful when people want to make experimental, risky, or concealed changes to a codebase, but those changes need to be isolated from the codebase in the original repo. A new fork is basically a new remote repo that shares the source code of the original repo.

As an independent version, changes you make to your fork, such as adding commits or branches, are hidden from the original repo. If you want to merge your codebase changes into the original repo, you must create a pull request (PR) to request review and approval of those changes.

The forking process doesn't transfer any permissions, policies, or build pipelines from the original repo to your fork.

This article addresses working with forks in Azure Repos Git repositories, and provides links to GitHub content that discusses how to manage Forks in GitHub repos.

In this article you learn how to:

• Share code between forks
• Choose between branches and forks
• Enable repo forks
• Create a fork
• Clone your fork locally
• Push local changes to your fork
• Create and complete a PR
• Sync your fork

Prerequisites for access to Azure Repos

• Repos must be enabled in your Azure DevOps project settings. If the Repos hub and associated pages don't display, see Turn an Azure DevOps service on or off to reenable Repos.

• To view code in private projects, you must be a member of an Azure DevOps project with Basic access level or higher. For public projects, everyone can view the code.

  • If you don't have a project, create one or sign up for free.

  • If you aren't a project member, get added.

• To clone or contribute to code for a private project, you must be a member of the Contributors security group or have the corresponding permissions set. For public projects, anyone can clone and contribute code. For more information, see What is a public project?

  Note

  For public projects, users granted Stakeholder access have full access to Azure Repos.

Share code between forks

The original repo is often referred to as the upstream repo. You can create PRs to merge changes in either direction: from fork to upstream, or upstream to fork. The most common direction is from fork to upstream. The destination repo's permissions, policies, builds, and work items will apply to the PR.

Choose between branches and forks

For a small team of 2-5 developers, a forking workflow might not be necessary because everyone can work in feature branches and branch policies can protect the default branch. However, if your team expands and outgrows this arrangement they can switch to a forking workflow.

If your repo has a large number of casual or infrequent committers, such as an open source project might, we recommend the forking workflow. Typically, only core contributors to your project should have direct commit rights to your original repo. Other collaborators should use a forking workflow to isolate their proposed changes until the core contributors have a chance to review their work.

Enable repo forks

To enable forks for an Azure Repos Git repo, see enable Forks.

To enable forks for a GitHub repo, see Managing the forking policy for your organization.

The forking workflow

The forking workflow consists of five steps that are described in the following sections.

1. Create a fork
2. Clone your fork locally
3. Push local changes to your fork
4. Create and complete a PR
5. Sync your fork

Create a fork

The following steps describe how to fork an Azure Repos Git repo.

Note

To fork a repo in an Azure DevOps project, you must have the Create Repository permission for that project. Repo owners should consider creating a dedicated project for forks and assigning the Create Repository permission to all contributors. For more information about setting permissions, see Set Git repository permissions.

1. From your web browser, navigate to the Azure Repos Git repo that you want to fork. Select Repo > Files and then choose Fork from the ellipsis menu to open the Fork dialog.

   

2. In the Fork dialog, name the forked repo, choose the project where you want the fork to be created, select the branches to include in the fork, and then choose Fork. You can specify whether the fork will contain all branches or just the default branch. If the repo contains several topic branches, then consider only including the default branch in your fork.

   

For information about how to fork a GitHub repo, see Fork a repo.

Clone your fork locally

After you've forked a repo, clone your fork to create a local copy in a folder on your computer. You can clone from the command line or by using an IDE like Visual Studio. For more information about cloning a repo, see Clone an existing Git repo.

When you clone a remote repo, Git assigns the alias origin as shorthand for the URL of the remote repo you cloned. For convenience, add another alias named upstream for the repo you forked from, which is referred to as the upstream repo. The following steps describe how to add an upstream alias.

Tip

For convenience, you can use the origin and upstream aliases instead of their corresponding URLs in your Git commands.

Visual Studio

To add an upstream alias in Visual Studio, follow these steps:

1. Choose Tools > Options from the menu bar to open the Options window. Select Source Control > Git Repository Settings > Remotes, and then choose Add to open the Add Remote dialog.

   

2. In the Add Remote dialog, add a new remote called upstream and enter the Git clone URL of the repo you forked. Then, choose Save.

   

Command Line

On the command line, navigate to the root folder of your local repo, and then run the following command to add a new remote named upstream. Replace <clone URL> with the Git clone URL of the repo you forked.

git remote add upstream <clone URL>

For example, git remote add upstream https://fiber-teams@dev.azure.com/fiber-teams/FiberTests/_git/FiberTests adds an upstream alias.

To edit an existing upstream alias, run the following command:

git remote set-url upstream <clone URL>

Push local changes to your fork

When you fork, you create a personal version of the original repository (original repository is referred as "upstream"). Fork is independent from the upstream, but fork shares the code and retains a link to the upstream, allowing for future synchronization. So, there's nothing to prevent you from working directly in the main branch of the local clone and then pushing that work to the main branch of your fork. However, it's generally better to use feature branches for your work. By using feature branches:

• You can maintain multiple, independent workstreams simultaneously.

• You make it easier for others to understand the work you share because that work is organized into distinct workstreams by branch.

A typical Git workflow includes these steps:

1. Create a local feature or bug fix branch.

2. Make changes in the new branch and commit your work. Typically, people make multiple commits when working on a feature or bug fix.

3. Push the feature or bug fix branch to your fork. Your fork has the alias origin.

For information on how to push your changes, see Share code with push.

Create and complete a PR

In Azure Repos, to merge into the original repo the changes that you pushed to your fork, you can:

1. Create a PR to request review and approval of your changes. When you open a PR, set the PR source branch to the feature or bugfix branch in your fork. The PR target branch is typically the main branch of the repo you forked. That repo is referred to as the upstream repo and has the alias upstream.

   The following screenshot shows the source repo and branch and the target repo and branch of a PR created in Azure Repos.

   

   For more information about how to create a PR using your browser, Visual Studio, or the Azure DevOps CLI, see Create a PR.

   Important

   Anyone in Project Valid Users and with the Read permission on the upstream repo can open a PR to it. If the upstream repo has a PR build pipeline that's configured to run on PR creation, a build will run on the changes introduced by your PR.

2. For your PR to complete, all required reviewers must approve the PR changes and all target branch policies must be met. On PR approval and completion, the changes in the PR source branch will merge into the PR target branch.

For information about how to create and complete a GitHub PR, see Creating a pull request and Merging a pull request.

Sync your fork

After a PR merges the changes from your fork into the target branch of the upstream repo, you can pull from the target branch of the upstream repo to update your corresponding local branch with both your changes and any changes made by other contributors. Then you're ready to:

• Create a new feature or bug fix branch from the updated local branch.

• Update your fork by pushing from your updated local branch to origin.

Typically, the target branch of the upstream repo is main. If you aren't directly editing your local main branch (you work in feature branches), then pulling from the upstream branch upstream/main will update your local main branch without merge conflicts.

Next steps

Share code with push Review pull requests

Related articles

• New to Git repos? Learn more
• Update code with fetch, merge, and pull
• Save your work with commits