Add latest changes from gitlab-org/gitlab@13-0-stable-ee

4 files changed, 90 insertions, 53 deletions

diff --git a/doc/gitlab-basics/command-line-commands.md b/doc/gitlab-basics/command-line-commands.md
index fed91046c32..b9426ec0849 100644
--- a/doc/gitlab-basics/command-line-commands.md
+++ b/doc/gitlab-basics/command-line-commands.md
@@ -2,7 +2,7 @@
 type: howto, reference
 ---
 
-# Command Line basic commands
+# Edit files through the command line
 
 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
diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md
index 1febe8337bc..152fb24699e 100644
--- a/doc/gitlab-basics/create-project.md
+++ b/doc/gitlab-basics/create-project.md
@@ -145,7 +145,7 @@ git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project
 Once the push finishes successfully, a remote message will indicate
 the command to set the remote and the URL to the new project:
 
-```text
+```plaintext
 remote:
 remote: The private project namespace/nonexistent-project was created.
 remote:
diff --git a/doc/gitlab-basics/create-your-ssh-keys.md b/doc/gitlab-basics/create-your-ssh-keys.md
index 9b3431a5a42..248f39b842c 100644
--- a/doc/gitlab-basics/create-your-ssh-keys.md
+++ b/doc/gitlab-basics/create-your-ssh-keys.md
@@ -11,7 +11,7 @@ In order to use SSH, you will need to:
 
 ## Creating your SSH key pair
 
