# Git(Lab) Basics

## Some definitions

### What's a repository ?

A repository is a hierarchy of folders (directories) to store your project files and folders *as well as additional files used by Git to keep track of all operations performed on your project files and folders*.

  #### Is each project stored in a single repository ?

Git is a distributed version management system. A specific project can be stored in multiple repositories. Usually, there is one reference repository used by all project contributors. All contributors have a local or work repository, which they initially cloned from the reference repository (more on this later).

### What's a Branch ?

In short: a branch is a name used to track the history of changes to files and folders over time, as a series of commits.
A repository can manage as many branches as needed (more on this later). When working on a Git project, there is always a *current* branch. Git provides operations to create/remove/switch between branches.

### What's a Commit ?

In short: a commit is a set of changes to files or folders that we want Git to keep track of, such as:
  - Addition a file or folder
  - Modification of the contents of a file
  - Removal of a file or folder
  - Renaming of a file or folder

Git provides operations to specify which files should be part of a commit.


## Creating a Repository

### [Log In to GitLab](./media/gitlab-login.mp4)

Log in to GitLab using your favourite account settings (GitLab, Google, GitHub, Twitter...)

![./media/gitlab_login.png](./media/gitlab_login.png)
  
### [Create a new Project](./media/gitlab-create-project.mp4)

1. Select **Create a Project**
1. Select **Create Blank Project**
1. Give it a sensible name for a collection of animal descriptions
1. Keep the visibility **private**
1. Check the **Initialize repository with a README**
1. Select **Create Project**
  

![./media/gitlab_create_project.png](./media/gitlab_create_project.png)

### GitLab User Interface Main Panels

#### Project Summary Information

Recap with your project's name the number of _commits_, _branches_ (more on these soon) and _tags_ as well as storage space occupied by project files.

![./media/gitlab_project_info.png](./media/gitlab_project_info.png)

#### Current View and Most Recent Activity

Which _branch_ are we looking at ?
What was the most recent activity in this branch ?

![./media/gitlab_current.png](./media/gitlab_current.png)

#### Files / Folders in the Current View

Which files folders are part of the current _branch_ ?
If there's a `README.md` file, what's its contents ?  

![./media/current_files.png](./media/current_files.png)


## Using the Web IDE

The Web IDE provides all that is required to manipulate a project's files. 

### Left Panel

The left panel shows a file explorer with at the top, buttons for:
  - Creating new files.
  - Uploading files.
  - Creating new folders.

  ![edit_icons.png](./media/edit_icons.png)
  
In the file explorer, highlighting a file/folders gives acces to a contextual menu with a set of operations: `rename/move` or `delete` for files and folders,  `new file`, `upload file` and `new directory` for folders.

Icons on the right of file name give clues as to what has been modified since the latest *commited* state of the current branch :
  - An orange dotted square icon after a file name means it has been modified

    ![modification_icon.png](./media/modification_icon.png)

  - A green dotted square icon after a file name means it has been added

    ![addition_icon.png](./media/addition_icon.png)

For folders, the number in the square icon represents the number of files inside the folder that have been affected by changes since the latest commit.

At the bottom of the left panel, a button allows to *commit* all the changes (i.e.: integrate them into the repository).

![commit_button.png](./media/commit_button.png)

### Center Panel

The center panel allows editing or viewing files using a tab for each currently opened file.

## Commiting Changes

Using the `Create commit...` allow to tune how modifications will be propagated to the repository:

  - A text area recaps the modifications included in the commit, which can be edited at will.
  - Two radio buttons allow to choose whether the commit will be made in the current branch (default choice) or if a new branch will be created on the fly
  - A checkbox `Start a new merge request...`(checked by default) can be used to create a *merge request* matching the commit.

### Merge Requests vs. Basic Commits

  - A basic *commit* will immediately propagate all modifications to the selected branch. The only remaining trace of the modifications will be a commit id (or hash code). This may be adapted to a set of small changes to a branch used by a single developer.

  - A *merge request* will encapsulate all the modifications in a changeset and not apply them immediately to the selected branch. To actually integrate the modifications, someone will have to `Merge` (!) the merge request. A best practice is to create merge requests when a changeset is destined to another branch, especially when the destination branch is also used by other participants. When creating a merge request, GitLab allows to add more comments as well as to assign the merge request to another project participant. Depending on project configuration, developers will not be allowed to commit to some branches (typically `main` and `develop`). The will need to create a merge request if they want their changes to be integrated into these protected branches. Project maintainers will then review the merge request before actually merging the changes.
  

## Your Turn

Take some time to complete [the exercises](./exercises.md)