Slides

Version your code with git!

A guide to manage your code and projects

Pierre Galmiche, December 2023

Not used to these slides?

You can navigate with:

The space bar
By clicking on the blue arrows .
By scrolling down on your phone
Go down first!

Why should you learn how to Git?

Every "big" coding projects in the world are using it
It's intuitive: just read the documentation!
You can go back in time!!!

What is git?

Git is

a versionning sofware
open source
hosted on GitLab or GitHub
efficient for collaborative work

We will start with the setup.

Create a GitLab repository (online)

Go to the GitLab page.
Follow the steps shown in the video.
Read the options for more personalization.

Clone a project (local)

Copy url in GitLab (video)
Run the clone command in your terminal


          git clone COPIED_URL

For the ssh version, you first need to set up a SSH key.

Local or Remote?

Please keep in mind that:

Git is local
Your GitLab host is a remote
You work locally and exchange with the remote.

You can work now!

Go to the cloned awesome folder
```
cd awesome-project/
          
```

Add an "awesome_file.txt" and write in it


In this file we add marvelous things.

Check what git has done with the command
```
git status
          
```

Git status to help you

If you are lost, use the command:
```
git status
          
```
Then, look where you are and what to do.

Let's look at an example.

Git status tells you that

You work on main (local) which is up to date with "origin/main" (remote).

We will learn more about branch later.

Git status tells you that

Your "awesome_file.txt" is not tracked.

Git status tells you that

You can use "git add" to track your file.

Only few commands to get started!

Basic Workflow

The basic git workflow consists in few commands:

```
git add FILE_NAME
          
```
to track the changes of your files


git commit -m "my awesome message"

to gather modifications and add a message (-m)

```
git push origin main
          
```
to push main branch to the server
```
git pull server branch
          
```
to recover modifications from the server

Practical case: our awesome project

Send the awesome file to origin

To version our awesome_file.txt, we use the command:
```
git add awesome_file.txt
          
```

We then commit this change with:


git commit -m "I added the awesome_file.txt"

Finally we push the modifications to the server
```
git push origin main
          
```

Some tips for the add command

The following commands can help you to add files:

```
git add -u
          
```
adds all modified files (not new files)


git commit -am "my awesome message"

adds modified files (not new files) + commit

```
git add -A
          
```
to add all the files in your project


git rm --cached awesome_file.txt

to undo a git add

Some tips for the add command

What if you don't want to follow some files?

```
git add -A
          
```
could add some files you don't want
To solve this problem, create and open a ".gitignore" file.

add the unwanted files/folders:


          *.npy
          *.png
          unwanted_folder/

Your files are ignored! Check with:
```
git status
          
```

Gitlab: commits and online changes

"git push" sends your commits to the remote.

Go to your GitLab page.
Check your commit(s)
Change a file online

Pull changes from the origin

To download the origin modifications, use:
```
git pull origin main
          
```
In some cases you might have some issues:

pull is refused because you have modified files
pull is refused because you have conflicts

Pull but you have modified files

You hide your modifications, pull, and pop them.

```
git stash
          
```
```
git pull
          
```
```
git stash pop
          
```

Or you commit your changes and you pull.

```
git commit -m "fix pull"
          
```
```
git pull
          
```

Pull: but you have conflicts

You have to select a strategy to deal with conflicts:

manual with a commit (recommended)


git config pull.rebase false

manual without commit
```
git config pull.rebase true
          
```
only pull if there is no conflict
```
git config pull.ff only
          
```

How to deal with your conflicts

Find files with conflicts:
```
git status
          
```

Open "both modified" files and find:


<<<<<<< HEAD
Your modifications in my_branch
=======
Conflicting modifications in the other branch
>>>>>>> other_branch_name

Remove the unwanted lines.


Your modifications in my_branch

Commit, add, push


          git commit -am "fix the conflicts :)"

          git push origin my_branch

A last word about your remote

GitLab, Gitub, or Bitbucket can be powerful for managing your project.
Read the Milestones, Issues and other documentation adapted to your needs.

Add people to your project, create milestones and related issues.

You now know how to git!

and can learn more Advanced Workflow.

You want to go back in time?

Before going into the past

First, you need to have knowledge of history with:

```
git log
          
```
to show the commits logs/history
```
          git reflog
          
```
to show show the reference logs/history

History: git log output

The git log command gives each commit hash, author and email, date, together with the commit message.


