Commit 9d49eb88 authored by Laurent Heirendt's avatar Laurent Heirendt
Browse files

slides of training of april 12th

parents
## 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` or `develop`, but **submit a PR**
* Get your code **reviewed** by your peers (submit a PR!)
* Submit a PR **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.txt
```
* Commit **only a few files** at once (after multiple separate `git add` commands)
* `Push` often - avoid conflicts
<br><br>
Remember: **A `push` a day keeps conflicts away!**
## Branches
Branch-off within the same repository in order to stay safe!
<br><br>The master branch
<img src="img/branch-master.png" class="branch-master" />
## One branch per feature
Assume that you want to work on a function for a matrix-vector operation.
```bash
$ git checkout -b matrix_vect_mult_myName
# creates the branch locally
```
The `-b` flag creates the branch.
<img src="img/branch-create.png" class="branch-create" />
Push the branch to the remote repository
```bash
$ git push
```
If you do that, `git` might complain
```bash
fatal: The current branch matrix_vect_mult_myName has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin matrix_vect_mult_myName
```
<br>
Follow the advice and do
```bash
$ git push --set-upstream origin matrix_vect_mult_myName
```
## Switch between branches
In your terminal, you may see the name of the branch you are on.
List available branches of the repository
```bash
$ git branch --list
```
<div class="fragment">
<br>
Checkout another branch
```bash
$ git checkout <branch_name>
```
<div class="fragment">
<br>
You can switch back to the `master` branch with
```bash
$ git checkout master
```
<br>
You can use the 5 essential commands as before.
Only difference: you are on your own branch.
<img src="img/branch-commit.png" class="branch-commit" />
## Merge a branch
If you want your feature on the `develop` or `master` branches,
**submit a MR or a PR** via the Github/Gitlab interface.
<br>
Use the **interface** to make use of your peers to review your code!
<img src="img/branch-merge.png" class="branch-merge" />
<br>
Once merged, you can delete the branch via the interface.
## Github interface
<img src="https://assets-cdn.github.com/images/modules/logos_page/GitHub-Mark.png" alt="GitHub" style="width: 100px;"/>
Detailed information is on [help.github.com/articles/creating-a-pull-request/](https://help.github.com/articles/creating-a-pull-request/).
1. Click on **New pull request**
![New pull request](https://help.github.com/assets/images/help/pull_requests/pull-request-start-review-button.png)
<br><br>
2. Compare the branches
![Compare branches](https://help.github.com/assets/images/help/pull_requests/choose-base-and-compare-branches.png)
<ol start="3">
<li>Assign your peer
<br>
![Assigning a peer](https://help.github.com/assets/images/help/issues/issues_assigning_dropdown.png)
</li>
</ol>
<ol start="4">
<li>Submit the PR
![Submit MR](https://help.github.com/assets/images/help/pull_requests/pullrequest-send.png)</li>
</ol>
## The 5 essential commands
<br>
**Yes**, you only need 5 commands!
<br>
`pull, status, add, commit, push`
<br>
or in other words (remember these!):
```bash
$ git pull
$ git status
$ git add myFile.txt # example
$ git commit -m "myMessage" # example
$ git push
```
## Pull the latest version of an existing repository
First, browse to the cloned directory (`git clone [...]`):
```bash
$ cd practice
```
Then, pull the latest revision:
```bash
$ git pull
# Already up to date
```
Verify its `status` with:
```bash
$ git status
```
## Be safe and create a new branch
(more on branches in a few minutes)
<br><br><br><br><br>
```bash
$ git checkout -b matrix_vect_mult_myName
```
## Modify a file
Modify and rename `addTwoNumbers.m` in the folder `firstCommit`
<br>
Open the file `addTwoNumbers.m` in the folder `firstCommit` using the `Atom` editor (or any other editor).
<br>
Then, rename the function by adding your name (`addTwoNumbers_myName`)
<br>
Uncomment the line
```Matlab
% c = a + b
```
<br>
Save and rename the file by <font color="red">adding your name</font>
```bash
$ mv firstCommit/addTwoNumbers.m firstCommit/addTwoNumbers_myName.m
```
## Add your file to the stage
First, check the repository status
```bash
$ git status
# uncommitted changes (displayed in red)
```
<div class="fragment">
<br>
Now, add the file (bring it on stage)
```bash
$ git add firstCommit/addTwoNumbers_myName.m
# returns the same as before, generally in green (means staged)
```
<div class="fragment">
<br>
**ADVANCED**: see your changes in the terminal
```bash
$ git diff
```
exit with `q`
## Add a commit message
```bash
$ git commit -m "Uncommented line for adding 2 numbers"
$ git status
```
<br>
You can pull, even at this stage, new possible changes
```bash
$ git pull
```
## Push your file to the repository
```bash
$ git push
```
<div class="fragment">
<br>
**ADVANCED**: see the log of all the commits (and your last one) in the terminal
```bash
$ git log
```
exit by typing `q`
## Do it yourself
* Modify and rename `secondCommit/multiplyTwoNumbers.m`
* Push the file `secondCommit/multiplyTwoNumbers_myName.m`
* Don't forget to add <font color="red">`_myName`</font>
<div class="fragment">
<br>
Commands:
```bash
$ git pull
$ git diff # optional
$ git add secondCommit/multiplyTwoNumbers_myName.m
$ git commit -m "Uncommented line for multiplying 2 numbers"
$ git status
$ git push
$ git log # optional
```
## Forks
You **fork** when you want to work on a public repository or a protected repository.
<br><br>
Remember:
- A **fork** is your own **copy** of a repository.
- A **fork** can have multiple **branches**.
- A **fork** is not a **branch**, but can have multiple **branches**.
<br><br>
A **fork** is only useful when you want to contribute, e.g., to The COBRAToolbox.
## Fork via interface
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)
## Clone your fork
Clone first
```bash
$ git clone https://git-r3lab.uni.lu/myGroup/myRepo.git forkMyRepo
```
<br>
then, you can change to the directory
```bash
$ cd forkMyRepo
```
## Add the address of the original repository
Add the `upstream` address (original/protected repository)
```bash
$ git remote add upstream https://git-r3lab.uni.lu/origGroup/origRepo.git
```
<br>
You can then check whether the remote address is set correctly
```bash
$ git remote -v
```
<!-- <img src="img/remote-0-master.png" class="as-is" /> //-->
<!-- <img src="img/remote-1-remote.png" class="as-is" /> //-->
<!--- <img src="img/remote-2-push.png" class="as-is" /> //-->
## Synchronize your fork
```bash
$ git checkout master
$ git status
```
<div class="fragment">
<br>
Fetch the changes from upstream (similar to pull)
```bash
$ git fetch upstream
```
<div class="fragment">
<br>
Merge the retrieved changes
```bash
$ git merge upstream/master
```
<div class="fragment">
<br>
Push the changes to your own fork
```bash
$ git push origin master
```
## Pull/Merge Requests
**Good news!**
Same procedure as with merging a branch...
## GitHub and GitLab
<img src="https://assets-cdn.github.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 is **public**, whereas GitLab is **restricted/private**.
Positive point: GitHub and GitLab are (almost) the same.
## GitHub (Live Demo)
[www.github.com](www.github.com)
<br><img src="https://assets-cdn.github.com/images/modules/logos_page/GitHub-Mark.png" alt="GitHub" style="width: 200px;"/>
## GitLab (Live Demo)
[https://git-r3lab.uni.lu](https://git-r3lab.uni.lu)
<br><img src="https://gitlab.com/gitlab-com/gitlab-artwork/raw/master/logo/logo-extra-whitespace.png" alt="GitLab" style="width: 200px;"/>
## Homework on GitLab
*This exercise has to be done on your lab computer on which `Matlab` **is** installed. Don't forget to properly configure `git` with your username and email, as we explained in the training slides.*
<br>
During the training, you committed to the
<br>
[https://git-r3lab.uni.lu/git-training/practice](https://git-r3lab.uni.lu/git-training/practice)
repository.
<br>
Your task is to create a fork of this repository, commit some code and create a merge request on `GitLab`.
## Homework: instructions
- First, fork the [https://git-r3lab.uni.lu/git-training/practice](https://git-r3lab.uni.lu/git-training/practice) repository.
- Create the new branch `homework_myName`.
- Implement a new function (create a new file `sqrt_myName.m`) called `sqrt_myName(x)` that computes the square root of `x`.
- Copy the `test.m` file to `test_myName.m` and change the names of the functions accordingly.
- Before submitting the merge request, verify locally that your code is running properly.
Simply execute it
```sh
$ matlab -nodesktop -nosplash < test_myName.m
```
and verify that no error is reported.
- Create a merge-request.
- Assign either Laurent (@laurent.heirendt) or Sylvain (@sylvain.arreckx) depending on your group and your merge-request will be reviewed by one of us.
<br>
That's it!
Absolute Beginners<br>
<img src="img/Git-Logo-Black.png" class="as-is" height="100px"><br>Workshop
<br>
<img src="img/logoLCSB.png" class="as-is" height="100px">
<br><br><br><br>
<br>
April 12th, 2017
Sylvain Arreckx & Laurent Heirendt
<br><br><br><br>
## Installation
<img src="img/github_app.png" class="as-is" height="200" />
**Linux (Ubuntu)**
```bash
$ sudo apt-get install git-all
```
<br>
**macOS**
Install *Xcode Command Line Tools*
<br>
**Windows**
Follow instructions on *[git-for-windows.github.io](https://git-for-windows.github.io)*.
**or:** `MobaXTerm` with `git` plugin: *[mobaxterm.mobatek.net](https://mobaxterm.mobatek.net)*.
<small>More on *[git-scm.com/book/en/v2/Getting-Started-Installing-Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)*</small>
## How to start?
**Linux (Ubuntu)** and **macOS**
Start the terminal (or any other shell)
<br>
**Windows**
Start `GUI Bash` or `MobaXTerm`.
## How to configure `git`?
```bash
$ git config --global user.name "Firstname Lastname"
$ git config --global user.email "first.last@uni.lu"
```
## Does it work?
```bash
$ git --version
# git version 2.10.0
```
## Test the configuration
Test whether your username and email have been registered
```bash
$ git config --list
```
<br>
This should list the configuration with `user.name` and `user.email`.
## How do I `clone` a repository?
You can clone a repository with
```bash
$ git clone https://github.com/userName/myRepo.git myRepo
```
<div class="fragment">
<br>
Clone the training repository with
```bash
$ git clone https://github.com/uni-lu/practice.git practice
```
<br>
You may be prompted to enter your credentials.
<div class="fragment">
<br>
Any other rudimentary method such as
*'I simply download the `.zip` un unzip it - works like a charm!'*
shall **be avoided**!
[
{
"filename": "index.md",
"attr": {
"data-background": "../img/sbgBackgroundWhite.jpg"
}
},
{
"filename": "overview.md",
"attr": {
"data-background": "../img/whiteBG.jpg"
}
},
{
"filename": "the_terminal.md",
"attr": {
"data-background": "../img/whiteBG.jpg"
}
},
{
"filename": "what_is_git.md",
"attr": {
"data-background": "../img/whiteBG.jpg"
}
},
{
"filename": "installation.md",
"attr": {
"data-background": "../img/whiteBG.jpg"
}
},
{
"filename": "essential_commands.md",
"attr": {
"data-background": "../img/whiteBG.jpg"
}
},
{
"filename": "github_gitlab.md",
"attr": {
"data-background": "../img/whiteBG.jpg"
}
},
{
"filename": "branches.md",
"attr": {
"data-background": "../img/whiteBG.jpg"
}
},
{
"filename": "best_practices.md",
"attr": {
"data-background": "../img/whiteBG.jpg"
}
},
{
"filename": "thanks.md",
"attr": {
"data-background": "../img/whiteBG.jpg"
}
}
]
## Overview
0. The Terminal
1. What is `git`? What is the use of `git`? <!--(5 min)//-->
2. GitHub and GitLab <!--(5min)//-->
3. Installation of `git`
4. The 5 essential commands <!--(10 min)//-->
* `pull` / `status` / `add` / `commit` / `push`
5. Branches <!--(10 min)//-->
7. Best practices
## Ready to practice?
<br>Go to https://github.com/uni-lu/group_members
<br>And follow the instructions in the `README` file.
### References
[1]: **Git** Book:
https://git-scm.com/book/en/v2
<br>[2]: GitHub training services: https://services.github.com/training/
### Cheat sheet
[Web](http://rogerdudler.github.io/git-guide/index.html) or [PDF](http://rogerdudler.github.io/git-guide/files/git_cheat_sheet.pdf)
## The Terminal (shell)
Starting the terminal presents itself with a line where you can enter a command
```bash
cesar@myComputer>
```