Merge branch 'bl-create-update-a-fork-page' into 'master'

Create update a fork page

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/170389



Merged-by: Fiona Neill <fneill@gitlab.com>
Approved-by: Fiona Neill <fneill@gitlab.com>
Reviewed-by: Fiona Neill <fneill@gitlab.com>
Co-authored-by: Brendan Lynch <blynch@gitlab.com>

doc/topics/git/forks.md

+---
+stage: Create
+group: Source Code
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+description: "Fork a Git repository when you want to contribute changes back to an upstream repository you don't have permission to contribute to directly."
+---
+
+# Update a fork
+
+DETAILS:
+**Tier:** Free, Premium, Ultimate
+**Offering:** GitLab.com, Self-managed, GitLab Dedicated
+
+A fork is a personal copy of the repository and all its branches, which you create
+in a namespace of your choice. You can use forks to propose changes to another project
+that you don't have access to. For more information,
+see [Forking workflows](../../user/project/repository/forking_workflow.md).
+
+This page describes how to update a fork using Git commands from your command line and
+how to [collaborate across forks](#collaborate-across-forks).
+
+You can also update a fork with the [GitLab UI](../../user/project/repository/forking_workflow.md#from-the-ui).
+
+Prerequisites:
+
+- You must [download and install the Git client](how_to_install_git/index.md) on your local machine.
+- You must [create a fork](../../user/project/repository/forking_workflow.md#create-a-fork) of the
+  repository you want to update.
+
+To update your fork from the command line:
+
+1. Check if an `upstream` remote repository is configured for your fork:
+
+   1. Clone your fork locally, if you haven't already. For more information, see [Clone a repository](clone.md).
+   1. View the configured remotes for your fork:
+
+      ```shell
+      git remote -v
+      ```
+
+   1. If your fork doesn't have a remote pointing to the original repository, use one of these examples
+      to configure a remote called upstream:
+
+       ```shell
+       # Set any repository as your upstream after editing <upstream_url>
+       git remote add upstream <upstream_url>
+
+       # Set the main GitLab repository as your upstream
+       git remote add upstream https://gitlab.com/gitlab-org/gitlab.git
+       ```
+
+1. Update your fork:
+
+   1. In your local copy, check out the [default branch](../../user/project/repository/branches/default.md).
+      Replace `main` with the name of your default branch:
+
+      ```shell
+      git checkout main
+      ```
+
+      NOTE:
+      If Git identifies unstaged changes, [commit or stash](commit.md) them before continuing.
+
+   1. Fetch the changes from the upstream repository:
+
+      ```shell
+      git fetch upstream
+      ```
+
+   1. Pull the changes into your fork. Replace `main` with the name of the branch you're updating:
+
+      ```shell
+      git pull upstream main
+      ```
+
+   1. Push the changes to your fork repository on the server:
+
+      ```shell
+      git push origin main
+      ```
+
+## Collaborate across forks
+
+GitLab enables collaboration between the upstream project maintainers and the fork owners.
+For more information, see:
+
+- [Collaborate on merge requests across forks](../../user/project/merge_requests/allow_collaboration.md)
+  - [Allow commits from upstream members](../../user/project/merge_requests/allow_collaboration.md#allow-commits-from-upstream-members)
+  - [Prevent commits from upstream members](../../user/project/merge_requests/allow_collaboration.md#prevent-commits-from-upstream-members)
+
+### Push to a fork as an upstream member
+
+You can push directly to the branch of the forked repository if:
+
+- The author of the merge request enabled contributions from upstream members.
+- You have at least the Developer role for the upstream project.
+
+In the following example:
+
+- The forked repository URL is `git@gitlab.com:contributor/forked-project.git`.
+- The branch of the merge request is `fork-branch`.
+
+To change or add a commit to the contributor's merge request:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Go to **Code** > **Merge requests** and find the merge request.
+1. In the upper-right corner, select **Code**, then select **Check out branch**.
+1. On the dialog, select **Copy** (**{copy-to-clipboard}**).
+1. In your terminal, go to the cloned version of the repository, and paste the commands. For example:
+
+   ```shell
+   git fetch "git@gitlab.com:contributor/forked-project.git" 'fork-branch'
+   git checkout -b 'contributor/fork-branch' FETCH_HEAD
+   ```
+
+   These commands fetch the branch from the forked project and create a local branch for you to work on.
+
+1. Make your changes to the local copy of the branch, and then commit them.
+1. Push your local changes to the forked project. The following command pushes the
+   local branch `contributor/fork-branch` to the `fork-branch` branch of
+   the `git@gitlab.com:contributor/forked-project.git` repository:
+
+   ```shell
+   git push git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch
+   ```
+
+   If you've amended or squashed any commits, you must use `git push --force`. Proceed with caution as this command rewrites the commit history.
+
+   ```shell
+   git push --force git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch
+   ```
+
+   The colon (`:`) specifies the source branch and the destination branch. The scheme is:
+
+   ```shell
+   git push <forked_repository_git_url> <local_branch>:<fork_branch>
+   ```
+
+## Related topics
+
+- [Forking workflows](../../user/project/repository/forking_workflow.md)
+  - [Create a fork](../../user/project/repository/forking_workflow.md#create-a-fork)
+  - [Unlink a fork](../../user/project/repository/forking_workflow.md#unlink-a-fork)
+- [Collaborate on merge requests across forks](../../user/project/merge_requests/allow_collaboration.md)
+- [Merge requests](../../user/project/merge_requests/index.md)

doc/user/project/merge_requests/allow_collaboration.md

@@ -52,54 +52,11 @@ upstream members of the project you're contributing to:
 
 You can push directly to the branch of the forked repository if:
 
-- The author of the merge request has enabled contributions from upstream
-  members.
-- You have at least the Developer role for the
-  upstream project.
+- The author of the merge request enabled contributions from upstream members.
+- You have at least the Developer role for the upstream project.
 
-In the following example:
-
-- The forked repository URL is `git@gitlab.com:contributor/forked-project.git`.
-- The branch of the merge request is `fork-branch`.
-
-To change or add a commit to the contributor's merge request:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Code > Merge requests** and find the merge request.
-1. In the upper-right corner, select **Code**, then select **Check out branch**.
-1. On the dialog, select **Copy** (**{copy-to-clipboard}**).
-1. In your terminal, go to your cloned version of the repository, and
-   paste the commands. For example:
-
-   ```shell
-   git fetch "git@gitlab.com:contributor/forked-project.git" 'fork-branch'
-   git checkout -b 'contributor/fork-branch' FETCH_HEAD
-   ```
-
-   Those commands fetch the branch from the forked project, and create a local branch
-   for you to work on.
-
-1. Make your changes to your local copy of the branch, and then commit them.
-1. Push your local changes to the forked project. The following command pushes
-   the local branch `contributor/fork-branch` to the `fork-branch` branch of
-   the `git@gitlab.com:contributor/forked-project.git` repository:
-
-   ```shell
-   git push git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch
-   ```
-
-   If you have amended or squashed any commits, you must force push. Proceed
-   with caution as this command rewrites the commit history:
-
-   ```shell
-   git push --force git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch
-   ```
-
-   Note the colon (`:`) between the two branches. The general scheme is:
-
-   ```shell
-   git push <forked_repository_git_url> <local_branch>:<fork_branch>
-   ```
+To push changes, or add a commit, to the branch of a fork, you can use command line Git.
+For more information, see [use Git to push to a fork as an upstream member](../../../topics/git/forks.md#push-to-a-fork-as-an-upstream-member).
 
 ## Troubleshooting
 

doc/user/project/repository/forking_workflow.md

@@ -98,57 +98,15 @@ To update your fork from the GitLab UI:
 
 ### From the command line
 
-To update your fork from the command line, first ensure that you have configured
-an `upstream` remote repository for your fork:
+You can also choose to update your fork from the command line.
 
-1. Clone your fork locally, if you have not already done so. For more information, see
-   [Cloning Git repositories](../../../topics/git/clone.md).
-1. View the remotes configured for your fork:
-
-   ```shell
-   git remote -v
-   ```
-
-1. If your fork does not have a remote pointing to the original repository,
-   use one of these examples to configure a remote called `upstream`:
-
-   ```shell
-   # Use this line to set any repository as your upstream after editing <upstream_url>
-   git remote add upstream <upstream_url>
-
-   # Use this line to set the main GitLab repository as your upstream
-   git remote add upstream https://gitlab.com/gitlab-org/gitlab.git
-   ```
-
-   After ensuring your local copy has the extra remote configured, you are ready to update your fork.
-
-1. In your local copy, ensure you have checked out the [default branch](branches/default.md),
-   replacing `main` with the name of your default branch:
-
-   ```shell
-   git checkout main
-   ```
-
-   If Git identifies unstaged changes, commit or stash them before continuing.
-
-1. Fetch the changes to the upstream repository:
-
-   ```shell
-   git fetch upstream
-   ```
-
-1. Pull the changes into your fork, replacing `main` with the name of the branch
-   you are updating:
-
-   ```shell
-   git pull upstream main
-   ```
+Prerequisites:
 
-1. Push the changes to your fork repository on the server (GitLab.com or self-managed):
+- You must [download and install the Git client](../../../topics/git/how_to_install_git/index.md) on your local machine.
+- You must [create a fork](#create-a-fork) of the repository you want to update.
 
-   ```shell
-   git push origin main
-   ```
+To update your fork from the command line, follow the instruction in
+[use Git to update a fork](../../../topics/git/forks.md#update-a-fork).
 
 ### With repository mirroring