.. _git:
Git crash course
================
.. important::
Remember that git is optionnal in this project. It is perfectly OK
to not use git and use another approach if you ever need to
synchronize your files.
Git is a wonderful tool to share some text between several computers,
while keeping track of the history of changes. This is incredibly
useful when working as a team on a programming project: when one team
member modifies a file (to add a feature), it clearly documents the
change. They then pushes these changes on a shared project, from which
others can get these change. They do so by synchronizing their local
version with the shared project.
In the git parlance, each teamate has a **local repository**, a
given change is a **commit** (some modifications to the files + a description of
these changes), while synchronizations can be either **push** or **pull**,
depending whether you send local changes to a remote repository or get
remote commits to your local repository.
.. image:: images/git-repo.png
:align: center
:scale: 50 %
Git is so useful that I routinely use it on projects where I'm the
only programmer. Even if I don't have to synchronize with remote
computers, I like the ability to build my software incrementally by
adding one commit after another. When things go wrong, I can go back
to a previous working commit, just like you go back to the previous
checkpoint when you lose in a video game.
This page only shows the minimal commands that you need. It does not
show the full power of git, but hopefully will help you getting
started with git.
Configuring your account on GitLab
----------------------------------
A single configuration is mandatory to use our academic hosting system
(`ISTIC gitlab `_) from your
computer. First log into our `this system
`_ using your academic
credentials. Go to your preference (click on the round icon on the
very top right corner), then "SSH keys" on the left and follow the
instructions to generate a key on your computer (don't use a
passphrase). Once generated, copy/paste the content of the public part
of your key to the GitLab preference box.
Getting your copy of the retrogames
-----------------------------------
You are not allowed to modify the `template available online
`_,
so you first need to dupplicate it on ISTIC's gitlab, and then you
need to get a local copy on your disk. In the git parlance, you need
to **fork** my repository on gitlab, and then **clone** your fork onto
your local computer.
.. image:: images/git-forkclone.png
:align: center
:scale: 50 %
The difference between **clone** and **pull** is that clone is
creating a local repository after a remote one while pull is only
copying commits between compatible repositories.
In practice, go to the `project you want to fork
`_,
clic on the "fork" button to the right of the project name and follow
the instructions to make a private project.
Once you have your own fork, clic on the big blue "Clone" button and
select the ssh URL. Then, the following in a terminal:
.. code:: shell
git clone #the URL of your project# retrogames
If your name is GIZMODO, you will probably type the following:
.. code:: shell
git clone git@gitlab.istic.univ-rennes1.fr:GIZMODO/template-retrogames.git retrogames
If you want to share your work with a teamate (once you have a
teamate), add this person as a project member on GitLab (they will get
a mail to confirm). After clicking on the received link to confirm,
they can clone your repository just as you did above.
Editing a file
--------------
Edit the file README.md on your local copy to add your name on top.
Verify the change you did by typing ``git diff``. This lists all
changes, line by line. In this output, lines starting with a ``-`` are
removed by the change while lines starting with a ``+`` were added.
For example, the following output simply means that I changed the
first line of the file, changing ``Retrogames template files`` into
``Retrogame, by me``. The other lines (starting with a space) are
unchanged by this edition. You can safely ignore the lines on top.
.. code:: diff
$ git diff
diff --git a/README.md b/README.md
index 5dcb136..dcf375f 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Retrogames template files
+# Retrogame, by me
This is the student's starter kit for the Retrogaming project (https://mquinson.frama.io/retrogames).
It contains all you need to start working on your project.
Creating a commit
-----------------
To send this change to your project, you first need to create a commit
with the following command.
.. code:: shell
git commit -m "Add my name" README.md
Here, ``git commit`` is what you want to do (create a git commit),
``-m "Add my name"`` documents the commit (ie, the string `Add my
name` will be used as a documentation to the change introduced, and
finally ``README.md`` asks git to only consider the changes of that
file.
Typing ``git diff`` again yields no output, because there is no file
edition that is not already commited to your repository.
Git will refuse to commit changes to files it does not track, so you
need to **add new files** before you can commit them.
.. code:: shell
# create mygame.py on disk
git commit -m "something" mygame.py # This is an error
git add mygame.py # now git knows about this file
git commit -m "something" mygame.py # OK
Synchronizing your repository
-----------------------------
Once you've created a commit, you need to explicitly send it to the
GitLab project as follows:
.. code:: shell
git push
Your colleagues (if any) need to explicitly pull this commit from the
GitLab project as follows:
.. code:: shell
git pull
Going further
-------------
There is much (much) more to say about git and gitlab, but you now
have the basics to get things done. Congratuations!
But don't get fooled. Git is a powerful (and often tricky) tool.
You will find many tutorials on the internet. `The one from Atlassian
`_ is
very good and very complete. Thomas Genet (our colleague at Rennes)
provide `a very good one in French `_ (`associated
video `_).
There is even `a little game `_
that you can play in your browser to learn to use git.