-1. Go to your [command line](start-using-git.md#open-a-shell).
+1. Go to your [command line](start-using-git.md#command-shell).
 1. Follow the [instructions](../ssh/README.md#generating-a-new-ssh-key-pair) to generate
    your SSH key pair.
 
diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md
index 9a05c7fff14..9ebcf258ee9 100644
--- a/doc/gitlab-basics/start-using-git.md
+++ b/doc/gitlab-basics/start-using-git.md
@@ -1,81 +1,104 @@
 ---
 type: howto, tutorial
+description: "Introduction to using Git through the command line."
+last_updated: 2020-04-22
 ---
 
 # Start using Git on the command line
 
-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.
+[Git](https://git-scm.com/) is an open-source distributed version control system designed to
+handle everything from small to very large projects with speed and efficiency. GitLab is built
+on top of Git.
 
-## Open a shell
+While GitLab has a powerful user interface from which you can do a great amount of Git operations
+directly in the browser, you’ll eventually need to use Git through the command line for advanced
+tasks.
 
-Depending on your operating system, you will need to use a shell of your preference.
-Here are some suggestions:
+For example, if you need to fix complex merge conflicts, rebase branches,
+merge manually, or undo and roll back commits, you'll need to use Git from
+the command line and then push your changes to the remote server.
 
-- [Terminal](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) on macOS
-- [GitBash](https://msysgit.github.io) on Windows
-- [Linux Terminal](https://www.howtogeek.com/140679/beginner-geek-how-to-start-using-the-linux-terminal/) on Linux
+This guide will help you get started with Git through the command line and can be your reference
+for Git commands in the future. If you're only looking for a quick reference of Git commands, you
+can download GitLab's [Git Cheat Sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf).
 
-## Check if Git has already been installed
+TIP: **Tip:**
+To help you visualize what you're doing locally, there are
+[Git GUI apps](https://git-scm.com/download/gui/) you can install.
 
-Git is usually preinstalled on Mac and Linux, so run the following command:
+## Requirements
 
-```shell
-git --version
-```
+You don't need a GitLab account to use Git locally, but for the purpose of this guide we
+recommend registering and signing into your account before starting. Some commands need a
+connection between the files in your computer and their version on a remote server.
 
-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'll also need to open a [command shell](#command-shell) and have
+[Git installed](#install-git) in your computer.
 
-After you are finished installing Git, open a new shell and type `git --version` again
-to verify that it was correctly installed.
+### Command shell
 
-## Add your Git username and set your email
+To execute Git commands in your computer, you'll need to open a command shell (also known as command
+prompt, terminal, and command line) of your preference. Here are some suggestions:
 
-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.
+- For macOS users:
+  - Built-in: [Terminal](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line). Press <kbd>⌘ command</kbd> + <kbd>space</kbd> and type "terminal" to find it.
+  - [iTerm2](https://www.iterm2.com/), which you can integrate with [zsh](https://git-scm.com/book/id/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Zsh) and [oh my zsh](https://ohmyz.sh/) for color highlighting, among other handy features for Git users.
+- For Windows users:
+  - Built-in: **cmd**. Click the search icon on the bottom navbar on Windows and type "cmd" to find it.
+  - [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-windows-powershell?view=powershell-7): a Windows "powered up" shell, from which you can execute a greater number of commands.
+  - Git Bash: it comes built into [Git for Windows](https://gitforwindows.org/).
+- For Linux users:
+  - Built-in: [Linux Terminal](https://www.howtogeek.com/140679/beginner-geek-how-to-start-using-the-linux-terminal/).
 
-In your shell, type the following command to add your username:
+### Install Git
+
+Open a command shell and run the following command to check if Git is already installed in your
+computer:
 
 ```shell
-git config --global user.name "YOUR_USERNAME"
+git --version
 ```
 
-Then verify that you have the correct username:
+If you have Git installed, the output will be:
 
 ```shell
-git config --global user.name
+git version X.Y.Z
 ```
 
-To set your email address, type the following command:
+If your computer doesn't recognize `git` as a command, you'll need to [install Git](../topics/git/how_to_install_git/index.md).
+After that, run `git --version` again to verify whether it was correctly installed.
 
-```shell
-git config --global user.email "your_email_address@example.com"
-```
+## Configure Git
+
+To start using Git from your computer, you'll need to enter your credentials (user name and email)
+to identify you as the author of your work. The user name and email should match the ones you're
+using on GitLab.
 
-To verify that you entered your email correctly, type:
+In your shell, add your user name:
 
 ```shell
-git config --global user.email
+git config --global user.name "your_username"
 ```
 
-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 or repositories, you can run the command without the `--global` option
-when you’re in that project, and that will default to `--local`. You can read more
-on how Git manages configurations in the [Git Config](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) documentation.
+And your email address:
 
-## Check your information
+```shell
+git config --global user.email "your_email_address@example.com"
+```
 
-To view the information that you entered, along with other global options, type:
+To check the configuration, run:
 
 ```shell
 git config --global --list
 ```
 
+The `--global` option tells Git to always use this information for anything you do on your system.
+If you omit `--global` or use `--local`, the configuration will be applied only to the current
+repository.
+
+You can read more on how Git manages configurations in the
+[Git Config](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) documentation.
+
 ## Basic Git commands
 
 Start using Git via the command line with the most basic commands as described below.
@@ -103,11 +126,11 @@ To start working locally on an existing remote repository, clone it with the com
 files to your local computer, automatically preserving the Git connection with the
 remote repository.
 
-You can either clone it via HTTPS or [SSH](../ssh/README.md). If you chose to clone
-it via HTTPS, you'll have to enter your credentials every time you pull and push.
+You can either clone it via [HTTPS](#clone-via-https) or [SSH](#clone-via-ssh). If you chose to
+clone it via HTTPS, you'll have to enter your credentials every time you pull and push.
 You can read more about credential storage in the
 [Git Credentials documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage).
-With SSH, you enter your credentials only once.
+With [SSH](../ssh/README.md), you enter your credentials only once.
 
 You can find both paths (HTTPS and SSH) by navigating to your project's landing page
 and clicking **Clone**. GitLab will prompt you with both paths, from which you can copy
@@ -119,24 +142,38 @@ As an example, consider this repository path:
 - SSH: `git@gitlab.com:gitlab-org/gitlab.git`
 
 To get started, open a terminal window in the directory you wish to clone the
-repository files into, and run one of the following commands.
+repository files into, and run one of the `git clone` commands as described below.
+
+Both commands will download a copy of the files in a folder named after the project's
+name. You can then navigate to the new directory and start working on it locally.
+
+#### Clone via HTTPS
 
-Clone via HTTPS:
+To clone `https://gitlab.com/gitlab-org/gitlab.git` via HTTPS:
 
 ```shell
 git clone https://gitlab.com/gitlab-org/gitlab.git
 ```
 
-Clone via SSH:
+You'll have to add your password every time you clone through HTTPS. If you have 2FA enabled
+for your account, you'll have to use a [Personal Access Token](../user/profile/personal_access_tokens.md)
+with **read_repository** or **write_repository** permissions instead of your account's password.
+
+If you don't have 2FA enabled, use your account's password.
+
+TIP: **Troubleshooting:**
+On Windows, if you entered incorrect passwords multiple times and GitLab is responding `Access denied`,
+you may have to add your namespace (user name or group name) to clone through HTTPS:
+`git clone https://namespace@gitlab.com/gitlab-org/gitlab.git`.
+
+#### Clone via SSH
+
+To clone `git@gitlab.com:gitlab-org/gitlab.git` via SSH:
 
 ```shell
 git clone git@gitlab.com:gitlab-org/gitlab.git
 ```
 
-Both commands will download a copy of the files in a folder named after the project's
-name. You can then navigate to the directory and start working
-on it locally.
-
 ### Switch to the master branch
 
 You are always in a branch when working with Git. The main branch is the master