From 4c10387e4302f66d338ff34adf3525f208082dce Mon Sep 17 00:00:00 2001 From: Russell Dickenson Date: Mon, 29 Jul 2019 23:43:43 +0000 Subject: [PATCH] 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. --- .../{ => branches}/img/compare_branches.png | Bin doc/user/project/repository/branches/index.md | 61 ++++++++++++-- .../repository/gpg_signed_commits/index.md | 75 +++++++++++------- doc/user/project/repository/index.md | 52 ++++-------- .../reducing_the_repo_size_using_git.md | 16 ++++ doc/user/project/repository/web_editor.md | 16 ++++ 6 files changed, 151 insertions(+), 69 deletions(-) rename doc/user/project/repository/{ => branches}/img/compare_branches.png (100%) diff --git a/doc/user/project/repository/img/compare_branches.png b/doc/user/project/repository/branches/img/compare_branches.png similarity index 100% rename from doc/user/project/repository/img/compare_branches.png rename to doc/user/project/repository/branches/img/compare_branches.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index a81c9197ec1..0858e8b2624 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -1,17 +1,41 @@ +--- +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. -- [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). +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). + +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'. + + diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 3b0a045ef9c..b929c6a681a 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -1,38 +1,39 @@ +--- +type: concepts, howto +--- + # 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. + +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. + NOTE: **Note:** The term GPG is used for all OpenPGP/PGP/GPG related material and implementations. -> - [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. - GPG verified tags are not supported yet. -## Getting started with GPG - -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 Enter 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 Enter 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) + + diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 5b5685b3418..84d63d29929 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -1,3 +1,7 @@ +--- +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. + + diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 7c711bc0b3b..3adf66e4b6f 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -1,3 +1,7 @@ +--- +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. + + diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 0116f0fe7ca..09a5cdabc00 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,3 +1,7 @@ +--- +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 + +