First pass to bring /gitlab-basics to SSoT standards

Removes duplicated information, and combines sections and files together when they are duplicated or highly related. Also adds intros to all pages and sections missing intros, and troubleshooting sections to pages that may need them in the future. Links more to other docs, and clarifies language when abosolutely necessary, and adds angle brackets to sample parameters.

First pass to bring /gitlab-basics to SSoT standards
Removes duplicated information, and combines sections and files together when they are duplicated or highly related. Also adds intros to all pages and sections missing intros, and troubleshooting sections to pages that may need them in the future. Links more to other docs, and clarifies language when abosolutely necessary, and adds angle brackets to sample parameters.
7f18248a · Marcel Amirault · Evan Read · 52af120f · 7f18248a · 7f18248a
Commit 7f18248a authored Jul 30, 2019 by Marcel Amirault Committed by Evan Read Jul 30, 2019
11 changed files
--- a/doc/gitlab-basics/README.md
+++ b/doc/gitlab-basics/README.md
 ---
 comments: false
+type: index
 ---
 # GitLab basics guides
-This section provides resources to help you start with GitLab by focusing on basic functionality.
+This section provides resources to help you start working with GitLab and Git by focusing
+on the basic features that you will need to use.
 This documentation is split into the following groups:
 - [GitLab-specific functionality](#gitlab-basics), for basic GitLab features.
- [General Git functionality](#git-basics), for working with Git in conjunction with GitLab.
+- [General Git functionality](#working-with-git-from-the-command-line), for working
+  with Git in conjunction with GitLab.
 ## GitLab basics
@@ -17,22 +20,26 @@ The following are guides to basic GitLab functionality:
 - [Create and add your SSH public key](create-your-ssh-keys.md), for enabling Git over SSH.
 - [Create a project](create-project.md), to start using GitLab.
- [Create a group](../user/group/index.md#create-a-new-group), to combine and administer projects together.
+- [Create a group](../user/group/index.md#create-a-new-group), to combine and administer
+  projects together.
 - [Create a branch](create-branch.md), to make changes to files stored in a project's repository.
 - [Fork a project](fork-project.md), to duplicate projects so they can be worked on in parallel.
 - [Add a file](add-file.md), to add new files to a project's repository.
- [Add an image](add-image.md), to add new images to a project's repository.
+- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue),
- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue), to start collaborating within a project.
+  to start collaborating within a project.
- [Create a merge request](add-merge-request.md), to request changes made in a branch be merged into a project's repository.
+- [Create a merge request](add-merge-request.md), to request changes made in a branch
- See how these features come together in the [GitLab Flow introduction video](https://youtu.be/InKNIvky2KE) and [GitLab Flow page](../workflow/gitlab_flow.md).
+  be merged into a project's repository.
+- See how these features come together in the [GitLab Flow introduction video](https://youtu.be/InKNIvky2KE)
+  and [GitLab Flow page](../workflow/gitlab_flow.md).
-## Git basics
+## Working with Git from the command line
-If you're familiar with Git on the command line, you can interact with your GitLab projects just as you would with any other Git repository.
+If you're familiar with Git on the command line, you can interact with your GitLab
+projects just as you would with any other Git repository.
 These resources will help get further acclimated to working on the command line.
 - [Start using Git on the command line](start-using-git.md), for some simple Git commands.
 - [Command line basics](command-line-commands.md), to create and edit files using the command line.
-More Git resources are available at GitLab's [Git documentation](../topics/git/index.md).
+More Git resources are available in GitLab's [Git documentation](../topics/git/index.md).
--- a/doc/gitlab-basics/add-file.md
+++ b/doc/gitlab-basics/add-file.md
-# How to add a file
+---
+type: howto
+---
-You can create a file in your [terminal](command-line-commands.md) and push
+# Add a file to a repository
-to GitLab or you can use the
+Adding files to a repository is a small, but key task. Bringing files in to a repository,
+such as code, images, or documents, allows them to be tracked by Git, even though they
+may have been created elsewhere.
+You can add a file to a repository in your [terminal](#add-a-file-using-the-command-line), and
+then push to GitLab. You can also use the [web interface](../user/project/repository/web_editor.md#upload-a-file),
+which may be a simpler solution.
+If you need to create a file first, for example a `README.md` text file, that can
+also be done from the [terminal](command-line-commands.md#create-a-text-file-in-the-current-directory) or
 [web interface](../user/project/repository/web_editor.md#create-a-file).
+## Add a file using the command line
+Open a [terminal/shell](command-line-commands.md), and change into the folder of your
+GitLab project. This usually means running the following command until you get
+to the desired destination:
+```sh
+cd <destination folder>
+```
+[Create a branch](create-branch.md) to add your file to, before it is added to the master
+(main) branch of the project. It is not strictly necessary, but working directly in
+the `master` branch is not recommended unless your project is very small, and you are
+the only person working on it. You can [switch to an existing branch](start-using-git.md#work-on-an-existing-branch),
+if you have one already.
+Using your standard tool for copying files (for example, Finder in macOS, or File Explorer
+in Windows), put the file into a directory within the GitLab project.
+Check if your file is actually present in the directory (if you are in Windows,
+use `dir` instead):
+```sh
+ls
+```
+You should see the name of the file in the list shown.
+Check the status:
+```sh
+git status
+```
+Your file's name should appear in red, so `git` took notice of it! Now add it
+to the repository:
+```sh
+git add <name of file>
+```
+Check the status again, your file's name should have turned green:
+```sh
+git status
+```
+Commit (save) your file to the repository:
+```sh
+git commit -m "DESCRIBE COMMIT IN A FEW WORDS"
+```
+Now you can push (send) your changes (in the branch `<branch-name>`) to GitLab
+(the git remote named 'origin'):
+```sh
+git push origin <branch-name>
+```
+Your image will be added to your branch in your repository in GitLab.
+<!-- ## 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. -->
--- a/doc/gitlab-basics/add-image.md
+++ b/doc/gitlab-basics/add-image.md
-# How to add an image
+---
+redirect_to: 'add-file.md'
+---
-Using your standard tool for copying files (e.g. Finder in Mac OS, or Explorer
+This document was moved to [another location](add-file.md).
-in Windows, or...), put the image file into the GitLab project. You can find the
-project as a regular folder in your files.
-Go to your [shell](command-line-commands.md), and move into the folder of your
-GitLab project. This usually means running the following command until you get
-to the desired destination:
-```
-cd NAME-OF-FOLDER-YOU'D-LIKE-TO-OPEN
-```
-Check if your image is actually present in the directory (if you are in Windows,
-use `dir` instead):
-```
-ls
-```
-You should see the name of the image in the list shown.
-Check the status:
-```
-git status
-```
-Your image's name should appear in red, so `git` took notice of it! Now add it
-to the repository:
-```
-git add NAME-OF-YOUR-IMAGE
-```
-Check the status again, your image's name should have turned green:
-```
-git status
-```
-Commit:
-```
-git commit -m "DESCRIBE COMMIT IN A FEW WORDS"
-```
-Now you can push (send) your changes (in the branch NAME-OF-BRANCH) to GitLab
-(the git remote named 'origin'):
-```
-git push origin NAME-OF-BRANCH
-```
-Your image will be added to your branch in your repository in GitLab.
--- a/doc/gitlab-basics/add-merge-request.md
+++ b/doc/gitlab-basics/add-merge-request.md
+---
+type: howto
+---
 # How to create a merge request
-Merge requests are useful to integrate separate changes that you've made to a
+Merge requests are how you integrate separate changes that you've made in a
-project, on different branches. This is a brief guide on how to create a merge
+[branch](create-branch.md) to a [project](create-project.md).
-request. For more information, check the
-[merge requests documentation](../user/project/merge_requests/index.md).
+This is a brief guide on how to create a merge request. For more detailed information,
+check the [merge requests documentation](../user/project/merge_requests/index.md), or
+you can watch our [GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE) for
+a quick overview of working with merge requests.
 ---
@@ -12,7 +19,7 @@ request. For more information, check the
 1. Go to the project where you'd like to merge your changes and click on the
   **Merge requests** tab.
 1. Click on **New merge request** on the right side of the screen.
-1. From there on, you have the option to select the source branch and the target
+1. From there, you have the option to select the source branch and the target
   branch you'd like to compare to. The default target project is the upstream
   repository, but you can choose to compare across any of its forks.
@@ -20,11 +27,23 @@ request. For more information, check the
 1. When ready, click on the **Compare branches and continue** button.
 1. At a minimum, add a title and a description to your merge request. Optionally,
-   select a user to review your merge request and to accept or close it. You may
+   select a user to review your merge request. You may also select a milestone and
-   also select a milestone and labels.
+   labels.
   ![New merge request page](img/merge_request_page.png)
 1. When ready, click on the **Submit merge request** button.
-Your merge request will be ready to be approved and merged.
+Your merge request will be ready to be reviewed, approved, and merged.
+<!-- ## 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. -->
--- a/doc/gitlab-basics/basic-git-commands.md
+++ b/doc/gitlab-basics/basic-git-commands.md
-# Basic Git commands
+---
+redirect_to: 'start-using-git.md'
+---
-This section is now merged into [Start using Git](start-using-git.md).
+This document was moved to [another location](start-using-git.md).
--- a/doc/gitlab-basics/command-line-commands.md
+++ b/doc/gitlab-basics/command-line-commands.md
-# Command Line basic commands
+---
+type: howto, reference
-## Start working on your project
+---
-In Git, when you copy a project you say you "clone" it. To work on a git project locally (from your own computer), you will need to clone it. To do this, sign in to GitLab.
-When you are on your Dashboard, click on the project that you'd like to clone.
-To work in the project, you can copy a link to the Git repository through a SSH
-or a HTTPS protocol. SSH is easier to use after it's been
-[set up](create-your-ssh-keys.md). While you are at the **Project** tab, select
-HTTPS or SSH from the dropdown menu and copy the link using the _Copy URL to clipboard_
-button (you'll have to paste it on your shell in the next step).
-![Copy the HTTPS or SSH](img/project_clone_url.png)
-## Working with project files on the command line
-This section has examples of some basic shell commands that you might find useful. For more information, search the web for _bash commands_.
-Alternatively, you can edit files using your choice of editor (IDE) or the GitLab user interface.
-### Clone your project
-Go to your computer's shell and type the following command with your SSH or HTTPS URL:
-```
+# Command Line basic commands
-git clone PASTE HTTPS OR SSH HERE
-```
-A clone of the project will be created in your computer.
-NOTE: **Note:**
-If you clone your project via a URL that contains special characters, make sure
-that characters are URL-encoded.
-### Go into a project directory to work in it
-```
-cd NAME-OF-PROJECT
-```
-### Go back one directory
+When [working with Git from the command line](start-using-git.md), you will need to
+use more than just the Git commands. There are several basic commands that you should
+learn, in order to make full use of the command line.
-```
+## Start working on your project
-cd ..
-```
-### List what’s in the current directory
+To work on a git project locally (from your own computer), with the command line,
+first you will need to [clone (copy) it](start-using-git.md#clone-a-repository) to
+your computer.
-```
+## Working with files on the command line
-ls
-```
-### List what’s in the current directory that starts with `a`
+This section has examples of some basic shell commands that you might find useful.
+For more information, search the web for _bash commands_.
-```
+Alternatively, you can edit files using your choice of editor (IDE), or the GitLab user
-ls a*
+interface (not locally).
-```
-### List what’s in the current directory that ends with `.md`
+### Common commands
-```
+The list below is not exhaustive, but contains many of the most commonly used commands.
-ls *.md
-```
-### Create a new directory
+| Command                        | Description                                 |
+|--------------------------------|---------------------------------------------|
+| `cd NAME-OF-DIRECTORY`         | Go into a directory to work in it           |
+| `cd ..`                        | Go back one directory                       |
+| `ls`                           | List what’s in the current directory        |
+| `ls a*`                        | List what’s in the current directory that starts with `a` |
+| `ls *.md`                      | List what’s in the current directory that ends with `.md` |
+| `mkdir NAME-OF-YOUR-DIRECTORY` | Create a new directory                      |
+| `cat README.md`                | Display the contents of a [text file you created previously](#create-a-text-file-in-the-current-directory) |
+| `pwd`                          | Show the current directory                  |
+| `clear`                        | Clear the shell window                      |
-```
+### Create a text file in the current directory
-mkdir NAME-OF-YOUR-DIRECTORY
-```
-### Create a README.md file in the current directory
+To create a text file from the command line, for example `README.md`, follow these
+steps:
 ```
 touch README.md
@@ -80,37 +52,37 @@ nano README.md
 #### Press: enter
 ```
-### Show the contents of the README.md file
+### Remove a file or directory
-```
+It is easy to delete (remove) a file or directory, but be careful:
-cat README.md
-```
-### Remove a file
 DANGER: **Danger:**
-This will permanently delete the file.
+This will **permanently** delete a file.
 ```
 rm NAME-OF-FILE
 ```
-### Remove a directory and all of its contents
 DANGER: **Danger:**
-This will permanently delete the directory and all of its contents.
+This will **permanently** delete a directory and **all** of its contents.
 ```
 rm -r NAME-OF-DIRECTORY
 ```
-### View command history
+### View and Execute commands from history
+You can view the history of all the commands you executed from the command line,
+and then execute any of them again, if needed.
+First, list the commands you executed previously:
 ```
 history
 ```
-### Execute command 123 from history
+Then, choose a command from the list and check the number next to the command (`123`,
+for example) . Execute the same full command with:
 ```
 !123
@@ -118,28 +90,32 @@ history
 ### Carry out commands for which the account you are using lacks authority
-You will be asked for an administrator’s password.
+Not all commands can be executed from a basic user account on a computer, you may
+need administrator's rights to execute commands that affect the system, or try to access
+protected data, for example. You can use `sudo` to execute these commands, but you
+will likely be asked for an administrator password.
 ```
-sudo COMMAND
+sudo RESTRICTED-COMMAND
 ```
 CAUTION: **Caution:**
 Be careful of the commands you run with `sudo`. Certain commands may cause
-damage to your data and system.
+damage to your data or system.
-### Show which directory I am in
+## Sample Git taskflow
-```
+If you are completely new to Git, looking through some [sample taskflows](https://rogerdudler.github.io/git-guide/)
-pwd
+will help you understand the best practices for using these commands as you work.
-```
-### Clear the shell window
-```
+<!-- ## Troubleshooting
-clear
-```
-### Sample Git taskflow
+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.
-If you are completely new to Git, looking through some [sample taskflows](https://rogerdudler.github.io/git-guide/) will help you understand best practices for using these commands as you work.
+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. -->
--- a/doc/gitlab-basics/create-branch.md
+++ b/doc/gitlab-basics/create-branch.md
+---
+type: howto
+---
 # How to create a branch
-A branch is an independent line of development.
+A branch is an independent line of development in a [project](../user/project/index.md).
-New commits are recorded in the history for the current branch, which results
+When you create a new branch (in your [terminal](basic-git-commands.md) or with
-in taking the source from someone’s repository (the place where the history of
+[the web interface](../user/project/repository/web_editor.md#create-a-new-branch)),
-your work is stored) at certain point in time, and apply your own changes to it
+you are creating a snapshot of a certain branch, usually the main `master` branch,
-in the history of the project.
+at it's current state. From there, you can start to make your own changes without
+affecting the main codebase. The history of your changes will be tracked in your branch.
-To add changes to your GitLab project, you should create a branch. You can do
+When your changes are ready, you then merge them into the rest of the codebase with a
-it in your [terminal](basic-git-commands.md) or by
+[merge request](add-merge-request.md).
-[using the web interface](../user/project/repository/web_editor.md#create-a-new-branch).
--- a/doc/gitlab-basics/create-project.md
+++ b/doc/gitlab-basics/create-project.md
-# Create a project
+---
+type: howto
+---
-[Projects](../user/project/index.md) combine many features of GitLab together.
+# Creating projects
-NOTE: **Note:**
+Most work in GitLab is done within a [Project](../user/project/index.md). Files and
-For a list of words that cannot be used as project names see
+code are saved in projects, and most features are used within the scope of projects.
-[Reserved project and group names](../user/reserved_names.md).
+## Create a project in GitLab
 To create a project in GitLab:
@@ -14,11 +17,14 @@ To create a project in GitLab:
   - Create a [blank project](#blank-projects).
   - Create a project using with one of the available [project templates](#project-templates).
   - [Import a project](../user/project/import/index.md) from a different repository,
-     if enabled on your GitLab instance. Contact your GitLab admin if this
+     if enabled on your GitLab instance. Contact your GitLab admin if this is unavailable.
-     is unavailable.
   - Run [CI/CD pipelines for external repositories](../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)**
-## Blank projects
+NOTE: **Note:**
+For a list of words that cannot be used as project names see
+[Reserved project and group names](../user/reserved_names.md).
+### Blank projects
 To create a new blank project on the **New project** page:
@@ -37,23 +43,25 @@ To create a new blank project on the **New project** page:
     can be cloned.
 1. Click **Create project**.
-## Project templates
+### Project templates
-Project templates can pre-populate your project with necessary files to get you started quickly.
+Project templates can pre-populate a new project with the necessary files to get you
+started quickly.
 There are two types of project templates:
 - [Built-in templates](#built-in-templates), sourced from the following groups:
  - [`project-templates`](https://gitlab.com/gitlab-org/project-templates)
  - [`pages`](https://gitlab.com/pages)
- [Custom project templates](#custom-project-templates-premium-only), for custom templates configured by GitLab administrators and users.
+- [Custom project templates](#custom-project-templates-premium-only), for custom templates
+  configured by GitLab administrators and users.
-### Built-in templates
+#### Built-in templates
 Built-in templates are project templates that are:
- Developed and maintained in the
+- Developed and maintained in the [`project-templates`](https://gitlab.com/gitlab-org/project-templates)
-  [`project-templates`](https://gitlab.com/gitlab-org/project-templates) and [`pages`](https://gitlab.com/pages) groups.
+  and [`pages`](https://gitlab.com/pages) groups.
 - Released with GitLab.
 To use a built-in template on the **New project** page:
@@ -62,22 +70,25 @@ To use a built-in template on the **New project** page:
 1. From the list of available built-in templates, click the:
   - **Preview** button to look at the template source itself.
   - **Use template** button to start creating the project.
-1. Finish creating the project by filling out the project's details. The process is the same as for
+1. Finish creating the project by filling out the project's details. The process is
-   using a [blank project](#blank-projects).
+   the same as creating a [blank project](#blank-projects).
 TIP: **Tip:**
-You can improve the existing built-in templates or contribute new ones on the
+You can improve the existing built-in templates or contribute new ones in the
-[`project-templates`](https://gitlab.com/gitlab-org/project-templates) and [`pages`](https://gitlab.com/pages) groups.
+[`project-templates`](https://gitlab.com/gitlab-org/project-templates) and
+[`pages`](https://gitlab.com/pages) groups.
-### Custom project templates **(PREMIUM ONLY)**
+#### Custom project templates **(PREMIUM ONLY)**
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in
 [GitLab Premium](https://about.gitlab.com/pricing) 11.2.
-Creating new projects based on custom project templates is a convenient option to bootstrap a project.
+Creating new projects based on custom project templates is a convenient option to
+bootstrap a project.
-Custom projects are available from the **Instance** or **Group** tabs under the **Create from template** tab,
+Custom projects are available at the [instance-level](../user/admin_area/custom_project_templates.md)
-depending on the type of template.
+from the **Instance** tab, or at the [group-level](../user/group/custom_project_templates.md)
+from the **Group** tab, under the **Create from template** tab.
 To use a custom project template on the **New project** page:
@@ -85,23 +96,19 @@ To use a custom project template on the **New project** page:
 1. From the list of available custom templates, click the:
   - **Preview** button to look at the template source itself.
   - **Use template** button to start creating the project.
-1. Finish creating the project by filling out the project's details. The process is the same as for
+1. Finish creating the project by filling out the project's details. The process is
-   using a [blank project](#blank-projects).
+   the same as creating a [blank project](#blank-projects).
-For information on configuring custom project templates, see:
- [Custom instance-level project templates](../user/admin_area/custom_project_templates.md), for instance-level templates.
- [Custom group-level project templates](../user/group/custom_project_templates.md), for group-level templates.
 ## Push to create a new project
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26388) in GitLab 10.5.
-When you create a new repo locally, instead of going to GitLab to manually
+When you create a new repository locally, instead of going to GitLab to manually
-create a new project and then push the repo, you can directly push it to
+create a new project and then [clone the repo](start-using-git.md#clone-a-repository)
-GitLab to create the new project, all without leaving your terminal. If you have access to that
+locally, you can directly push it to GitLab to create the new project, all without leaving
-namespace, we will automatically create a new project under that GitLab namespace with its
+your terminal. If you have access rights to the associated namespace, GitLab will
-visibility set to Private by default (you can later change it in the [project's settings](../public_access/public_access.md#how-to-change-project-visibility)).
+automatically create a new project under that GitLab namespace with its visibility
+set to Private by default (you can later change it in the [project's settings](../public_access/public_access.md#how-to-change-project-visibility)).
 This can be done by using either SSH or HTTPS:
@@ -127,3 +134,15 @@ remote: To view the project, visit:
 remote:   https://gitlab.example.com/namespace/nonexistent-project
 remote:
 ```
+<!-- ## 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. -->
--- a/doc/gitlab-basics/create-your-ssh-keys.md
+++ b/doc/gitlab-basics/create-your-ssh-keys.md
-# Create and add your SSH public key
+---
+type: howto
+---
-This topic describes how to:
+# Create and add your SSH public key
- Create an SSH key pair to use with GitLab.
+It is best practice to use [Git over SSH instead of Git over HTTP](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols).
- Add the SSH public key to your GitLab account.
+In order to use SSH, you will need to
-You do this to use [Git over SSH instead of Git over HTTP](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols).
+1. [Create an SSH key pair](#creating-your-ssh-key-pair) on your local computer.
+1. [Add the key to GitLab](#adding-your-ssh-public-key-to-gitlab).
 ## Creating your SSH key pair
-1. Go to your [command line](start-using-git.md).
+1. Go to your [command line](start-using-git.md#open-a-shell).
-1. Follow the [instructions](../ssh/README.md#generating-a-new-ssh-key-pair) to generate your SSH key pair.
+1. Follow the [instructions](../ssh/README.md#generating-a-new-ssh-key-pair) to generate
+   your SSH key pair.
 ## Adding your SSH public key to GitLab
-To add the SSH public key to GitLab,
+To add the SSH public key to GitLab, see
-see [Adding an SSH key to your GitLab account](../ssh/README.md#adding-an-ssh-key-to-your-gitlab-account).
+[Adding an SSH key to your GitLab account](../ssh/README.md#adding-an-ssh-key-to-your-gitlab-account).
 NOTE: **Note:**
-Once you add a key, you cannot edit it. If the paste
+Once you add a key, you cannot edit it. If it didn't paste properly, it
-[didn't work](../ssh/README.md#testing-that-everything-is-set-up-correctly), you need to remove the key and re-add it.
+[will not work](../ssh/README.md#testing-that-everything-is-set-up-correctly), and
+you will need to remove the key from GitLab and try adding it again.
--- a/doc/gitlab-basics/fork-project.md
+++ b/doc/gitlab-basics/fork-project.md
+---
+type: howto
+---
 # How to fork a project
 A fork is a copy of an original repository that you put in another namespace
 where you can experiment and apply changes that you can later decide whether or
 not to share, without affecting the original project.
-It takes just a few steps to fork a project in GitLab.
+It takes just a few steps to [fork a project in GitLab](../workflow/forking_workflow.md#creating-a-fork).
-1. Go to a project's dashboard under the **Project** tab and click on the
-   **Fork** button.
-    ![Click on Fork button](img/fork_new.png)
-1. You will be asked where to fork the repository. Click on the user or group
-   to where you'd like to add the forked project.
-    ![Choose namespace](img/fork_choose_namespace.png)
-1. After a few moments, depending on the repository's size, the forking will
-   complete.
--- a/doc/gitlab-basics/start-using-git.md
+++ b/doc/gitlab-basics/start-using-git.md
+---
+type: howto, tutorial
+---
 # Start using Git on the command line
-If you want to start using Git and GitLab, make sure that you have created and/or signed into an account on GitLab.
+While GitLab has a powerful user interface, if you want to use Git itself, you will
+have to do so from the command line. If you want to start using Git and GitLab together,
+make sure that you have created and/or signed into an account on GitLab.
 ## Open a shell
-Depending on your operating system, you will need to use a shell of your preference. Here are some suggestions:
+Depending on your operating system, you will need to use a shell of your preference.
+Here are some suggestions:
- [Terminal](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) on  Mac OSX
+- [Terminal](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) on macOS
 - [GitBash](https://msysgit.github.io) on Windows
 - [Linux Terminal](http://www.howtogeek.com/140679/beginner-geek-how-to-start-using-the-linux-terminal/) on Linux
 ## Check if Git has already been installed
-Git is usually preinstalled on Mac and Linux.
+Git is usually preinstalled on Mac and Linux, so run the following command:
-Type the following command and then press enter:
 ```bash
 git --version
 ```
-You should receive a message that tells you which Git version you have on your computer. If you don’t receive a "Git version" message, it means that you need to [download Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+You should receive a message that tells you which Git version you have on your computer.
+If you don’t receive a "Git version" message, it means that you need to
+[download Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
-If Git doesn't automatically download, there's an option on the website to [download manually](https://git-scm.com/downloads). Then follow the steps on the installation window.
+After you are finished installing Git, open a new shell and type `git --version` again
+to verify that it was correctly installed.
-After you are finished installing Git, open a new shell and type `git --version` again to verify that it was correctly installed.
 ## Add your Git username and set your email
-It is important to configure your Git username and email address, since every Git commit will use this information to identify you as the author.
+It is important to configure your Git username and email address, since every Git
+commit will use this information to identify you as the author.
-On your shell, type the following command to add your username:
+In your shell, type the following command to add your username:
 ```bash
 git config --global user.name "YOUR_USERNAME"
@@ -56,7 +61,10 @@ To verify that you entered your email correctly, type:
 git config --global user.email
 ```
-You'll need to do this only once, since you are using the `--global` option. It tells Git to always use this information for anything you do on that system. If you want to override this with a different username or email address for specific projects, you can run the command without the `--global` option when you’re in that project.
+You'll need to do this only once, since you are using the `--global` option. It tells
+Git to always use this information for anything you do on that system. If you want
+to override this with a different username or email address for specific projects,
+you can run the command without the `--global` option when you’re in that project.
 ## Check your information
@@ -68,12 +76,12 @@ git config --global --list
 ## Basic Git commands
-Start using Git via the command line with the most basic
+Start using Git via the command line with the most basic commands as described below.
-commands as described below.
-## Initialize a local directory for Git version control
+### Initialize a local directory for Git version control
-If you have an existing local directory that you want to *initialize* for version control, use the `init` command to instruct Git to begin tracking the directory:
+If you have an existing local directory that you want to *initialize* for version
+control, use the `init` command to instruct Git to begin tracking the directory:
 ```bash
 git init
@@ -81,34 +89,33 @@ git init
 This creates a `.git` directory that contains the Git configuration files.
-Once the directory has been initialized, you can [add a remote repository](#add-a-remote-repository) and [send changes to GitLab.com](#send-changes-to-gitlabcom). View the instructions on [Create a project](../gitlab-basics/create-project.html#push-to-create-a-new-project) to create a new project on GitLab with your changes.
+Once the directory has been initialized, you can [add a remote repository](#add-a-remote-repository)
+and [send changes to GitLab.com](#send-changes-to-gitlabcom). You will also need to
+[create a new project in GitLab](../gitlab-basics/create-project.html#push-to-create-a-new-project)
+for your Git repository.
 ### Clone a repository
-To start working locally on an existing remote repository,
+To start working locally on an existing remote repository, clone it with the command
-clone it with the command `git clone <repository path>`.
+`git clone <repository path>`. By cloning a repository, you'll download a copy of its
-By cloning a repository, you'll download a copy of its
+files to your local computer, automatically preserving the Git connection with the
-files into your local computer, preserving the Git
+remote repository.
-connection with the remote repository.
-You can either clone it via HTTPS or [SSH](../ssh/README.md).
+You can either clone it via HTTPS or [SSH](../ssh/README.md). If you chose to clone
-If you chose to clone it via HTTPS, you'll have to enter your
+it via HTTPS, you'll have to enter your credentials every time you pull and push.
-credentials every time you pull and push. With SSH, you enter
+With SSH, you enter your credentials only once.
-your credentials once and can pull and push straightaway.
-You can find both paths (HTTPS and SSH) by navigating to
+You can find both paths (HTTPS and SSH) by navigating to your project's landing page
-your project's landing page and clicking **Clone**. GitLab
+and clicking **Clone**. GitLab will prompt you with both paths, from which you can copy
-will prompt you with both paths, from which you can copy
 and paste in your command line.
-As an example, consider a repository path:
+As an example, consider this repository path:
 - HTTPS: `https://gitlab.com/gitlab-org/gitlab-ce.git`
- SSH: `` git@gitlab.com:gitlab-org/gitlab-ce.git ``
+- SSH: `git@gitlab.com:gitlab-org/gitlab-ce.git`
-To get started, open a terminal window in the directory
+To get started, open a terminal window in the directory you wish to clone the repository
-you wish to clone the repository files into, and run one
+files into, and run one of the following commands.
-of the following commands.
 Clone via HTTPS:
@@ -122,13 +129,15 @@ Clone via SSH:
 git clone git@gitlab.com:gitlab-org/gitlab-ce.git
 ```
-Both commands will download a copy of the files in a
+Both commands will download a copy of the files in a folder named after the project's
-folder named after the project's name.
+name. You can then navigate to the directory and start working
-You can then navigate to the directory and start working
 on it locally.
-### Go to the master branch to pull the latest changes from there
+### Switch to the master branch
+You are always in a branch when working with Git. The main branch is the master branch,
+but you can use the same command to switch to a different branch by changing `master`
+to the branch name.
 ```bash
 git checkout master
@@ -136,13 +145,20 @@ git checkout master
 ### Download the latest changes in the project
-This is for you to work on an up-to-date copy (it is important to do this every time you start working on a project), while you set up tracking branches. You pull from remote repositories to get all the changes made by users since the last time you cloned or pulled the project. Later, you can push your local commits to the remote repositories.
+To work on an up-to-date copy of the project (it is important to do this every time
+you start working on a project), you `pull` to get all the changes made by users since
+the last time you cloned or pulled the project. Use `master` for the `<name-of-branch>`
+to get the main branch code, or the branch name of the branch you are currently working
+in.
 ```bash
-git pull REMOTE NAME-OF-BRANCH
+git pull REMOTE <name-of-branch>
 ```
-When you first clone a repository, REMOTE is typically "origin". This is where the repository came from, and it indicates the SSH or HTTPS URL of the repository on the remote server. NAME-OF-BRANCH is usually "master", but it may be any existing branch.
+When you first clone a repository, REMOTE is typically `origin`. This is where the
+repository was cloned from, and it indicates the SSH or HTTPS URL of the repository
+on the remote server. `<name-of-branch>` is usually `master`, but it may be any existing
+branch.
 ### View your remote repositories
@@ -157,17 +173,20 @@ git remote -v
 To add a link to a remote repository:
 ```bash
-git remote add SOURCE-NAME REPOSITORY-PATH
+git remote add <source-name> <repository-path>
 ```
-You'll use this source name every time you [push changes to GitLab.com](#send-changes-to-gitlabcom), so use something easy to remember and type.
+You'll use this source name every time you [push changes to GitLab.com](#send-changes-to-gitlabcom),
+so use something easy to remember and type.
 ### Create a branch
-To create a branch, type the following (spaces won't be recognized in the branch name, so you will need to use a hyphen or underscore):
+To create a new branch, to work from without affecting the `master` branch, type the
+following (spaces won't be recognized in the branch name, so you will need to use a
+hyphen or underscore):
 ```bash
-git checkout -b NAME-OF-BRANCH
+git checkout -b <name-of-branch>>
 ```
 ### Work on an existing branch
@@ -175,12 +194,14 @@ git checkout -b NAME-OF-BRANCH
 To switch to an existing branch, so you can work on it:
 ```bash
-git checkout NAME-OF-BRANCH
+git checkout <name-of-branch>
 ```
 ### View the changes you've made
-It's important to be aware of what's happening and the status of your changes. When you add, change, or delete files/folders, Git knows about it. To check the status of your changes:
+It's important to be aware of what's happening and the status of your changes. When
+you add, change, or delete files/folders, Git knows about it. To check the status of
+your changes:
 ```bash
 git status
@@ -188,7 +209,8 @@ git status
 ### View differences
-To view the differences between your local, unstaged changes and the repository versions that you cloned or pulled, type:
+To view the differences between your local, unstaged changes and the repository versions
+that you cloned or pulled, type:
 ```bash
 git diff
@@ -196,16 +218,19 @@ git diff
 ### Add and commit local changes
-You'll see your local changes in red when you type `git status`. These changes may be new, modified, or deleted files/folders. Use `git add` to stage a local file/folder for committing. Then use `git commit` to commit the staged files:
+You'll see any local changes in red when you type `git status`. These changes may
+be new, modified, or deleted files/folders. Use `git add` to first stage (prepare)
+a local file/folder for committing. Then use `git commit` to commit (save) the staged
+files:
 ```bash
-git add FILE OR FOLDER
+git add <file-name OR folder-name>
 git commit -m "COMMENT TO DESCRIBE THE INTENTION OF THE COMMIT"
 ```
 ### Add all changes to commit
-To add and commit all local changes in one command:
+To add and commit (save) all local changes quickly:
 ```bash
 git add .
@@ -217,35 +242,32 @@ The `.` character typically means _all_ in Git.
 ### Send changes to GitLab.com
-To push all local commits to the remote repository:
+To push all local commits (saved changes) to the remote repository:
 ```bash
-git push REMOTE NAME-OF-BRANCH
+git push <remote> <name-of-branch>
 ```
-For example, to push your local commits to the _master_ branch of the _origin_ remote:
+For example, to push your local commits to the _`master`_ branch of the _`origin`_ remote:
 ```bash
 git push origin master
 ```
-### Delete all changes in the Git repository
+### Delete all changes in the branch
-To delete all local changes in the repository that have not been added to the staging area, and leave unstaged files/folders, type:
+To delete all local changes in the branch that have not been added to the staging
+area, and leave unstaged files/folders, type:
 ```bash
 git checkout .
 ```
-### Delete all untracked changes in the Git repository
+Note that this removes *changes* to files, not the files themselves.
-```bash
-git clean -f
-```
 ### Unstage all changes that have been added to the staging area
-To undo the most recent add, but not committed, files/folders:
+To undo the most recently added, but not committed, changes to files/folders:
 ```bash
 git reset .
@@ -259,25 +281,31 @@ To undo the most recent commit, type:
 git reset HEAD~1
 ```
-This leaves the files and folders unstaged in your local repository.
+This leaves the changed files and folders unstaged in your local repository.
 CAUTION: **Warning:**
-A Git commit is mostly irreversible, particularly if you already pushed it to the remote repository. Although you can undo a commit, the best option is to avoid the situation altogether.
+A Git commit should not usually be reverse, particularly if you already pushed it
+to the remote repository. Although you can undo a commit, the best option is to avoid
+the situation altogether by working carefully.
-### Merge created branch with master branch
+### Merge a branch with master branch
-You need to be in the created branch.
+When you are ready to make all the changes in a branch a permanent addition to
+the master branch, you `merge` the two together:
 ```bash
-git checkout NAME-OF-BRANCH
+git checkout <name-of-branch>
 git merge master
 ```
-### Merge master branch with created branch
+<!-- ## Troubleshooting
-You need to be in the master branch.
+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.
-```bash
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
-git checkout master
+If you have none to add when creating a doc, leave this section in place
-git merge NAME-OF-BRANCH
+but commented out to help encourage others to add to it in the future. -->
-```