Share via

Forks

  • Article

TFS 2018

Visual Studio 2019 | Visual Studio 2022

Git repo forks are useful when people want to make experimental, risky, or confidential changes to a codebase, but those changes need to be isolated from the codebase in the original repo. A new fork is basically a clone of the original repo pushed to a new remote repo. The fork is independent of the original repo, and is a complete copy unless you specify a single branch.

As an independent copy, changes you make to your fork, such as adding commits or branches, aren't shared with 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

  • To view code, you must be a member of an Azure DevOps project with Basic access or higher. If you aren't a project member, get added.

  • To clone or contribute to code, you must be a member of the Contributors security group or have the corresponding permissions.

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.

    Screenshot of the Fork menu item in the More actions menu on the Repo Files page in Azure Repos.

  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.

    Screenshot of the Fork dialog on the Repo Files page in Azure Repos.

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.

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.

    Screenshot of the Add button in the Remotes pane of the Git Repository Settings submenu of the Source Control menu in Visual Studio 2019.

  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.

    Screenshot of the Add Remote dialog box in Visual Studio 2019.

Push local changes to your fork

When you fork, you create a personal and independent copy of the remote repo. 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.

    Screenshot of the PR source and target branch options 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 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