Introduction to git and Gitlab

This presentation will show you how to manage your projects with the IN2P3 Gitlab. It is based upon the work of Grégory Sainton at IPGP. It is directed to the members of the METIS Geophysics team.

Get started

Install git : https://git-scm.com/downloads

Create your Gitlab account on the IN2P3 server

https://gitlab.in2p3.fr/users/sign_in

You should be able to connect with your Sorbonne Université or CNRS credentials.

Once your account is activated, I recommend you set up a specific password to your account by clicking on your avatar at the top left, then Preferences and Password.

Join the METIS Geophysics group

You can find it here : https://gitlab.in2p3.fr/metis-geophysics/

Create your SSH Key

If you do not have an existing SSH key pair, generate a new one:

Open a terminal.
Run ssh-keygen -t followed by the key type and an optional comment.

This comment is included in the .pub file that's created. You may want to use an email address for the comment.
```
ssh-keygen -t ed25519 -C "<firstname.lastname@sorbonne-universite.fr>"
```

Press Enter. Output similar to the following is displayed:

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):

Accept the suggested filename and directory by pressing Enter
Specify a passphrase:
```
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
```
A confirmation is displayed, including information about where your files are stored.

The public key needed to access your Gitlab account is stored in ~/.ssh/id_ed25519.pub

More details can be found here : https://gitlab.in2p3.fr/help/user/ssh

Add the SSH key to your Gitlab account

Copy and paste content of your public key in the designated field as shown below.

add ssh key

Verify that you can connect

Verify that your SSH key was added correctly.

Open a terminal and run the following command:

ssh -T git@gitlab.in2p3.fr

The following warning message will appear:

The authenticity of host 'gitlab.in2p3.fr (134.158.69.41)' can't be established.
ECDSA key fingerprint is SHA256:j9RRZcczB+XocN53k9R/+IAs1nLHyEjjkB4bjJiL+QU.
Are you sure you want to continue connecting (yes/no)?

Type yes, then you might have to enter your passphrase defined when generating the SSH key.

Once done, you'll get the confirmation that all worked correcly:
```
Warning: Permanently added 'gitlab.in2p3.fr,134.158.69.41' (ECDSA) to the list of known hosts.
Welcome to GitLab, @username!
```

Create a new repository/project in Gitlab

On the top right of your Gitlab main page, click on New Project, then Create blank project
Give it a name, then choose the project url to decide wether you want to store the project on your own personnal page (usually firstname.lastname) or on any group you are part of (e.g. metis-geophysics).
Select the visibility level and wether you want to initialize a Readme file, then click on Create project.

If a project is empty, you won't be able to sync it locally. You can create files either from the Gitlab interface, or locally and then push them to Gitlab's server.

Download/clone a distant repository on your computer

On Gitlab project's main page, get the repository ssh or https address by clicking on Code or Clone (depends on Gitlab version), then Clone with SSH or Clone with HTTPS .

clone repository

In a terminal, type :

git clone git@gitlab.in2p3.fr:metis-geophysics/gitlab_introduction_metis.git

It will create a directory with a local copy of the repository.

You can then retrieve remote updates of the project, move to the local directory with the following command :

cd gitlab_introduction_metis
git pull

Create a repository on your computer

Create a directory : mkdir new_repo

This directory is your workspace. It contains the version of your repository you are currently working on.
Get to the directory : cd new_repo
Create a readme file in Markdown : echo '# New repository' > README.md

If you don't know Markdown : https://www.markdownguide.org/basic-syntax/
Initialize git repository : git init
It will create an empty Git in /Users/me/new_repo/.git/

This .git hidden directory will contain all versions of your repository, so you can go back and forth within versions of your project.
Get the status of the repository : git status

You should get the following message : On branch master
```
No commits yet

Untracked files:
(use "git add <file>..." to include in what will be committed)

README.md

nothing added to commit but untracked files present (use "git add" to track)
```
It means that there are new files in the repository that are not indexed, and thus only exist locally in your workspace.
To add the file to the index, use git add README.md

You can also add all the new (or untracked), deleted and modified files at once with git add -A

The new files are now staged (indexed), but not yet in the repository.
If you want to unstage files : git reset README.md
To definitely add the new file to the local repository as a new comit snapshot, use git commit -m "My first commit, I'm so happy!"

You'll get the following message:
```
[master (root-commit) c60c6f2] My first commit, I'm so happy!
1 file changed, 1 insertion(+)
create mode 100644 README.md
```
The message between quotes should be short and explicit to help you remember what kind of overall changes were made in the new version of the repository.

You can get information about previous commits with git log.

Here is what you should get :

