Commit df0c5a2d authored by Laurent Heirendt's avatar Laurent Heirendt
Browse files

Merge branch 'basic-git-scg-group' into 'develop'

Slides for basic git training for SCG group

See merge request !73
parents a2634d99 108f3b92
Pipeline #23750 passed with stage
in 3 minutes and 14 seconds
# Best practices
* `pull` before `push`
* Work on your <font color="red">own</font> branch (in your own fork), and **not** on `master` and **not** on `develop`
* Do **not push** to `master`, but **submit a Merge Request (MR)**
* Get your code **reviewed** by your peers (submit a MR!)
* Submit a MR **often**!
* `clone` a repository, do not download the `.zip` file.
* Do **not** combine `git` commands
```bash
$ git commit -am "myMessage" # do not do this
```
* Stage only 1 file at once using
```bash
$ git add myFile.md
```
* Commit **only a few files** at once (after multiple separate `git add` commands)
* `Push` often - avoid conflicts
Remember: **A `push` a day keeps conflicts away!**
# Development scheme
Generally, in a repository, there are guidelines for contributing.
<div class="fragment">
A common development scheme is dual with a:
- **development** version of the code on `develop`
- **stable** version of the code on `master`
A **version** of the code is referred to as a **branch**.
<div class="fragment">
<img src="slides/img/icon-live-demo.png" height="100px">
<font color="red">In the practice repository, the development branch is called `develop`!</font>
<div class="fragment">
![bulb](slides/img/bulb.png) Use this dual development scheme for your own repositories!
# Branches
A **version** of the code (i.e., a **branch**) is made up of a sequence of code changes.
<div class="fragment">
These individual code changes are called **commits**.
For instance, the `master` and `develop` branches can be represented as a timeline:
<img src="slides/img/branch-master.png" class="branch-master" height="500em"/>
# Switch between branches
List all branches of the repository with
```bash
$ git branch -a
```
Exit by typing `q`. The branch with the * is the current branch.
<div class="fragment">
Checkout another branch
```bash
$ git checkout <branchName>
```
<div class="fragment">
You can switch to the `develop` branch with
```bash
$ git checkout develop
```
If the local branch does not exist but the remote does, it is created automatically.
<div class="fragment">
<img src="slides/img/icon-live-demo.png" height="100px">
# Create your own version
Assume that you want to work on a file:
<div class="fragment">
<font color="red">Create a new **branch**!</font>
```bash
$ git checkout -b myBranch
```
The `-b` flag creates the branch. Locally, you have your own version now:
<img src="slides/img/branch-create.png" class="branch-create" height="500em"/>
Push your version to your fork:
```bash
$ git push origin myBranch
```
<div class="fragment">
<img src="slides/img/icon-live-demo.png" height="100px">
# How do I start working on a repository?
You have to `clone` it first:
```bash
$ git clone ssh://git@git-r3lab-server.uni.lu:8022/<groupName>/myRepo.git myRepo
```
If you did not configure your SSH key, clone using HTTPS:
```bash
$ git clone https://git-r3lab.uni.lu/<groupName>/myRepo.git myRepo
```
You will be prompted to enter your credentials.
# How to configure `git`?
```bash
$ git config --global user.name "Firstname Lastname"
$ git config --global user.email "first.last@uni.lu"
```
Test whether your username and email have been registered
```bash
$ git config --list
```
This should list the configuration with `user.name` and `user.email`.
Exit by typing `q`.
# What is an SSH key?
An SSH key is a secure access credential.
**Principle**: <br><br>
Communicate **securely** with Github/Gitlab **without** entering the username/password.
# How do I get and set my SSH key?
Check if you already have an SSH key:
```bash
$ ls -al ~/.ssh
```
If there are 2 files named `id_rsa`, you have an SSH key.
If you don’t have yet an SSH key, you have to generate one:
```bash
$ ssh-keygen -t rsa # -b 4096
```
Then, add the SSH key to Github/Gitlab.
<img src="slides/img/icon-live-demo.png" height="100px">
\ No newline at end of file
# The 5 essential commands
**Yes**, you only need 5 commands!
`pull, status, add, commit, push`
or in other words (remember these!):
```bash
$ git pull <remote> <branch>
$ git status
$ git add myFile.md # example
$ git commit -m "myMessage" # example
$ git push <remote> <branch>
```
# Pull the latest version of an existing branch
Pull the latest revision on branch `myBranch`:
```bash
$ git pull origin myBranch
# Already up to date
```
<div class="fragment">
Verify its `status` with:
```bash
$ git status
```
# Modify a file
Copy the file `template.md` in the folder `_attendees` and rename it with your firstname:
```bash
$ cd _attendees
$ cp template.md myName.md
```
Then, make your changes with your favorite editor!
# Add your file to the stage
First, check the repository status
```bash
$ git status
# uncommitted changes (displayed in red)
```
<div class="fragment">
Now, add the file (bring it on stage)
```bash
$ git add myName.md # replace myName
$ git status
# returns the same as before, generally in green (means staged)
```
<div class="fragment">
**ADVANCED**: If there have been more changes after the file has been added, you can see your changes in the terminal
```bash
$ git diff
```
exit with `q`
# Add a commit message
```bash
$ git commit -m "Add the profile of <myName>"
$ git status
```
# Push your file to your fork
```bash
$ git push origin myBranch
```
<div class="fragment">
**ADVANCED**: see the log of all the commits (and your last one) in the terminal
```bash
$ git log
```
exit by typing `q`.
\ No newline at end of file
# What is a `fork`?
<center>
<img src="slides/img/fork.jpg" class="as-is" height="500em"/>
</center>
<!--http://www.cndajin.com/data/wls/246/22302193.jpg-->
# Not really ...
<center>
<img src="slides/img/fork-crossed.png" class="as-is" height="500em"/>
</center>
# What is a `fork`?
- In general, when contributing to a repository, you only have **read** access.
- In other words, you can only **pull** (unless it is your own repository or access has been granted).
- In general, you **cannot write** changes. In other words, you do not have **push** access.
- You have to work on your **own copy**.
- In other words, you have to work on your own <font color="red">**fork**</font>.
# How to get a fork?
Browse to the original repository and click on the button `Fork`:
![Fork the repo](https://help.github.com/assets/images/help/repository/fork_button.jpg)
<img src="slides/img/icon-live-demo.png" height="100px">
# Time to practice!
Fork the practice repository: <br><br>
https://git-r3lab.uni.lu/R3/school/git/basic-practice-pages<br><br>
Then, clone your fork to your home directory!
<img src="slides/img/icon-live-demo.png" height="100px">
```bash
$ git clone ssh://git@git-r3lab-server.uni.lu:8022/<yourName>/basic-practice-pages.git
```
Change to the practice directory with:
```bash
$ cd basic-practice-pages
```
# A note on shortcuts ...
<font color="red">
Any other rudimentary method such as
*'I simply download the `.zip` and unzip it - works like a charm!'*
shall **be avoided**!
</font>
**Why?**
# How to update my fork?
As you have your own fork, it will not automatically be updated once the original repository is updated.
![bulb](slides/img/bulb.png) You have to update it yourself!
<br>
**More on that later!**
# GitHub and GitLab
<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" alt="GitHub" style="width: 200px;"/>
<img src="https://gitlab.com/gitlab-com/gitlab-artwork/raw/master/logo/logo-extra-whitespace.png" alt="GitLab" style="width: 200px;"/>
GitHub and GitLab are VCS systems.
GitHub/Gitlab are both **publicly available**, but GitLab can be **on-premise**.
Positive point: GitHub and GitLab are (almost) the same.
<img src="slides/img/icon-live-demo.png" height="100px">
- **GitHub**: [https://github.com](https://github.com)
- Public GitLab: [https://gitlab.com](https://gitlab.com)
- LCSB specific: [https://git-r3lab.uni.lu](https://git-r3lab.uni.lu)
\ No newline at end of file
../../../2019/2019-06-11_basicGitTraining/slides/img
\ No newline at end of file
# R3.school
## March 30th, 2020
<div style="top: 6em; left: 0%; position: absolute;">
<img src="theme/img/lcsb_bg.png">
</div>
<div style="top: 5em; left: 60%; position: absolute;">
<img src="slides/img/r3-training-logo.png" height="200px">
<br><br><br>
<h1>git training for beginners</h1>
<br><br><br><br>
<h4>
Laurent Heirendt, Ph.D.<br><br>
laurent.heirendt@uni.lu<br><br>
<i>Luxembourg Centre for Systems Biomedicine</i>
</h4>
</div>
# The terminal (shell)
**macOS users:**
> Start the Terminal from your `/Applications` directoy.
![bulb](slides/img/bulb.png) Install iTerm2: [https://www.iterm2.com](https://www.iterm2.com)
<br>
**Windows users:**
> Install Git Bash: [https://git-scm.com/download/win](https://git-scm.com/download/win)
<br>
**Linux users:**
> Launch default terminal.<br>
![bulb](slides/img/bulb.png) Install Terminator: [https://launchpad.net/terminator](https://launchpad.net/terminator)
# Installation of `git`
<img src="slides/img/github_app.png" class="as-is" height="200" />
**macOS**
> Install *Xcode Command Line Tools*
<br>
**Windows**
> Install Git Bash: <br>`https://git-scm.com/download/win`
<br>
**Linux (Ubuntu)**
```bash
$ sudo apt-get install git-all
```
# How to get started?
**macOS**
> Start the `Terminal` or `iTerm`.
<br>
**Windows**
> Start `GUI Bash`.
<br>
**Linux (Ubuntu)**
> Start the `Terminal` or `Terminator`.
[
{ "filename": "index.md" },
{ "filename": "overview.md" },
{ "filename": "what_is_git.md" },
{ "filename": "github_gitlab.md" },
{ "filename": "installation.md" },
{ "filename": "the_terminal.md" },
{ "filename": "the_editor.md" },
{ "filename": "configuration.md" },
{ "filename": "cloneRepo.md" },
{ "filename": "forks.md" },
{ "filename": "branches.md" },
{ "filename": "essential_commands.md" },
{ "filename": "merge.md" },
{ "filename": "syncFork.md" },
{ "filename": "best_practices.md" },
{ "filename": "thanks.md" }
]
# Pull and merge requests
If you want your changes to be reflected on the `develop` or `master` branches,
**submit a PR** via the Github interface.
Use the **interface** to make use of your peers to review your code!
<img src="slides/img/branch-merge.png" class="branch-merge" height="500em"/>
Once merged, you can delete the branch via the interface.
<div class="fragment">
<img src="slides/img/icon-live-demo.png" height="100px" >
\ No newline at end of file
# Overview
1. What is `git`? What is the use of `git`?
2. GitHub and GitLab
3. The terminal
4. Installation of `git`
5. The editor
6. How do I configure `git`?
7. Where and how to start?
8. What is a fork?
9. What are branches?
10. The 5 essential commands (`pull` / `status` / `add` / `commit` / `push`)
11. What are merge/pull requests?
12. How do I synchronize my fork?
13. Best practices
\ No newline at end of file
# Synchronize your fork
![bulb](slides/img/bulb.png) Remember, we have to regularly update our own copy of the code.
Add the `upstream` address (original/protected repository)
```bash
$ URL=ssh://git@git-r3lab-server.uni.lu:8022/R3/school/git/basic-practice-pages.git
$ git remote add upstream $URL
```
![bulb](slides/img/bulb.png) Note the change in the URL.
You can then check whether the remote address is set correctly
```bash
$ git remote -v
```
<div class="fragment">
Fetch the changes from upstream (similar to pull)
```bash
$ git fetch upstream
```
Merge the retrieved changes on the `master` branch:
```bash
$ git checkout master
$ git merge upstream/master
$ git push origin master
```
<div class="fragment">
Do the same for the `develop` branch:
```bash
$ git checkout develop
$ git merge upstream/develop
$ git push origin develop
```
<img src="slides/img/icon-live-demo.png" height="100px">
\ No newline at end of file
# Let's refresh our memories
<div class="fragment">
- What is a **fork**?
<div class="fragment">
- What are **branches**?
<div class="fragment">
- Can I have **multiple branches** in my fork?
<div class="fragment">
- What is a good **development scheme**?
<div class="fragment">
- What are the **5 essential commands**?
# References & Cheat sheet
[1]: Git Book: https://git-scm.com/book/en/v2
[2]: GitHub training services: https://services.github.com/training/
[3]: Cheat sheet: http://rogerdudler.github.io/git-guide
# Thank you.
<img src="slides/img/r3-training-logo.png" height=