Commit 10ac20ed authored by Sylvain's avatar Sylvain
Browse files

trial

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)
* Always **sync your fork** before starting to work on a new branch
```bash
$ git remote -v # verify to have the right remote set
$ git fetch upstream
$ git merge upstream/master
$ git push origin master # do not do git push (!)
```
* `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.
## Gitlab interface
<img src="https://gitlab.com/gitlab-com/gitlab-artwork/raw/master/logo/logo.png" alt="GitLab" style="width: 100px;"/>
Detailed information is on [docs.gitlab.com/ce/gitlab-basics/add-merge-request.html](https://docs.gitlab.com/ce/gitlab-basics/add-merge-request.html).
1. Click on **New merge request**
![New Merge Request](https://docs.gitlab.com/ee/gitlab-basics/img/merge_request_new.png)
<br><br>
2. Compare the branches
![Compare branches](https://docs.gitlab.com/ee/gitlab-basics/img/merge_request_select_branch.png)
<ol start="3">
<li>Assign your peer
<br>
![Assigning a peer](https://gitlab.com/gitlab-org/gitlab-ce/uploads/6445f80f96d8cb85b320322d36d8bb0e/assigneesidebar.png)
</li>
</ol>
<ol start="4">
<li>Submit the MR
![Submit MR](https://docs.gitlab.com/ee/gitlab-basics/img/merge_request_page.png)</li>
</ol>
## 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
```
## 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`
<div class="fragment">
<br><br>
You just pushed to `master`. This is **not a good** practice (more later!).
## 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;"/>
## Open an issue (Live Demo)
## 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!
<img src="img/Git-Logo-Black.png" class="as-is" height="100px">training
<br><br>
**SBG & MSP groups**
<img src="img/logoLCSB.png" class="as-is" height="100px">
<br><br><br><br>
<br><br><br><br>
January 19th, 2017
Sylvain Arreckx & Laurent Heirendt
<br><br><br><br>
note:
(**Tuesday**: verify that everybody has a working computer with git installed)
Verify that everyone has a GitHub and a Gitlab account
**Thursday**: interactive session
˜/work/training/cobratoolbox
1. Git (on GitHub and GitLab)
Init (git-r3 / graphique)
clone, add, commit, (diff, log), push and status
branch, checkout (add commit push on a branch)
Demo that if pushed to a branch, we will have a conflict -> submit a PR to DEVELOP from own branch to avoid that
2. Github
Explain interface
Fork, update the fork
PR, issues (on a dummy test repo)
**Thursday**: Home exercise (30 min)
- Task 1a: Create a function with documentation
- Task 1b: test
- Task 2: Push to forked repo and create a PR
- Bonus Task: Fork the cobratoolbox and update
- Friday: 1h debriefing
Put your speaker notes here.
You can see them pressing 's'.
Fullscreen can be activated by typing 'f'.
## 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://git-r3lab.uni.lu/git-training/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**!
## I need `The COBRAToolbox`?
Simply `clone` the repository (i.e., retrieve a copy)
```bash
$ git clone https://github.com/opencobra/cobratoolbox.git cobratoolbox
```
<br><br>
**Do not** do it right now! Thank you.
[
{
"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": {