# Fork a repository

Copy a repository, with every branch and tag, into a new private repository of the same organization, and keep it up to date.

A fork is a new private repository in the same organization, whatever the parent's visibility.
From then on the two are independent: deleting the parent leaves the fork. The examples use the
parent's id `5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60` and the fork's id
`8a1f3c2d-4b5e-4f60-9a7b-8c9d0e1f2a3b`; replace my-fork with the fork's name.

## Prerequisites

- Permission for `git:PullRepository` on the parent and `git:CreateRepository`.
- In the Deutsche Cloud Console, also `git:GetRepository` on the parent to open its page (without it the page
  is not found).
- The parent is not empty, and the organization is below its `git.repositories` quota.
- To sync a fork, `git:PushRepository` on the fork and `git:PullRepository` on the parent. An
  archived fork cannot be synced.

## Fork it

**Console**
1. Open the repository, then choose **Fork** in its header. The button is shown only when the
   repository is not empty and you may fork it.
2. For **Name**, keep _repository_`-fork` or enter my-fork.
3. Choose **Create fork**. The new repository's page opens.

**CLI**
```sh
dcloud git repositories fork 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 --name my-fork
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/fork
{ "name": "my-fork" }
```

The API answers 202 with the new repository. The copy runs in the background and the new
repository shows its progress, as an import does (`importState`). Its header says **Forked from**,
and the parent's header counts its **Forks**.

The fork is refused with 409 `An empty repository has nothing to fork`, 409
`A repository named "<name>" already exists`, or 409 with `code: QuotaExceeded`.

## Sync a fork

**Sync fork** brings a branch of the fork up to the parent's branch of the same name: in the
Deutsche Cloud Console the default branch, from the CLI or API the default branch or the branch you name. It
only fast-forwards, and nothing on the fork is overwritten. The update goes through branch
protection, CI and webhooks like a push.

**Console**
1. Open the fork, then choose **Sync fork** in its header. Below the button it says
   _branch_ `is now` _parent_`'s.`, _branch_ `is already up to date.`, or why it was refused.

**CLI**
```sh
dcloud git repositories sync-fork 8a1f3c2d-4b5e-4f60-9a7b-8c9d0e1f2a3b --branch main
```

**API**
```http
POST /git/api/repositories/8a1f3c2d-4b5e-4f60-9a7b-8c9d0e1f2a3b/sync-fork
{ "branch": "main" }
```

The answer's `updated` says whether the branch moved. A sync is refused with 409 and the reason:

- `"<branch>" has commits the parent does not; it cannot be fast-forwarded. Merge the parent's changes in a pull request.`
- `The parent has no branch "<branch>".`
- `This repository is not a fork`, `The parent repository is gone`, or `Repository is archived`.
- A refusal from the fork's branch protection.

## Related

- Pull requests from a fork into its parent are not supported; see [Not supported](not-supported.md).
- `git.repositories.fork` · `dcloud git repositories fork` · `dcloud git repositories sync-fork`
