Commit faaf9c70 authored by Kati Paizee's avatar Kati Paizee Committed by Suzanne Selhorn

Create tutorial for how Git works

parent e6a0f5b9
---
stage: none
group: unassigned
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Make your first Git commit
This tutorial is going to teach you a little bit about how Git works, and walk
you through the steps of creating your own project and editing a file.
When you're done, you'll have a project where you can practice using Git.
## What you need
Before you begin:
- [Install Git on your local machine](../topics/git/how_to_install_git/index.md).
- Ensure you can sign in to an instance of GitLab. If your organization doesn't
have GitLab, create an account on GitLab.com.
- [Create SSH keys and add them to GitLab](../ssh/index.md). SSH keys are how you
securely communicate between your computer and GitLab.
## What is Git?
Before we jump into steps, let's go over some basic Git concepts.
Git is a version control system. It's used to track changes to files.
You store files, like code or documents, in a Git *repository*. When you want to edit the files, you
*clone* the repository to your computer, make the changes, and *push* your changes
back to the repository. In GitLab, a Git repository is located in
a *project*.
Each time you push a change, Git records it as a unique *commit*. These commits make up
the history of when and how a file changed, and who changed it.
```mermaid
graph LR
subgraph Repository commit history
A(Author: Alex<br>Date: 3 Jan at 1PM<br>Commit message: Added sales figures for January<br> Commit ID: 123abc12) ---> B
B(Author: Sam<br>Date: 4 Jan at 10AM<br>Commit message: Removed outdated marketing information<br> Commit ID: aabb1122) ---> C
C(Author: Zhang<br>Date: 5 Jan at 3PM<br>Commit message: Added a new 'Invoices' file<br> Commit ID: ddee4455)
end
```
When you work in a Git repository, you work in *branches*. By default, the contents
of a repository are in a default branch. To make changes, you:
1. Create your own branch, which is a snapshot of the default branch at the time
you create it.
1. Make changes and push them to your branch. Each push creates a commit.
1. When you're ready, *merge* your branch into the default branch.
```mermaid
flowchart LR
subgraph Default branch
A[Commit] --> B[Commit] --> C[Commit] --> D[Commit]
end
subgraph My branch
B --1. Create my branch--> E(Commit)
E --2. Add my commit--> F(Commit)
F --2. Add my commit--> G(Commit)
G --3. Merge my branch to default--> D
end
```
If this all feels a bit overwhelming, hang in there. You're about to see these concepts in action.
## Steps
Here's an overview of what we're going to do:
1. [Create a sample project](#create-a-sample-project).
1. [Clone the repository](#clone-the-repository).
1. [Create a branch and make your changes](#create-a-branch-and-make-changes).
1. [Commit and push your changes](#commit-and-push-your-changes).
1. [Merge your changes](#merge-your-changes).
1. [View your changes in GitLab](#view-your-changes-in-gitlab).
### Create a sample project
To start, create a sample project in GitLab.
1. In GitLab, on the top bar, select **Menu > Projects > Create new project**.
1. Select **Create blank project**.
1. For **Project name**, enter `My sample project`. The project slug is generated for you.
This slug is the URL you can use to access the project after it's created.
1. Ensure **Initialize repository with a README** is selected.
How you complete the other fields is up to you.
1. Select **Create project**.
### Clone the repository
Now you can clone the repository in your project. *Cloning* a repository means you're creating
a copy on your computer, or wherever you want to store and work with the files.
1. On your project page, select **Clone**. Copy the URL for **Clone with SSH**.
![Clone a project with SSH](img/clone_project_v14_9.png)
1. Open a terminal on your computer and go to the directory
where you want to clone the files.
1. Enter `git clone` and paste the URL:
```shell
git clone git@gitlab.com:gitlab-example/my-sample-project.git
```
1. Go to the directory:
```shell
cd my-sample-project
```
1. By default, you've cloned the default branch for the repository. Usually this
branch is `main`. To be sure, get the name of the default branch:
```shell
git branch
```
The branch you're on is marked with an asterisk.
Press `Q` on your keyboard to return to the main terminal
window.
### Create a branch and make changes
Now that you have a copy of the repository, create your own branch so you can
work on your changes independently.
1. Create a new branch called `example-tutorial-branch`.
```shell
git checkout -b example-tutorial-branch
```
1. In a text editor like Visual Studio Code, Sublime, `vi`, or any other editor,
open the README.md file and add this text:
```plaintext
Hello world! I'm using Git!
```
1. Save the file.
1. Git keeps track of changed files. To confirm which files have changed, get
the status.
```shell
git status
```
You should get output similar to the following:
```shell
On branch example-tutorial-branch
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: README.md
no changes added to commit (use "git add" and/or "git commit -a")
```
### Commit and push your changes
You've made changes to a file in your repository. Now it's time to record
those changes by making your first commit.
1. Add the `README.md` file to the *staging* area. The staging area is where you
put files before you commit them.
```shell
git add README.md
```
1. Confirm the file is staged:
```shell
git status
```
You should get output similar to the following, and the filename should be in
green text.
```shell
On branch example-tutorial-branch
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
modified: README.md
```
1. Now commit the staged file, and include a message
that describes the change you made. Make sure you surround the message in double
quotes (").
```shell
git commit -m "I added text to the README file"
```
1. The change has been committed to your branch, but your branch and its commits
are still only available on your computer. No one else has access to them yet.
Push your branch to GitLab:
```shell
git push origin example-tutorial-branch
```
Your branch is now available on GitLab and visible to other users in your project.
![Branches dropdown list](img/branches_dropdown_v14_10.png)
### Merge your changes
Now you're ready to merge the changes from your `example-tutorial-branch` branch
to the default branch (`main`).
1. Check out the default branch for your repository.
```shell
git checkout main
```
1. Merge your branch into the default branch.
```shell
git merge example-tutorial-branch
```
1. Push the changes.
```shell
git push
```
NOTE:
For this tutorial, you merge your branch directly to the default branch for your
repository. In GitLab, you typically use a [merge request](../user/project/merge_requests/)
to merge your branch.
### View your changes in GitLab
You did it! You updated the `README.md` file in your branch, and you merged those changes
into the `main` branch.
Let's look in the UI and confirm it.
1. In your project, scroll down and view the `README.md` file.
Your changes should be visible.
1. Above the list of files, select **History**.
Your commit and commit message should display.
Now you can change back to your personal branch (`git checkout example-tutorial-branch`)
and continue updating or even creating files. Type `git status` to view the status
of your changes and commit with abandon.
Don't worry if you mess things up. Everything in Git can be reverted, and if you
find you can't recover, you can always create a new branch and start again.
Nice work.
## Find more Git learning resources
- Get a complete introduction to Git in the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Git for GitLab](https://www.youtube.com/watch?v=4lxvVj7wlZw) beginner's course (1h 33m).
- Find other tutorials about Git and GitLab on the [tutorials page](index.md).
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