summaryrefslogtreecommitdiff
path: root/doc/gitlab-basics/start-using-git.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/gitlab-basics/start-using-git.md')
-rw-r--r--doc/gitlab-basics/start-using-git.md137
1 files changed, 87 insertions, 50 deletions
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