slides of training of april 12th

best_practices.md

+## 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.md

+## 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>

essential_commands.md

+## 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.md

+## 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_gitlab.md

+## 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.md

+## 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!

index.md

+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.md

+## 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**!
+

list.json

+[
+    {
+        "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.md

+## 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.md

+## Ready to practice?
+
+<br>Go to https://github.com/uni-lu/group_members
+
+<br>And follow the instructions in the `README` file.

thanks.md

+### 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.md

+## The Terminal (shell)
+
+Starting the terminal presents itself with a line where you can enter a command
+```bash
+cesar@myComputer>
+```
+
+<div class="fragment">
+<br>
+Often written, for covenience, as
+```bash
+$
+```
+
+<br>
+When you open your terminal (shell), you are located
+in your home directory (unless otherwise configured), denoted as `~/`.
+
+
+## Essential Linux commands
+
+List the contents of a directory
+```bash
+$ ls
+```
+
+<div class="fragment">
+<br>
+Create a directory
+```bash
+$ mkdir myNewDirectory
+```
+
+<div class="fragment">
+<br>
+Change the directory to a specific folder
+```bash
+$ cd myNewDirectory
+```
+
+
+<br>
+Change the directory 1 level and 2 levels up
+```bash
+$ cd ..
+# 1 level up
+
+$ cd ../..
+# 2 levels up
+```
+
+<div class="fragment">
+<br>
+Move a file or a directory
+```bash
+$ mv myFile.m myNewDirectory/.
+```
+
+<div class="fragment">
+<br>
+Rename a file or a directory
+```bash
+$ mv myFile.m myNewFile.m
+$ mv myNewDirectory myDirectory
+```

what_is_git.md

+## What is `git`?
+
+<!-- ![](img/git_definition.png) -->
+
+`git` is a **version control system** (VCS) for tracking changes in computer files and coordinating work on those files among multiple people [1].
+
+<br><br><br>Designed and implemented in 2005 by **Linus Torvalds**
+
+![](img/linus.jpg)
+
+<div align="left"><small>[1] *https://en.wikipedia.org/wiki/Git*</small></div>
+
+
+## Funny story
+
+![](img/git_definition.png)
+<br><br>
+```
+I'm an egotistical bastard, and I name all my projects after myself. 
+First Linux, now git.
+```
+Linus Torvald (2007-06-14)
+
+
+## What is the use of `git`?
+
+* No need to fully rewrite code; **reuse code** and **save time**
+* Keep the changes you made over time (**history**)
+* Allows you to **backtrack** (if necessary) and undo unwanted changes
+* Easily **add contributions** of your collaborators to the main code base
+
+note:
+
+Other points to mention:
+* git shall not be considered as a nuisance, but as a tool that should help to track and trace the code.
+* git is not to track performance. Not using it shows exactly the opposite.