Commit fe81a170 authored by Marcin Sedlak-Jakubowski's avatar Marcin Sedlak-Jakubowski

Merge branch 'docs-git-start-guide-cloning' into 'master'

Docs: revamp Git clone

See merge request gitlab-org/gitlab!30728
parents a7974822 b35d8183
...@@ -104,68 +104,134 @@ repository. ...@@ -104,68 +104,134 @@ repository.
You can read more on how Git manages configurations in the 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. [Git Config](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) documentation.
## Basic Git commands ## Git authentication methods
Start using Git via the command line with the most basic commands as described below. To connect your computer with GitLab, you need to add your credentials to identify yourself.
You have two options:
### Initialize a local directory for Git version control - 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 won't ask your credentials every time you pull, push,
and clone.
If you have an existing local directory that you want to *initialize* for version To start the authentication process, we'll [clone](#clone-a-repository) an existing repository
control, use the `init` command to instruct Git to begin tracking the directory: to our computer:
```shell - If you want to use **SSH** to authenticate, follow the instructions on the [SSH documentation](../ssh/README.md)
git init to set it up before cloning.
``` - If you want to use **HTTPS**, GitLab will request your user name and password:
- 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.
Create one before cloning.
- If you don't have 2FA enabled, use your account's password.
This creates a `.git` directory that contains the Git configuration files. NOTE: **Note:**
Authenticating via SSH is GitLab's 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).
Once the directory has been initialized, you can [add a remote repository](#add-a-remote-repository) ## Git terminology
and [send changes to GitLab.com](#send-changes-to-gitlabcom). You will also need to
[create a new project in GitLab](../gitlab-basics/create-project.md#push-to-create-a-new-project)
for your Git repository.
### Clone a repository If you're familiar with the Git terminology, you may want to jump directly
into the [basic commands](#basic-git-commands).
### Namespace
A **namespace** is either a **user name** or a **group name**.
For example, suppose Jo is a GitLab.com user and they chose their user name as
`jo`. You can see Jo's profile at `https://gitlab.com/jo`. `jo` is a namespace.
Jo also created a group in GitLab, and chose the path `test-group` for their
group. The group can be accessed under `https://gitlab.com/test-group`. `test-group` is a namespace.
### Repository
Your files in GitLab live in a **repository**, similar to how you have them in a folder or
directory in your computer. **Remote** repository refers to the files in
GitLab and the copy in your computer is called **local** copy.
A **project** in GitLab is what holds a repository, which holds your files.
Often, the word "repository" is shortened to "repo".
### Fork
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'll create a copy of the project into your own
namespace to have read and write permissions to modify the project files
and settings.
For example, if you fork this project, <https://gitlab.com/gitlab-tests/sample-project/> into your namespace, you'll create your own copy of the repository in your namespace (`https://gitlab.com/your-namespace/sample-project/`). From there, you can clone it into your computer,
work on its files, and (optionally) submit proposed changes back to the
original repository if you'd like.
### Download vs clone
To start working locally on an existing remote repository, clone it with the command To create a copy of a remote repository files on your computer, you can either
`git clone <repository path>`. By cloning a repository, you'll download a copy of its **download** or **clone** it. If you download it, you cannot sync it with the
files to your local computer, automatically preserving the Git connection with the remote repository on GitLab.
remote repository.
You can either clone it via [HTTPS](#clone-via-https) or [SSH](#clone-via-ssh). If you chose to On the other hand, by cloning a repository, you'll download a copy of its
clone it via HTTPS, you'll have to enter your credentials every time you pull and push. files to your local computer, but preserve the Git connection with the remote
You can read more about credential storage in the repository, so that you can work on the its files on your computer and then
[Git Credentials documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). upload the changes to GitLab.
With [SSH](../ssh/README.md), you enter your credentials only once.
### Pull and push
After you saved a local copy of a repository and modified its files on your computer, you can upload the
changes to GitLab. This is referred to as **pushing** to GitLab, as this is achieved by the command
[`git push`](#send-changes-to-gitlabcom).
When the remote repository changes, your local copy will be behind it. You can update it with the new
changes in the remote repo.
This is referred to as **pulling** from GitLab, as this is achieved by the command
[`git pull`](#download-the-latest-changes-in-the-project).
## Basic Git commands
For the purposes of this guide, we will use this example project on GitLab.com:
[https://gitlab.com/gitlab-tests/sample-project/](https://gitlab.com/gitlab-tests/sample-project/).
To use it, log into GitLab.com and fork the example project into your
namespace to have your own copy to playing with. Your sample
project will be available under `https://gitlab.com/<your-namespace>/sample-project/`.
You can also choose any other project to follow this guide. Then, replace the
example URLs with your own project's.
If you want to start by copying an existing GitLab repository onto your
computer, see how to [clone a repository](#clone-a-repository). On the other
hand, if you want to start by uploading an existing folder from your computer
to GitLab, see how to [convert a local folder into a Git repository](#convert-a-local-directory-into-a-repository).
### Clone a repository
To start working locally on an existing remote repository, clone it with the
command `git clone <repository path>`. You can either clone it via [HTTPS](#clone-via-https) or [SSH](#clone-via-ssh), according to your preferred [authentication method](#git-authentication-methods).
You can find both paths (HTTPS and SSH) by navigating to your project's landing page 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 and clicking **Clone**. GitLab will prompt you with both paths, from which you can copy
and paste in your command line. and paste in your command line.
As an example, consider this repository path: For example, considering our [sample project](https://gitlab.com/gitlab-tests/sample-project/):
- HTTPS: `https://gitlab.com/gitlab-org/gitlab.git` - To clone through HTTPS, use `https://gitlab.com/gitlab-tests/sample-project.git`.
- SSH: `git@gitlab.com:gitlab-org/gitlab.git` - To clone through SSH, use `git@gitlab.com:gitlab-tests/sample-project.git`.
To get started, open a terminal window in the directory you wish to clone the To get started, open a terminal window in the directory you wish to add the
repository files into, and run one of the `git clone` commands as described below. 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 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. name and preserve the connection with the remote repository.
You can then navigate to the new directory with `cd sample-project` and start working on it
locally.
#### Clone via HTTPS #### Clone via HTTPS
To clone `https://gitlab.com/gitlab-org/gitlab.git` via HTTPS: To clone `https://gitlab.com/gitlab-tests/sample-project/` via HTTPS:
```shell ```shell
git clone https://gitlab.com/gitlab-org/gitlab.git git clone https://gitlab.com/gitlab-tests/sample-project.git
``` ```
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:** TIP: **Troubleshooting:**
On Windows, if you entered incorrect passwords multiple times and GitLab is responding `Access denied`, 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: you may have to add your namespace (user name or group name) to clone through HTTPS:
...@@ -179,16 +245,44 @@ To clone `git@gitlab.com:gitlab-org/gitlab.git` via SSH: ...@@ -179,16 +245,44 @@ To clone `git@gitlab.com:gitlab-org/gitlab.git` via SSH:
git clone git@gitlab.com:gitlab-org/gitlab.git git clone git@gitlab.com:gitlab-org/gitlab.git
``` ```
### Switch to the master branch ### Convert a local directory into a repository
You are always in a branch when working with Git. The main branch is the master When you have your files in a local folder and want to convert it into
branch, but you can use the same command to switch to a different branch by a repository, you'll need to _initialize_ the folder through the `git init`
changing `master` to the branch name. command. This will instruct Git to begin to track that directory as a
repository. To do so, open the terminal on the directory you'd like to convert
and run:
```shell ```shell
git checkout master git init
``` ```
This command creates a `.git` folder in your directory that contains Git
records and configuration files. We advise against editing these files
directly.
Then, on the next step, add the [path to your remote repository](#add-a-remote-repository)
so that Git can upload your files into the correct project.
#### Add a remote repository
By "adding a remote repository" to your local directory you'll tell Git that
the path to that specific project in GitLab corresponds to that specific
folder you have in your computer. This way, your local folder will be
identified by Git as the local content for that specific remote project.
To add a remote repository to your local copy:
1. In GitLab, [create a new project](../gitlab-basics/create-project.md#push-to-create-a-new-project) to hold your files.
1. Visit this project's homepage, scroll down to **Push an existing folder**, and copy the command that starts with `git remote add`.
1. On your computer, open the terminal in the directory you've initialized, paste the command you copied, and press <kbd>enter</kbd>:
```shell
git remote add origin <git@gitlab.com:username/projectpath.git
```
After you've done that, you can [stage your files](#add-and-commit-local-changes) and [upload them to GitLab](#send-changes-to-gitlabcom).
### Download the latest changes in the project ### Download the latest changes in the project
To work on an up-to-date copy of the project (it is important to do this every time To work on an up-to-date copy of the project (it is important to do this every time
...@@ -219,16 +313,16 @@ git remote -v ...@@ -219,16 +313,16 @@ git remote -v
The `-v` flag stands for verbose. The `-v` flag stands for verbose.
### Add a remote repository ## Branching
To add a link to a remote repository: If you want to add code to a project but you're not sure if it will work properly, or you're
collaborating on the project with others, and don't want your work to get mixed up, it's a good idea
to work on a different **branch**.
```shell When you create a branch in a Git repository, you make a copy of its files at the time of branching. You're free
git remote add <source-name> <repository-path> to do whatever you want with the code in your branch without impacting the main branch or other branches. And when
``` you're ready to bring your changes to the main codebase, you can merge your branch into the main one
used in your project (such as `master`).
You'll use this source name every time you [push changes to GitLab.com](#send-changes-to-gitlabcom),
so use something easy to remember and type.
### Create a branch ### Create a branch
...@@ -240,6 +334,16 @@ use a hyphen or underscore): ...@@ -240,6 +334,16 @@ use a hyphen or underscore):
git checkout -b <name-of-branch> git checkout -b <name-of-branch>
``` ```
### Switch to the master branch
You are always in a branch when working with Git. The main branch is the master
branch, but you can use the same command to switch to a different branch by
changing `master` to the branch name.
```shell
git checkout master
```
### Work on an existing branch ### Work on an existing branch
To switch to an existing branch, so you can work on it: To switch to an existing branch, so you can work on it:
...@@ -279,7 +383,7 @@ git add <file-name OR folder-name> ...@@ -279,7 +383,7 @@ git add <file-name OR folder-name>
git commit -m "COMMENT TO DESCRIBE THE INTENTION OF THE COMMIT" git commit -m "COMMENT TO DESCRIBE THE INTENTION OF THE COMMIT"
``` ```
### Add all changes to commit #### Add all changes to commit
To add and commit (save) all local changes quickly: To add and commit (save) all local changes quickly:
...@@ -293,10 +397,6 @@ The `.` character means _all file changes in the current directory and all subdi ...@@ -293,10 +397,6 @@ The `.` character means _all file changes in the current directory and all subdi
### Send changes to GitLab.com ### Send changes to GitLab.com
NOTE: **Note:**
To create a merge request from a fork to an upstream repository, see the
[forking workflow](../user/project/repository/forking_workflow.md)
To push all local commits (saved changes) to the remote repository: To push all local commits (saved changes) to the remote repository:
```shell ```shell
...@@ -309,6 +409,10 @@ For example, to push your local commits to the _`master`_ branch of the _`origin ...@@ -309,6 +409,10 @@ For example, to push your local commits to the _`master`_ branch of the _`origin
git push origin master git push origin master
``` ```
NOTE: **Note:**
To create a merge request from a fork to an upstream repository, see the
[forking workflow](../user/project/repository/forking_workflow.md).
### Delete all changes in the branch ### Delete all changes in the branch
To delete all local changes in the branch that have not been added to the staging To delete all local changes in the branch that have not been added to the staging
...@@ -353,7 +457,7 @@ git checkout <name-of-branch> ...@@ -353,7 +457,7 @@ git checkout <name-of-branch>
git merge master git merge master
``` ```
### Synchronize changes in a forked repository with the upstream ## Synchronize changes in a forked repository with the upstream
[Forking a repository](../user/project/repository/forking_workflow.md) lets you create [Forking a repository](../user/project/repository/forking_workflow.md) lets you create
a copy of a repository in your namespace. Changes made to your copy of the repository a copy of a repository in your namespace. Changes made to your copy of the repository
......
...@@ -26,8 +26,9 @@ The following resources will help you get started with Git: ...@@ -26,8 +26,9 @@ The following resources will help you get started with Git:
- [Git Basics](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics) - [Git Basics](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics)
- [Git on the Server - GitLab](https://git-scm.com/book/en/v2/Git-on-the-Server-GitLab) - [Git on the Server - GitLab](https://git-scm.com/book/en/v2/Git-on-the-Server-GitLab)
- [How to install Git](how_to_install_git/index.md) - [How to install Git](how_to_install_git/index.md)
- [Git terminology](../../gitlab-basics/start-using-git.md#git-terminology)
- [Start using Git on the command line](../../gitlab-basics/start-using-git.md) - [Start using Git on the command line](../../gitlab-basics/start-using-git.md)
- [Command line file editing basic commands](../../gitlab-basics/command-line-commands.md) - [Edit files through the command line](../../gitlab-basics/command-line-commands.md)
- [GitLab Git Cheat Sheet (download)](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) - [GitLab Git Cheat Sheet (download)](https://about.gitlab.com/images/press/git-cheat-sheet.pdf)
- Commits: - Commits:
- [Revert a commit](../../user/project/merge_requests/revert_changes.md#reverting-a-commit) - [Revert a commit](../../user/project/merge_requests/revert_changes.md#reverting-a-commit)
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment