.. highlight:: console

.. _Git-tut:

########################
Version Control with Git
########################

The objective of this chapter is to practice Version Control of a Modelica source code
using Git. See also links to :ref:`doc-Git` docss.

Based on http://swcarpentry.github.io/git-novice/

Slides:
:download:`ETS Git slides.pdf <./git/ETS Git slides.pdf>`,
:download:`ETS Git slides.odp <./git/ETS Git slides with fonts.odp>` (LibreOffice),

Git spatial diagram: :download:`Git_spatial_diagram.pdf <./git/Git_spatial_diagram.pdf>`


Bash survival kit
=================

The most useful commands:

* ``pwd``: Print Working Directory (answers the question "Where am I?")
* ``ls``: List folder content (option ``-a`` to see *all* the content, including hidden files/folders)
* ``cd``: Change Directory (and ``cd ..`` to go to parent)

Extras:

* ``rm``: ReMove file(s)
* ``mkdir``: MaKe (create) a DIRectory


Personal work
=============

Git commands: ``init``, ``config``, ``add``, ``commit``, ``diff``, ``log``


Publish work on GitLab
======================

You should use the GitLab instance *for teaching*
https://gitlab-student.centralesupelec.fr/.

You should *not* use those other GitLab instances:

* ⛔ https://gitlab-research.centralesupelec.fr/ (for research projects)
* ⛔ https://gitlab.centralesupelec.fr/ (older instance replaced by the teaching and research ones)

.. admonition:: Communicating with remotes: SSH versus HTTPS protocol
    :class: hint

    When cloning a repository or adding a remote, need to specify the
    URL (the "web address") of the remote using one of those two schemes:

    * SSH URL (like ``git@gitlab-student.centralesupelec.fr:user/repo.git``)
    * HTTPS URL (like ``https://gitlab-student.centralesupelec.fr/user/repo.git``)

    This chooses which *internet protocol* (SSH vs HTTPS) will be used for transfering
    commits between the local and the remote repository.
    Both choices are possible, but SSH requires some *setup work*
    (cf. doc `setup SSH for GitLab`_: first create SSH keys and then
    add the public key to GitLab), whereas HTTPS can be used *immediately*.

    So, unless you happen to be comforable with the SSH setup,
    **I recommend using HTTPS**.
    HTTPS requires inputting the login and password for each connection,
    but with Git for Windows, a *Credential Manager* is already setup
    to remember them after the first usage.


.. admonition:: Managing stored Gitlab credentials under Windows
    :class: hint

    The `Git Credential Manager for Windows`_ conveniently remembers your login & password.
    However, it also remembers wrong ones! As a consequence, you will permanently
    get authentification errors like::

        $ git pull
        remote: HTTP Basic: Access denied
        fatal: Authentication failed for 'https://gitlab-student.centralesupelec.fr/user/repo.git/'

    One solution is to dig into Windows' Control Panel to edit those credentials
    where they are stored. The steps are
    (source: `Accessing Credential Manager`_ doc for Windows 10):

    1. To open Credential Manager, type "credential manager" in the search box on the taskbar
       and select Credential Manager Control panel.
    2. Select **Windows Credentials** to access the credentials you want to manage.
       In the list you should see the GitLab URL. You can *erase* or *modify* the entry.


Collaborative work
==================

1. Ping-pong workflow: an ideal collaboration with no conflict
2. Managing conflicts


.. _setup SSH for GitLab: https://docs.gitlab.com/ee/gitlab-basics/create-your-ssh-keys.html
.. _Git protocols: https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols
.. _Git Credential Manager for Windows: https://github.com/microsoft/Git-Credential-Manager-for-Windows/blob/master/Docs/CredentialManager.md
.. _Accessing Credential Manager: https://support.microsoft.com/en-us/help/4026814/windows-accessing-credential-manager