Skip to content
Snippets Groups Projects
Commit 197ae254 authored by Laurent Heirendt's avatar Laurent Heirendt :airplane:
Browse files

Merge branch 'training-jan24' into 'develop' 

Draft: Updated slides for training on Jan 24

See merge request R3school/git.slides!34
parents 632886f0 16fdcd89
No related branches found
No related tags found
2 merge requests!35Regular merge of develop,!34Draft: Updated slides for training on Jan 24
Pipeline #8460 passed
Stage: deploy
    Hide whitespace changes
    Inline Side-by-side
    Showing
    with 324 additions and 251 deletions
    slides/best_practices.md
    + 3
    − 3
    View file @ 197ae254
    ...@@ -4,11 +4,11 @@ ...@@ -4,11 +4,11 @@
    * Work on your <font color="red">own</font> branch (in your own fork), and **not** on `master` and **not** on `develop` * 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** * Do **not push** to `master` or `develop`, but **submit a PR/MR**
    * Get your code **reviewed** by your peers (submit a PR!) * Get your code **reviewed** by your peers (submit a PR/MR!)
    * Submit a PR **often**! * Submit a PR/MR **often**!
    * `clone` a repository, do not download the `.zip` file. * `clone` a repository, do not download the `.zip` file.
    ......
    slides/branches.md
    + 52
    − 72
    View file @ 197ae254
    ## Branches ## Development scheme
    Branch-off within the same repository in order to stay safe! <br>
    Generally, in a repository, there are guidelines for contributing.
    <br><br>The master branch <div class="fragment">
    <img src="img/branch-master.png" class="branch-master" />
    <br>
    A common development scheme is dual with a:
    ## One branch per feature - **development** version of the code on `develop`
    - **stable** version of the code on `master`
    Assume that you want to work on a function for a matrix-vector operation. <br>
    ```bash A **version** of the code is referred to as a **branch**.
    $ 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" /> <div class="fragment">
    <br><br>
    (Live Demo)
    Push the branch to the remote repository
    ```bash
    $ git push
    ```
    <br>
    <font color="red">In the practice repository, the development branch is called `develop`!</font>
    If you do that, `git` might complain <div class="fragment">
    ```bash <br>
    fatal: The current branch matrix_vect_mult_myName has no upstream branch. ![bulb](img/bulb.png) Use this dual development scheme for your own repositories!
    To push the current branch and set the remote as upstream, use
    git push --set-upstream origin matrix_vect_mult_myName
    ```
    ## Branches
    A **version** of the code (i.e., a **branch**) is made up of a sequence of code changes.
    <div class="fragment">
    <br> <br>
    Follow the advice and do These individual code changes are called **commits**.
    ```bash
    $ git push --set-upstream origin matrix_vect_mult_myName
    ```
    ## Switch between branches For instance, the `master` and `develop` branches can be represented as a timeline:
    <img src="img/branch-master.png" class="branch-master" />
    In your terminal, you may see the name of the branch you are on.
    List available branches of the repository ## Switch between branches
    List all branches of the repository with
    ```bash ```bash
    $ git branch --list $ git branch -a
    ``` ```
    Exit by typing `q`. The branch with the ***** is the current branch.
    <div class="fragment"> <div class="fragment">
    <br> <br>
    Checkout another branch Checkout another branch
    ```bash ```bash
    $ git checkout <branch_name> $ git checkout branchName
    ``` ```
    <div class="fragment"> <div class="fragment">
    <br> <br>
    You can switch back to the `master` branch with You can switch to the `develop` branch with
    ```bash ```bash
    $ git checkout master $ git checkout develop
    ``` ```
    (Live Demo)
    <br>
    You can use the 5 essential commands as before.
    Only difference: you are on your own branch. ## Create your own version
    <img src="img/branch-commit.png" class="branch-commit" /> Assume that you want to work on a function for adding 2 numbers.
    ## 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.
    <div class="fragment">
    <br> <br>
    Use the **interface** to make use of your peers to review your code! <font color="red">Create a new **branch**!</font>
    <img src="img/branch-merge.png" class="branch-merge" />
    <br> ```bash
    Once merged, you can delete the branch via the interface. $ git checkout -b add-2-numbers
    ```
    The `-b` flag creates the branch.
    ## Github interface Locally, you have your own version now:
    <img src="https://assets-cdn.github.com/images/modules/logos_page/GitHub-Mark.png" alt="GitHub" style="width: 100px;"/> <img src="img/branch-create.png" class="branch-create" />
    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** Push your version to your fork:
    ```bash
    $ git push origin add-2-numbers
    ```
    ![New pull request](https://help.github.com/assets/images/help/pull_requests/pull-request-start-review-button.png)
    <br><br> <br><br>
    2. Compare the branches (Live Demo)
    ![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>
    slides/cloneRepo.md 0 → 100644
    + 18
    − 0
    View file @ 197ae254
    ## How do I start working on a repository?
    You have to `clone` it first:
    ```bash
    $ git clone git@github.com:userName/myRepo.git myRepo
    ```
    <div class="fragment">
    <br>
    If you did not configure your SSH key, clone using HTTPS:
    ```bash
    $ git clone https://github.com/userName/myRepo.git myRepo
    ```
    <br>
    <div class="fragment">
    You will be prompted to enter your credentials.
    slides/configuration.md 0 → 100644
    + 53
    − 0
    View file @ 197ae254
    ## How to configure `git`?
    ```bash
    $ git config --global user.name "Firstname Lastname"
    $ git config --global user.email "first.last@uni.lu"
    ```
    ## 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`.
    ## What is an SSH key?
    An SSH key is a secure access credential.
    ## Why do I need an SSH key?
    <br>
    **Idea**: <br><br>
    communicate **securely** with Github/Gitlab **without** entering the username/password.
    ## How do I get and set my SSH key?
    <br>
    Check if you already have an SSH key:
    ```bash
    $ ls -al ~/.ssh
    ```
    <br>
    If there is a file with an extension `.pub`, you already have an SSH key.
    <div class="fragment">
    <br><br>
    If you don’t have yet an SSH key, you have to generate one:
    ```bash
    $ ssh-keygen -t rsa
    ```
    <br>
    Then, add the SSH key to Github/Gitlab (see demo).
    slides/essential_commands.md
    + 13
    − 31
    View file @ 197ae254
    ...@@ -9,62 +9,44 @@ ...@@ -9,62 +9,44 @@
    <br> <br>
    or in other words (remember these!): or in other words (remember these!):
    ```bash ```bash
    $ git pull $ git pull <remote> <branch>
    $ git status $ git status
    $ git add myFile.txt # example $ git add myFile.txt # example
    $ git commit -m "myMessage" # example $ git commit -m "myMessage" # example
    $ git push $ git push <remote> <branch>
    ``` ```
    ## Pull the latest version of an existing repository ## Pull the latest version of an existing repository
    First, browse to the cloned directory (`git clone [...]`):
    ```bash
    $ cd practice
    ```
    Then, pull the latest revision: Then, pull the latest revision:
    ```bash ```bash
    $ git pull $ git pull origin add-2-numbers
    # Already up to date # Already up to date
    ``` ```
    <div class="fragment">
    <br>
    Verify its `status` with: Verify its `status` with:
    ```bash ```bash
    $ git status $ 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 a file
    Modify and rename `addTwoNumbers.m` in the folder `firstCommit` Modify and rename `addTwoNumbers.m` in the folder `src/firstCommit` as `addTwoNumbers_myName`:
    <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> ```bash
    Uncomment the line $ cd src/firstCommit
    ```Matlab $ mv addTwoNumbers.m addTwoNumbers_myName.m
    % c = a + b
    ``` ```
    <br> <br>
    Save and rename the file by <font color="red">adding your name</font> Open the file using the `Visual Studio Code` editor (or any other editor)
    ```bash and correct the line
    $ mv firstCommit/addTwoNumbers.m firstCommit/addTwoNumbers_myName.m ```Matlab
    c = a + b;
    ``` ```
    ......
    slides/forks.md
    + 52
    − 53
    View file @ 197ae254
    ## Forks
    You **fork** when you want to work on a public repository or a protected repository. ## What is a `fork`?
    <br><br> <div class="fragment">
    Remember: <img src="img/fork.jpg" class="as-is" />
    [//]: <> (http://www.cndajin.com/data/wls/246/22302193.jpg)
    ## Not really ...
    <img src="img/fork-crossed.png" class="as-is" />
    ## What is a `fork`?
    In general, when contributing to a repository, you only have **read** access.
    <div class="fragment">
    In other words, you can only **pull** (unless it is your own repository or access has been granted).
    <div class="fragment">
    <br>
    In general, you **cannot write** changes. In other words, you do not have **push** access.
    - A **fork** is your own **copy** of a repository. <div class="fragment">
    - A **fork** can have multiple **branches**. You have to work on your **own copy**.
    - A **fork** is not a **branch**, but can have multiple **branches**.
    <br><br> <div class="fragment">
    A **fork** is only useful when you want to contribute, e.g., to The COBRAToolbox. <br>
    In other words, you have to work on your own <font color="red">**fork**</font>.
    ## Fork via interface ## How to get a fork?
    Browse to the original repository and click on the button `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) ![Fork the repo](https://help.github.com/assets/images/help/repository/fork_button.jpg)
    (Live Demo)
    ## Clone your fork
    Clone first ## Time to practice!
    ```bash
    $ git clone https://git-r3lab.uni.lu/myGroup/myRepo.git forkMyRepo (Live Demo)
    ```
    <br> <br>
    then, you can change to the directory
    ```bash
    $ cd forkMyRepo
    ```
    Fork the practice repository: <br><br>
    https://git-r3lab.uni.lu/R3school/git.practice
    ## Add the address of the original repository Then, clone your fork to your home directory!
    Add the `upstream` address (original/protected repository) <div class="fragment">
    <br>
    ```bash ```bash
    $ git remote add upstream https://git-r3lab.uni.lu/origGroup/origRepo.git $ git clone ssh://git@git-r3lab-server.uni.lu:8022/yourUserName/
    git.practice.git practice
    ``` ```
    <br> <br>
    You can then check whether the remote address is set correctly Change to the practice directory with:
    ```bash ```bash
    $ git remote -v $ cd practice
    ``` ```
    <!-- <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 <font color="red">
    Any other rudimentary method such as
    ```bash *'I simply download the `.zip` and unzip it - works like a charm!'*
    $ git checkout master
    $ git status
    ```
    <div class="fragment"> shall **be avoided**!
    <br> </font>
    Fetch the changes from upstream (similar to pull)
    ```bash
    $ git fetch upstream
    ```
    <div class="fragment"> <div class="fragment">
    <br> <br>Why?
    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
    ```
    ## How to update my fork?
    As you have your own fork, it will not automatically update once the original repository is update.
    ## Pull/Merge Requests ![bulb](img/bulb.png) You have to update it yourself!
    **Good news!** <div class="fragment">
    <br>
    **More on that later!**
    Same procedure as with merging a branch...
    slides/img/branch-create.png
    + 0
    − 0
    View replaced file @ 632886f0 View file @ 197ae254
    slides/img/branch-create.png

    56.2 KiB | W: | H:

    slides/img/branch-create.png

    108 KiB | W: | H:

    slides/img/branch-create.png
    slides/img/branch-create.png
    slides/img/branch-create.png
    slides/img/branch-create.png
    • 2-up
    • Swipe
    • Onion skin
    slides/img/branch-i-state.graffle
    + 0
    − 0
    View file @ 197ae254
    No preview for this file type
    slides/img/branch-master.png
    + 0
    − 0
    View replaced file @ 632886f0 View file @ 197ae254
    slides/img/branch-master.png

    65.4 KiB | W: | H:

    slides/img/branch-master.png

    92.3 KiB | W: | H:

    slides/img/branch-master.png
    slides/img/branch-master.png
    slides/img/branch-master.png
    slides/img/branch-master.png
    • 2-up
    • Swipe
    • Onion skin
    slides/img/bulb.png 0 → 100644
    + 0
    − 0
    View file @ 197ae254
    slides/img/bulb.png

    4.72 KiB

    slides/img/fork-crossed.png 0 → 100644
    + 0
    − 0
    View file @ 197ae254
    slides/img/fork-crossed.png

    1.71 MiB

    slides/img/fork.graffle/data.plist 0 → 100644
    + 0
    − 0
    View file @ 197ae254
    File added
    slides/img/fork.graffle/image1.tiff 0 → 100644
    + 0
    − 0
    View file @ 197ae254
    slides/img/fork.graffle/image1.tiff

    1.75 MiB

    slides/img/fork.graffle/image2.tiff 0 → 100644
    + 0
    − 0
    View file @ 197ae254
    slides/img/fork.graffle/image2.tiff

    257 KiB

    slides/img/fork.jpg 0 → 100644
    + 0
    − 0
    View file @ 197ae254
    slides/img/fork.jpg

    35.2 KiB

    slides/installation.md
    + 11
    − 85
    View file @ 197ae254
    ## Installation ## Installation of `git`
    <img src="img/github_app.png" class="as-is" height="200" /> <img src="img/github_app.png" class="as-is" height="200" />
    **Linux (Ubuntu)**
    ```bash
    $ sudo apt-get install git-all
    ```
    <br>
    **macOS** **macOS**
    Install *Xcode Command Line Tools* Install *Xcode Command Line Tools*
    ...@@ -17,8 +11,15 @@ Install *Xcode Command Line Tools* ...@@ -17,8 +11,15 @@ Install *Xcode Command Line Tools*
    Install Git Bash: <br>`https://git-scm.com/download/win` Install Git Bash: <br>`https://git-scm.com/download/win`
    <br>
    **Linux (Ubuntu)**
    ```bash
    $ sudo apt-get install git-all
    ```
    ## How to start?
    ## How to get started?
    **Linux (Ubuntu)** and **macOS** **Linux (Ubuntu)** and **macOS**
    ...@@ -30,84 +31,9 @@ Start the `Terminal` or `iTerm`. ...@@ -30,84 +31,9 @@ Start the `Terminal` or `iTerm`.
    Start `GUI Bash`. Start `GUI Bash`.
    ## How to configure `git`? ## Is `git` properly installed?
    ```bash
    $ git config --global user.name "Firstname Lastname"
    $ git config --global user.email "first.last@uni.lu"
    ```
    ## Does it work?
    ```bash ```bash
    $ git --version $ git --version
    # git version 2.10.0 # git version 2.10.0
    ``` ```
    \ No newline at end of file
    ## 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 to set my SSH key?
    Check if you already have an SSH key:
    ```bash
    $ ls -al ~/.ssh
    ```
    If there is a file with an extension `.pub`, you already have an SSH key.
    <div class="fragment">
    <br><br>
    If you don’t have yet an SSH key, you have to generate one:
    ```bash
    $ ssh-keygen -t rsa
    ```
    <br>
    Then, add the SSH key to Github/Gitlab (see demo).
    ## How do I `clone` a repository?
    You can clone a repository with
    ```bash
    $ git clone git@github.com:userName/myRepo.git myRepo
    ```
    <br>
    If you did not configure your SSH key, clone using HTTPS:
    ```bash
    $ git clone https://github.com/userName/myRepo.git myRepo
    ```
    <br>
    You may be prompted to enter your credentials.
    ## Clone the practice repository
    (Live Demo)
    <br>
    Clone the training repository! <br><br>
    https://git-r3lab.uni.lu/R3.training/git.practice
    <div class="fragment">
    <br><br>
    Any other rudimentary method such as
    *'I simply download the `.zip` un unzip it - works like a charm!'*
    shall **be avoided**!
    slides/list.json
    + 32
    − 2
    View file @ 197ae254
    ...@@ -29,6 +29,12 @@ ...@@ -29,6 +29,12 @@
    "data-background": "img/whiteBG.jpg" "data-background": "img/whiteBG.jpg"
    } }
    }, },
    {
    "filename": "installation.md",
    "attr": {
    "data-background": "img/whiteBG.jpg"
    }
    },
    { {
    "filename": "github_gitlab.md", "filename": "github_gitlab.md",
    "attr": { "attr": {
    ...@@ -36,13 +42,19 @@ ...@@ -36,13 +42,19 @@
    } }
    }, },
    { {
    "filename": "installation.md", "filename": "configuration.md",
    "attr": { "attr": {
    "data-background": "img/whiteBG.jpg" "data-background": "img/whiteBG.jpg"
    } }
    }, },
    { {
    "filename": "essential_commands.md", "filename": "cloneRepo.md",
    "attr": {
    "data-background": "img/whiteBG.jpg"
    }
    },
    {
    "filename": "forks.md",
    "attr": { "attr": {
    "data-background": "img/whiteBG.jpg" "data-background": "img/whiteBG.jpg"
    } }
    ...@@ -53,6 +65,24 @@ ...@@ -53,6 +65,24 @@
    "data-background": "img/whiteBG.jpg" "data-background": "img/whiteBG.jpg"
    } }
    }, },
    {
    "filename": "essential_commands.md",
    "attr": {
    "data-background": "img/whiteBG.jpg"
    }
    },
    {
    "filename": "merge.md",
    "attr": {
    "data-background": "img/whiteBG.jpg"
    }
    },
    {
    "filename": "syncFork.md",
    "attr": {
    "data-background": "img/whiteBG.jpg"
    }
    },
    { {
    "filename": "best_practices.md", "filename": "best_practices.md",
    "attr": { "attr": {
    ......
    slides/merge.md 0 → 100644
    + 43
    − 0
    View file @ 197ae254
    ## 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>
    slides/ready.md deleted 100644 → 0
    + 0
    − 5
    View file @ 632886f0
    ## Ready to practice?
    <br>Go to https://git-r3lab.uni.lu/R3.training/git.practice
    <br>And follow the instructions in the `README` file.
    slides/syncFork.md 0 → 100644
    + 47
    − 0
    View file @ 197ae254
    ## Synchronize your fork
    ![bulb](img/bulb.png) Remember, we have to regularly update our own copy of the code.
    ## Add the address of the original repository
    Add the `upstream` address (original/protected repository)
    ```bash
    $ git remote add upstream ssh://git@git-r3lab-server.uni.lu:8022/R3school/
    git.practice.git
    ```
    ![bulb](img/bulb.png) Note the change in the URL.
    <br>
    You can then check whether the remote address is set correctly
    ```bash
    $ git remote -v
    ```
    <div class="fragment">
    <br>
    Fetch the changes from upstream (similar to pull)
    ```bash
    $ git fetch upstream
    ```
    <div class="fragment">
    <br>
    Merge the retrieved changes on the `master` branch:
    ```bash
    $ git checkout master
    $ git merge upstream/master
    $ git push origin master
    ```
    <div class="fragment">
    <br>
    Do the same for the `develop` branch<br>
    (replace `master` with `develop`).
    ## Time to practice!
    (Live Demo)
    \ No newline at end of file
    0% or .
    You are about to add 0 people to the discussion. Proceed with caution.
    Finish editing this message first!
    Please register or to comment