Merge branch 'docs-git-review-intro' into 'master'

Docs: Revamp Git intro

See merge request gitlab-org/gitlab!30230

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.
 

doc/gitlab-basics/start-using-git.md

 ---
 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'll also need to open a [command shell](#command-shell) and have
+[Git installed](#install-git) in your computer.
 
-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).
+### Command shell
 
-After you are finished installing Git, open a new shell and type `git --version` again
-to verify that it was correctly installed.
+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:
 
-## Add your Git username and set your email
+- 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/).
 
-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.
+### Install Git
 
-In your shell, type the following command to add your username:
+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.

doc/topics/git/how_to_install_git/index.md

@@ -6,7 +6,7 @@ article_type: user guide
 date: 2017-05-15
 description: 'This article describes how to install Git on macOS, Ubuntu Linux and Windows.'
 type: howto
-last_updated: 2019-05-31
+last_updated: 2020-04-22
 ---
 
 # Installing Git
@@ -32,34 +32,47 @@ use one of the aforementioned methods.
 
 ### Installing Xcode
 
-Xcode is needed by Homebrew to build dependencies.
-You can install [XCode](https://developer.apple.com/xcode/)
-through the macOS App Store.
+To build dependencies, Homebrew needs the XCode Command Line Tools. Install
+it by running in your terminal:
+
+```shell
+xcode-select --install
+```
+
+Click **Install** to download and install it. Alternativelly, you can install
+the entire [XCode](https://developer.apple.com/xcode/) package through the
+macOS App Store.
 
 ### Installing Homebrew
 
-Once Xcode is installed browse to the [Homebrew website](https://brew.sh/index.html)
+With Xcode installed, browse to the [Homebrew website](https://brew.sh/index.html)
 for the official Homebrew installation instructions.
 
 ### Installing Git via Homebrew
 
-With Homebrew installed you are now ready to install Git.
-Open a Terminal and enter in the following command:
+With Homebrew installed, you are now ready to install Git.
+Open a terminal and enter the following command:
 
 ```shell
 brew install git
 ```
 
-Congratulations you should now have Git installed via Homebrew.
+Congratulations! You should now have Git installed via Homebrew.
+
+To verify that Git works on your system, run:
+
+```shell
+git --version
+```
 
-Next read our article on [adding an SSH key to GitLab](../../../ssh/README.md).
+Next, read our article on [adding an SSH key to GitLab](../../../ssh/README.md).
 
 ## Install Git on Ubuntu Linux
 
 On Ubuntu and other Linux operating systems
-it is recommended to use the built in package manager to install Git.
+it is recommended to use the built-in package manager to install Git.
 
-Open a Terminal and enter in the following commands
+Open a terminal and enter the following commands
 to install the latest Git from the official Git maintained package archives:
 
 ```shell
@@ -68,15 +81,21 @@ sudo apt-get update
 sudo apt-get install git
 ```
 
-Congratulations you should now have Git installed via the Ubuntu package manager.
+Congratulations! You should now have Git installed via the Ubuntu package manager.
+
+To verify that Git works on your system, run:
+
+```shell
+git --version
+```
 
-Next read our article on [adding an SSH key to GitLab](../../../ssh/README.md).
+Next, read our article on [adding an SSH key to GitLab](../../../ssh/README.md).
 
 ## Installing Git on Windows from the Git website
 
-Browse to the [Git website](https://git-scm.com/) and download and install Git for Windows.
+Open the [Git website](https://git-scm.com/) and download and install Git for Windows.
 
-Next read our article on [adding an SSH key to GitLab](../../../ssh/README.md).
+Next, read our article on [adding an SSH key to GitLab](../../../ssh/README.md).
 
 <!-- ## Troubleshooting