commit 85c035458122ca9f90a56fc2fa167bb61d22580b (HEAD -> master)
Author: Initial Commit LLC "Example@domain.com"
Date:   Mon May 23 10:39:12 2022 -0500

    Added sample text to file1.ext

commit cd918fd09e0014eefbcf9516a6ad99c431315838
Author: Initial Commit LLC "Example@domain.com"
Date:   Mon May 23 10:27:34 2022 -0500

    Initial commit

History: git log tips


git log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

to personnalize the logs


          git log -- path/to/file(s)

to only show commits changing the file(s)(last option)


          git log --grep=word

to only show commits with "word" in their message

History: git reflog output

Git reflog output looks like:


a32556a HEAD@{0}: commit: migrating content
ab371fd HEAD@{1}: commit: adding git reflog outline
23a491a HEAD@{2}: checkout: moving from stage to feature/solver
56a183a HEAD@{3}: commit: changing color scheme

and tracks every change (with its hash) effecting the git refs location.

You can moove in history with

```
git checkout commit_hash
          
```
to change your files back to the commit
```
git reset commit_hash
          
```
goes back to the commit and moves HEAD to commit

You can change history

But before doing so, be careful. Your actions may have consequences.
Never change public history (already pushed information).

You can change history with

```
git revert commit_hash
          
```
to undo a commit
```
git reset --hard commit_hash
          
```
reset current branch to a previous commit while discarding any local change

```
git rebase -i commit_hash
          
```
interactively changes history from the given commit


git commit --amend -m "an updated commit message"

to add new changes to the last commit

Advanced workflow

Be curious and look at the documentation for more details about the commands (-h or --help).

We now dive into powerful git features.
You can use the git history together with them.

Advanced workflow

The advanced git workflow contains:

Branching to always have a working/tested version
Tagging to mark specific versions (commits) of your code

Submodules to use other projects inside yours
GitLab CI/CD to automate build/test/deploy

Git branches

represent independent lines of development.
allow you to always keep a working version.

allow you to work on features separately.
help you to organize your code development.

Git branches

To deal with branches, you need the following commands:

```
git branch my_branch
          
```
to create a branch
```
git checkout my_branch
          
```
to switch to my_branch

```
git merge my_branch
          
```
to merge my_branch to the current branch
```
git branch -d my_branch
          
```
to delete my_branch

Some tips for the branch commands

The following commands can help you:

```
git branch -a
          
```
to list the branches
```
git checkout -b my_branch
          
```
to create and checkout to my_branch


git branch -m old_name new_name

to rename the branch


git push --set-upstream origin my_branch

to push my_branch to the server

Git tag

To tag, you need the following commands:


git tag -a v1.7 -m "version 1.7"

to capture the last commit


git tag -a v1.7 1502795d -m "version 1.7"

to tag an older commit with SHA hash = 1502795d

SHA hash is found using:
```
git log --pretty=oneline
          
```

Git tag

Then, you can use the following commands to:

list the tags with their messages:
```
git tag -n
          
```
go back to the tag version using:
```
git checkout TAG_NAME
          
```
push you tag to the remote
```
git push origin TAG_NAME
          
```

Git submodules

are useful:

to integrate other git projects to yours
to avoid code duplication
to follow external projects evolutions and update directly the features in your project

Git submodules

To use submodules, you need the following commands:


git submodule add repo_url folder_path

to add a git folder to your project

```
git submodule init
          
```
to initialize the submodules
```
git submodule update
          
```
to fetch the data from the submodules

Git submodules: some tips

A submodule is a git folder! You can pull, add, commit from it and push if you have the rights.
To clone a git repository together with its submodules, you can:


git clone --recurse-submodules repo_url


git clone repo_url
git submodule init
git submodule update

GitLab CI/CD for automation

Continuous Integration (CI) consists in automating code changes in a project.
GitLab uses a ".gitlab-ci.yml" to configure the tasks and runs them automatically when you push.
Follow the GitLab tutorial for CI for more information.

Bonus commands

You can always go further with git.
The following slides contains extra commands to amaze you.

Git Hooks

To add scripts/actions before/after your commits or pushes to:

Only accept commits if the files follow a specific syntax
Force commit messages to have a specific syntax

You have an idea of advanced workflow in git

Continue your quest of git knowledge with the documentation and check out git integrations for your favorite editor: