# Getting started with Git

Create a repository, push to it over HTTPS, open a pull request and merge it, in about ten minutes.

Replace these values:

- my-repo: the repository name.
- my-org: your organization's name as it appears in clone URLs.
- `5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60`: the repository id, which the create call returns and
  `dcloud git repositories list` shows.

## Prerequisites

- `git` on your machine.
- Permission for `git:CreateRepository`, `git:CreateAccessToken`, `git:PushRepository`,
  `git:CreatePullRequest`, `git:MergePullRequest`, `git:DeleteRepository` and
  `git:DeleteAccessToken`. The `AdministratorAccess` policy grants all of them.
- In the Deutsche Cloud Console, also `git:ListRepositories` to open **Git → Repositories** (without it the
  page shows only an access-denied notice).
- In the Deutsche Cloud Console, also `git:GetRepository` to open the repository's pages (without it the page
  is not found).
- In the Deutsche Cloud Console, also `git:GetPullRequest` to open the pull request (without it the page is
  not found).
- In the Deutsche Cloud Console, also `git:ListAccessTokens` to open **Account → Git tokens** (without it the
  page shows an access-denied notice).
- For the CLI tab, the `dcloud` CLI, signed in.

## Step 1: Create a repository

**Console**
1. Open **Git → Repositories**, then choose **New repository**.
2. On step **Identity**, under **Source**, choose **Start empty**.
3. For **Repository name**, enter my-repo.
4. Under **Visibility**, keep **Private**, then choose **Continue**.
5. On step **Initialisation**, keep the default branch `main` and leave the starter files off, then
   choose **Continue**.
6. On step **Access**, choose **Create repository**. The repository's page opens.

**CLI**
```sh
dcloud git repositories create --name my-repo --visibility private
```

**API**
```http
POST /git/api/repositories
{ "name": "my-repo", "visibility": "private" }
```

## Step 2: Create an access token

**Console**
1. In the repository, choose **Settings**, then **Access tokens**.
2. Choose **Create token**.
3. For **Name**, enter laptop. For **Expires**, choose **In 7 days**.
4. Keep **Repositories** at **Only** _my-repo_ and **Permissions** at **Read and write (clone,
   fetch and push)**.
5. Choose **Create token**. Copy the token now: it is shown once.

From the CLI and API a token without `--repository-ids` reaches every repository you can reach,
and one without `--expires-in-days` never expires.

**CLI**
```sh
dcloud git access-tokens create --name laptop --expires-in-days 7
```

**API**
```http
POST /git/api/access-tokens
{ "name": "laptop", "expiresInDays": 7 }
```

The token has the form `prefix.secret`.

## Step 3: Clone and push

```sh
git clone https://git.<platform domain>/my-org/my-repo.git
cd my-repo
echo "# my-repo" > README.md
git add README.md && git commit -m "Add README"
git push origin HEAD:main
git switch -c add-greeting
echo "Hello" > hello.txt
git add hello.txt && git commit -m "Add greeting"
git push origin add-greeting
```

When `git` asks, give the token's prefix as the username and its secret as the password. Pasting
the whole `prefix.secret` value into either field also works.

## Step 4: Open a pull request

**Console**
1. In the repository, choose **Pull requests**, then **New pull request**.
2. Pick `add-greeting` as the source branch and `main` as the target branch.
3. For the title, enter Add greeting.
4. Choose **Create pull request**. The pull request opens with its merge status.

**CLI**
```sh
dcloud git pulls create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --title "Add greeting" --source-branch add-greeting --target-branch main
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls
{ "title": "Add greeting", "sourceBranch": "add-greeting", "targetBranch": "main" }
```

## Step 5: Merge it

**Console**
1. On the pull request, choose the method **Squash**.
2. Choose **Merge pull request**. The pull request shows **Merged**.

**CLI**
```sh
dcloud git pulls merge 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 1 --method squash
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls/1/merge
{ "method": "squash" }
```

`main` now holds the greeting. Run `git pull origin main` to see it locally.

## Clean up

**Warning:**
Deleting a repository deletes all of its code, commits, branches, tags and history. It cannot be
undone.

**Console**
1. In the repository, choose **Settings**, then **Danger zone**.
2. Under **Delete this repository**, choose **Delete repository**, type the repository's name to
   confirm, and choose **Delete repository**.
3. Open **Account → Git tokens**, choose **Revoke** on the token you created, and confirm with
   **Revoke**. (On another repository's **Settings → Access tokens**, the token's actions menu has
   **Revoke token**.)

**CLI**
```sh
dcloud git repositories delete 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60
dcloud git access-tokens list
dcloud git access-tokens delete token-id
```

**API**
```http
DELETE /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60
```

Then `DELETE /git/api/access-tokens/{id}` with the token's id.

## Next steps

- [Clone over SSH](clone-over-ssh.md) with a key instead of a token.
- [Protect a branch](protect-a-branch.md) so changes land only through reviewed pull requests.
- [Import a repository](import-a-repository.md) you already have elsewhere.
