diff options
Diffstat (limited to 'doc/gitlab-basics/start-using-git.md')
| -rw-r--r-- | doc/gitlab-basics/start-using-git.md | 137 |
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 |