Commit 4c10387e authored by Russell Dickenson's avatar Russell Dickenson Committed by Evan Read

Changes to Repository docs for SSOT epic

Content about Repository was edited to comply with
docs standards. This is part of a SSOT epic.

- Added standard elements to each file.
- Moved content on Branches, and Compare, to the
  Branches file.
- Added a brief introduction piece to the GPG
  content.
- Lightly edited all content to improve clarity.
parent 2f680d64
---
type: concepts, howto
---
# Branches
Read through GiLab's branching documentation:
A branch is a version of a project's working tree. You create a branch for each
set of related changes you make. This keeps each set of changes separate from
each other, allowing changes to be made in parallel, without affecting each
other.
After pushing your changes to a new branch, you can:
- Create a [merge request](../../merge_requests/index.md)
- Perform inline code review
- [Discuss](../../discussions/index.md) your implementation with your team
- Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md).
With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request
[approval](../../merge_requests/merge_request_approvals.md) from your managers.
For more information on managing branches using the GitLab UI, see:
- [Default branches](#default-branch)
- [Create a branch](../web_editor.md#create-a-new-branch)
- [Protected branches](../../protected_branches.md#protected-branches)
- [Delete merged branches](#delete-merged-branches)
- [Branch filter search box](#branch-filter-search-box)
You can also manage branches using the
[command line](../../../../gitlab-basics/start-using-git.md#create-a-branch).
- [Create a branch](../web_editor.md#create-a-new-branch).
- [Default branch](#default-branch).
- [Protected branches](../../protected_branches.md#protected-branches).
- [Delete merged branches](#delete-merged-branches).
- [Branch filter search box](#branch-filter-search-box).
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>Watch the video [GitLab Flow](https://www.youtube.com/watch?v=InKNIvky2KE).
See also:
- [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API.
- [GitLab Flow](../../../../university/training/gitlab_flow.md). Use the best of GitLab for your branching strategies.
- [GitLab Flow](../../../../university/training/gitlab_flow.md) documentation.
- [Getting started with Git](../../../../topics/git/index.md) and GitLab.
## Default branch
......@@ -29,6 +53,17 @@ The default branch is also protected against accidental deletion. Read through
the documentation on [protected branches](../../protected_branches.md#protected-branches)
to learn more.
## Compare
To compare branches in a repository:
1. Navigate to your project's repository.
1. Select **Repository > Compare** in the sidebar.
1. Select branches to compare using the [branch filter search box](#branch-filter-search-box)
1. Click **Compare** to view the changes inline:
![compare branches](img/compare_branches.png)
## Delete merged branches
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6449) in GitLab 8.14.
......@@ -57,3 +92,15 @@ Sometimes when you have hundreds of branches you may want a more flexible matchi
- `^feature` will only match branch names that begin with 'feature'.
- `feature$` will only match branch names that end with 'feature'.
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
# Signing commits with GPG
---
type: concepts, howto
---
NOTE: **Note:**
The term GPG is used for all OpenPGP/PGP/GPG related material and
implementations.
# Signing commits with GPG
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9546) in GitLab 9.5.
> - Subkeys support was added in GitLab 10.1.
GitLab can show whether a commit is verified or not when signed with a GPG key.
All you need to do is upload the public GPG key in your profile settings.
You can use a GPG key to sign Git commits made in a GitLab repository. Signed
commits are labeled **Verified** if the identity of the committer can be
verified. To verify the identity of a committer, GitLab requires their public
GPG key.
GPG verified tags are not supported yet.
NOTE: **Note:**
The term GPG is used for all OpenPGP/PGP/GPG related material and
implementations.
## Getting started with GPG
GPG verified tags are not supported yet.
Here are a few guides to get you started with GPG:
- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys)
- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices)
- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced)
See the [further reading](#further-reading) section for more details on GPG.
## How GitLab handles GPG
GitLab uses its own keyring to verify the GPG signature. It does not access any
public key server.
In order to have a commit verified on GitLab the corresponding public key needs
to be uploaded to GitLab. For a signature to be verified three conditions need
to be met:
For a commit to be verified by GitLab:
1. The public key needs to be added your GitLab account
1. One of the emails in the GPG key matches a **verified** email address you use in GitLab
1. The committer's email matches the verified email from the gpg key
- The committer must have a GPG public/private key pair.
- The committer's public key must have been uploaded to their GitLab
account.
- One of the emails in the GPG key must match a **verified** email address
used by the committer in GitLab.
- The committer's email address must match the verified email address from the
GPG key.
## Generating a GPG key
......@@ -65,8 +66,7 @@ started:
Your selection? 1
```
1. The next question is key length. We recommend to choose the highest value
which is `4096`:
1. The next question is key length. We recommend you choose `4096`:
```
RSA keys may be between 1024 and 4096 bits long.
......@@ -74,8 +74,8 @@ started:
Requested keysize is 4096 bits
```
1. Next, you need to specify the validity period of your key. This is something
subjective, and you can use the default value which is to never expire:
1. Specify the validity period of your key. This is something
subjective, and you can use the default value, which is to never expire:
```
Please specify how long the key should be valid.
......@@ -94,9 +94,9 @@ started:
Is this correct? (y/N) y
```
1. Enter you real name, the email address to be associated with this key (should
match a verified email address you use in GitLab) and an optional comment
(press <kbd>Enter</kbd> to skip):
1. Enter your real name, the email address to be associated with this key
(should match a verified email address you use in GitLab) and an optional
comment (press <kbd>Enter</kbd> to skip):
```
GnuPG needs to construct a user ID to identify your key.
......@@ -270,3 +270,24 @@ via [push rules](../../../../push_rules/push_rules.md).
## GPG signing API
Learn how to [get the GPG signature from a commit via API](../../../../api/commits.md#get-gpg-signature-of-a-commit).
## Further reading
For more details about GPG, see:
- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys)
- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices)
- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced)
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
---
type: concepts, howto
---
# Repository
A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository)
......@@ -111,33 +115,7 @@ GitLab.
## Branches
When you submit changes in a new [branch](branches/index.md), you create a new version
of that project's file tree. Your branch contains all the changes
you are presenting, which are detected by Git line by line.
To continue your workflow, once you pushed your changes to a new branch,
you can create a [merge request](../merge_requests/index.md), perform
inline code review, and [discuss](../../discussions/index.md)
your implementation with your team.
You can live preview changes submitted to a new branch with
[Review Apps](../../../ci/review_apps/index.md).
With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request
[approval](../merge_requests/merge_request_approvals.md) from your managers.
To create, delete, and view [branches](branches/index.md) via GitLab's UI:
- [Default branches](branches/index.md#default-branch)
- [Create a branch](web_editor.md#create-a-new-branch)
- [Protected branches](../protected_branches.md#protected-branches)
- [Delete merged branches](branches/index.md#delete-merged-branches)
- [Branch filter search box](branches/index.md#branch-filter-search-box)
Alternatively, you can use the
[command line](../../../gitlab-basics/start-using-git.md#create-a-branch).
To learn more about branching strategies read through the
[GitLab Flow](../../../university/training/gitlab_flow.md) documentation.
For details, see [Branches](branches/index.md).
## Commits
......@@ -213,14 +191,6 @@ detected, add the following to `.gitattributes` in the root of your repository.
> *.proto linguist-detectable=true
## Compare
Select branches to compare using the [branch filter search box](branches/index.md#branch-filter-search-box), then click the **Compare** button to view the changes inline:
![compare branches](img/compare_branches.png)
Find it under your project's **Repository > Compare**.
## Locked files **(PREMIUM)**
Use [File Locking](../file_lock.md) to
......@@ -256,3 +226,15 @@ By clicking the download icon, a dropdown will open with links to download the f
`tar`, `tar.gz`, and `tar.bz2`.
- **Artifacts:**
allows users to download the artifacts of the latest CI build.
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
---
type: howto
---
# Reducing the repository size using Git
A GitLab Enterprise Edition administrator can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md)
......@@ -139,3 +143,15 @@ purposes!
```
Your repository should now be below the size limit.
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
---
type: howto
---
# GitLab Web Editor
Sometimes it's easier to make quick changes directly from the GitLab interface
......@@ -169,3 +173,15 @@ through the web editor, you can choose to use another of your linked email
addresses from the **User Settings > Edit Profile** page.
[ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment