.. image:: _static/epom.png
    :width: 200px
    :height: 200px
    :align: center
    :alt: logo

How to use git - Quick Start
============================

.. highlight:: none

.. index:: quickstart
.. index:: git

How to open a terminal
----------------------

Once logged on the `CCOM/JHC <http://ccom.unh.edu/>`_ :term:`server`, a preliminary step to use ``git`` is the opening of a terminal
(:numref:`open_terminal`).

.. _open_terminal:
.. figure:: ./_static/open_terminal.png
    :width: 600px
    :align: center
    :alt: open terminal
    :figclass: align-center

    How to open a terminal on the CCOM/JHC :term:`server`.

How to create a new local repository
------------------------------------

To create a new local ``git`` repository (:numref:`new_repo`):

* Create an empty folder with a name of your choice (e.g., ``mkdir my_repo``).
* From within the created folder (e.g., ``cd my_repo``), execute ``git init``.

.. _new_repo:
.. figure:: ./_static/new_repo.png
    :width: 600px
    :align: center
    :alt: new repo
    :figclass: align-center

    How to create a new ``git`` repository.

How to make the first commit
----------------------------

Before committing the code, you need to set name and email to identify who submitted a change:

::

    git config --global user.email "my_email@example.com"
    git config --global user.name "My Name"

Now an example of commit (:numref:`first_commit`). We first create a file (i.e., a README file) with a basic welcome message, then:

* The created file is added to the tracked files with ``git add``.
* The above change to the repository is committed with ``git commit``.

::

    echo "Welcome to my repository!" >> README.rst
    git add README.rst
    git commit -m "First commit"

.. _first_commit:
.. figure:: ./_static/first_commit.png
    :width: 600px
    :align: center
    :alt: first commit
    :figclass: align-center

    Example of first commit.

How to set and push to a remote repository
------------------------------------------

You first need to create a repository on an ``git`` hosting services such as
`GitHub <https://github.com>`_ (:numref:`github_repo`), `GitLab <https://about.gitlab.com/>`_,
and `BitBucket <https://bitbucket.org>`_.

Once that that a remote repository is created, an url similar to the following one will be available:

* ``https://github.com/hydroffice/my_repo.git``

.. _github_repo:
.. figure:: ./_static/github_repo.png
    :width: 600px
    :align: center
    :alt: github repo
    :figclass: align-center

    Example of remote repository created on GitHub.

You set the above url as the remote repository (this operation usually only happens once, at the creation time):

::

    git remote add origin https://github.com/hydroffice/my_repo.git

Then, you push to the remote repository each time that you want to remotely store your changes:

::

    git push -u origin master

You will be asked to authenticate yourself on the hosting service of your choice (:numref:`push_changes`).

.. _push_changes:
.. figure:: ./_static/push_changes.png
    :width: 600px
    :align: center
    :alt: push changes
    :figclass: align-center

    Example of how to push changes to a GitHub repository.

After that the ``push`` operation is completed, you should be able to visualize your updated code
on the hosting service (:numref:`github_repo_with_commit`).

.. _github_repo_with_commit:
.. figure:: ./_static/github_repo_with_commit.png
    :width: 600px
    :align: center
    :alt: github repo with commit
    :figclass: align-center

    Results on the GitHub repository after the ``push`` action for a first commit.


Other useful ``git`` operations
-------------------------------

* To display all the changes for both tracked and un-tracked files:

::

    git status


* To display changes only to tracked files:

::

    git diff

* To add a specific file (e.g., "Lecture0.ipynb") to the tracking for the next commit:

::

    git add Lecture0.ipynb

* To commit all local changes in tracked files (``-a``) with a message (``-m "Latest changes"``)

::

    git commit -a -m "Latest changes"

* To download all changes from a remote repository (e.g., "origin"):

::

    git pull origin

* To discard all the local changes to tracked files. **You will lose all the unpushed changes!!!**

::

    git reset -hard HEAD


Useful references
-----------------

* `git Documentation <https://git-scm.com/docs/git>`_
* `GitHub's git cheat sheet <https://services.github.com/on-demand/downloads/github-git-cheat-sheet.pdf>`_
* `Tower's git cheat sheet <https://www.git-tower.com/blog/git-cheat-sheet/>`_