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 on your computer and their version on a remote server.
To start using GitLab with Git, complete the following tasks:
You must also open a [terminal](#open-a-terminal) and have
[Git installed](#install-git) on your computer.
- Create and sign in to a GitLab account.
-[Open a terminal](#open-a-terminal).
-[Install Git](#install-git) on your computer.
-[Configure Git](#configure-git).
-[Choose a repository](#choose-a-repository).
### Open a terminal
To execute Git commands on your computer, you must open a terminal (also known as command
prompt, command shell, and command line) of your preference. Here are some suggestions:
prompt, command shell, and command line). Here are some options:
- 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://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.
- 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`.
-[iTerm2](https://iterm2.com/). You can integrate it 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 and other advanced features.
- For Windows users:
- Built-in: `cmd`. Click the search icon on the bottom navigation bar on Windows and type `cmd` to find it.
-[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/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/).
- Built-in command line. On the Windows taskbar, select the search icon and type `cmd`.
To connect your computer with GitLab, you need to add your credentials to identify yourself.
You have two options:
- Authenticate on a project-by-project basis through HTTPS, and enter your credentials every time
you perform an operation between your computer and GitLab.
- Authenticate through SSH once and GitLab no longer requests your credentials every time you
perform an operation between your computer and GitLab.
To start the authentication process, we'll [clone](#clone-a-repository) an existing repository
to our computer:
- If you want to use **SSH** to authenticate, follow the instructions on the [SSH documentation](../ssh/README.md)
to set it up before cloning.
- If you want to use **HTTPS**, GitLab requests your username and password:
- If you have 2FA enabled for your account, you must 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.
NOTE:
Authenticating through SSH is the GitLab recommended method. You can read more about credential storage
in the [Git Credentials documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage).
## Git terminology
If you're familiar with Git terminology, you may want to jump directly
into [setting up a repository](#set-up-a-repository).
### Repository
Your files in GitLab live in a **repository**, similar to how you have them in a folder or
directory on your computer.
### Choose a repository
-**Remote** repository refers to the files in GitLab.
- A **local** copy refers to the files on your computer.
Before you begin, choose the repository you want to work in. You can use any project you have permission to
access on GitLab.com or any other GitLab instance.
<!-- vale gitlab.Spelling = NO -->
<!-- vale gitlab.SubstitutionWarning = NO -->
Often, the word "repository" is shortened to "repo".
<!-- vale gitlab.Spelling = YES -->
<!-- vale gitlab.SubstitutionWarning = YES -->
To use the repository in the examples on this page:
A **project** in GitLab is what holds a repository.
1. Go to [https://gitlab.com/gitlab-tests/sample-project/](https://gitlab.com/gitlab-tests/sample-project/).
1. In the top right, select **Fork**.
1. Choose a namespace for your fork.
### Fork
The project becomes available at `https://gitlab.com/<your-namespace>/sample-project/`.
When you want to copy someone else's repository, you [**fork**](../user/project/repository/forking_workflow.md#creating-a-fork)
the project. By forking it, you create a copy of the project into your own
[namespace](../user/group/#namespaces) to have read and write permissions to modify the project files
and settings.
You can [fork](../user/project/repository/forking_workflow.md#creating-a-fork) any project you have access to.
For example, if you fork this project, <https://gitlab.com/gitlab-tests/sample-project/> into your namespace,
you create your own copy of the repository in your namespace (`https://gitlab.com/your-namespace/sample-project/`).
From there, you can clone the repository, work on the files, and (optionally) submit proposed changes back to the
original repository.
## Clone a repository
### Difference between download and clone
When you clone a repository, the files from the remote repository are downloaded to your computer,
and a connection is created.
To create a copy of a remote repository's files on your computer, you can either
**download** or **clone** the repository. If you download it, you cannot sync the repository with the
remote version on GitLab.
This connection requires you to add credentials. You can either use SSH or HTTPS. SSH is recommended.
[Cloning](#clone-a-repository) a repository is the same as downloading, except it preserves the Git connection
with the remote repository. This allows you to modify the files locally and
upload the changes to the remote repository on GitLab.
### Clone with SSH
### Pull and push
Clone with SSH when you want to authenticate only one time.
After you save a local copy of a repository and modify the files on your computer, you can upload the
changes to GitLab. This is referred to as **pushing** to the remote, as this is achieved by the command
[`git push`](#send-changes-to-gitlabcom).
1. Authenticate with GitLab by following the instructions in the [SSH documentation](../ssh/README.md).
1. Go to your project's landing page and select **Clone**. Copy the URL for **Clone with SSH**.
1. Open a terminal and go to the directory where you want to clone the files. Git automatically creates a folder with the repository name and downloads the files there.
1. Run this command:
When the remote repository changes, your local copy is behind. You can update your local copy with the new
changes in the remote repository.
This is referred to as **pulling** from the remote, as this is achieved by the command
Remember to replace the example URLs with the relevant path of your project.
To get started, choose one of the following:
- Use the example project by signing into GitLab.com and [forking](../user/project/repository/forking_workflow.md#creating-a-fork)
it into your namespace to make it available under `https://gitlab.com/<your-namespace>/sample-project/`.
- Copy an existing GitLab repository onto your computer by [cloning a repository](#clone-a-repository).
- Upload an existing folder from your computer to GitLab by [converting a local folder into a Git repository](#convert-a-local-directory-into-a-repository).