commit c60c6f2ecd55c94dff82bda85b13b02c433e0801 (HEAD -> master)
Author: Sylvain Pasquet <sylvain.pasquet@upmc.fr>
Date:   Thu Jun 6 11:42:02 2024 +0200

My first commit, I'm so happy!

Now let's modify README.md. Open it with your text editor and save modifications.
Use git diff look at the differences between the file stored in the local repository, and the file in the workspace that we just modified.

In the example, I added a new empty line, and a line with the following text: How to use git and Gitlab.. Here is what your should get :
```
diff --git a/README.md b/README.md
index 33addf3..19743d0 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,3 @@
# Create a new repository
+
+How to use git and Gitlab.
```
If you want to save the changes in your local repository, simply redo git add README.md, then git commit.

If you don't specify a message in the git commit command, you will be asked to enter the commit message in the terminal using vim.

Press i to start insert mode, type your message, then press Ctrl + C to quit insert mode. Type :x to save and quit.

Here is a list of vim commands : https://vim.rtorr.com/
If you want to change the commit message before pushing it to the distant repository, use git commit --amend -m "My new message". You can check if it worked correctly with git log

To summarize :

git init : Create a local repository

git add : Add files to the index

git commit : Add indexed files to the local repository

git log : Get the list of actions done on the repository

git status : Get the current status of the repository (highlights changes since the last commit)

git diff : Show the difference between the workspace and the local repository

Push your local repository to Gitlab

Initial configuration

git config --global user.name "Sylvain Pasquet"
git config --global user.email "sylvain.pasquet@upmc.fr"
git remote add origin git@gitlab.in2p3.fr:sylvain.pasquet/new_repo.git

These informations are saved in the .gitconfig file

If you want to push the repository to the METIS Geophysics group, change the git remote command as follows :

git remote add origin git@gitlab.in2p3.fr:metis-geophysics/new_repo.git

Now let's make the first push to Gitlab

git push --set-upstream origin master

It should give you the following message :

Counting objects: 6, done.
Delta compression using up to 12 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (6/6), 538 bytes | 538.00 KiB/s, done.
Total 6 (delta 0), reused 0 (delta 0)
remote: 
remote: 
remote: The private project sylvain.pasquet/new_repo was successfully created.
remote: 
remote: To configure the remote, run:
remote:   git remote add origin git@gitlab.in2p3.fr:sylvain.pasquet/new_repo.git
remote: 
remote: To view the project, visit:
remote:   https://gitlab.in2p3.fr/sylvain.pasquet/new_repo
remote: 
remote: 
remote: 
To gitlab.in2p3.fr:sylvain.pasquet/new_repo.git
* [new branch]      master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'.

And new_repo should now appear on your Gitlab Personal projects

Then, for the next pushes
```
git push
```

Advanced tips & tricks

If you want to exclude some local files from the repository (e.g. local configuration files), you need to create a .gitignore file. Go into your repository, and type the following command in the terminal :
```
echo '# Gitignore file' > .gitignore
```
Then open it with your text editor and list any file you want to ignore
```
# Gitignore file

.DS_Store
.dropbox
.ipynb_checkpoints
```

If you want to compare two commits, first get the ID (SHA) of these commits (list of 40 characters) using the git log command (cf example below).

commit 26c13a25563f4674b6a2b84cb4367df4af78562b (HEAD -> master, origin/master)
Author: Sylvain Pasquet <sylvain.pasquet@upmc.fr>
Date:   Thu Jun 6 11:51:03 2024 +0200

    My new message

commit c60c6f2ecd55c94dff82bda85b13b02c433e0801 (branch1)
Author: Sylvain Pasquet <sylvain.pasquet@upmc.fr>
Date:   Thu Jun 6 11:42:02 2024 +0200

    My first commit, I'm so happy!

Use commit IDs as follow to highlight differences between commits :

    git diff c60c6f2ecd55c94dff82bda85b13b02c433e0801 26c13a25563f4674b6a2b84cb4367df4af78562b

It should give you something like :

    diff --git a/README.md b/README.md
    index 33addf3..19743d0 100644
    --- a/README.md
    +++ b/README.md
    @@ -1 +1,3 @@
    # Create a new repository
    +
    +How to use git and Gitlab.

If you want to go back to a previous commit (i.e. locally in your workspace), use the git checkout command as follows :
```
git checkout c60c6f2ecd55c94dff82bda85b13b02c433e0801
```

Create a branch

If you have a stable version of your code, and you want to develop and test new features, you should create a branch that will diverge from the main code.

git branch

Create a branch called "test"
```
git branch test
```
Move to branch "test"
```
git checkout test
```
Info

You can do this in one step with the following command : git checkout -b test
Check which branch you are currently working on
```
git branch
```
Push the new branch to the remote repository

git push -u origin test