.. !split
Motivation
==========
Greg Wilson's excellent `Script for Introduction to Version Control `__ provides a detailed motivation why you will benefit greatly
from using version control systems. Here follows a shorter motivation
and a quick overview of the basic concepts.
Why not Dropbox or Google Drive?
--------------------------------
The simplest services for hosting project files are `Dropbox `__ and `Google Drive `__.
It is very easy to get started with these systems, and they allow you
to share files among laptops and mobile units with as many users as
you want. The systems offer a kind of version control in that the
files are stored frequently (several times per minute), and you can go
back to previous versions for the last 30 days. However, it is
challenging to find the right version from the past when there are
so many of them and when the different versions are not annotated with
sensible comments. Another deficiency of Dropbox and Google Drive is
that they sync all your files in a folder, a feature you clearly do not
want if there are many large files (simulation data, visualizations,
movies, binaries from compilations,
temporary scratch files, automatically generated copies)
that can easily be regenerated.
However, the most serious problem with Dropbox and Google Drive arises
when several people edit files simultaneously: it can be difficult
detect who did what when, roll back to previous versions, and to
manually merge the edits when these are incompatible. Then one needs
more sophisticated tools, which means a *true version control system*.
The following text aims at providing you with the minimum information
to started with Git, the leading version control system, combined
with project hosting services for file storage.
Project hosting services
------------------------
Through the last decade, several popular project hosting sites
appeared: `Sourceforge `__,
`Google code `__,
`Launchpad `__,
`Bitbucket `__, and
`GitHub `__.
Today, the latter two stand out as the most successful,
and we therefore concentrate on them in this quick intro.
Both services have
excellent introductions available at their web sites, but the recipes
below are much shorter and aim at getting you started as quickly as
possible by concentrating on the most important need-to-know steps.
After the recipes on how to be up and going with project hosting
services, there is an introduction to Git. One can find
a lot of Git tutorials on the web so you might ask why
yet another one. Traditionally, Git introductions have been quite
technical, aimed at professional programmers.
The material on Git in this document grew out my need to provide
students in course with *minimal* information on how they can
archive and hand in all their computer-based course work in Git.
The coming text therefore gets you up and going very fast.
More advanced features of Git (branching, stashing, forking, merging),
which enhances the reliability of your work,
are introduced subsequently, but are not required for beginners.
Thereafter, your Git background should be firm enough to
easily access the many references I provide to material on the web.
Repositories and local copies
-----------------------------
The mentioned services host all your files in a specific project in what
is known as a *repository*, or *repo* for short. When a copy of the
files are wanted on a certain computer, one clones the repository on
that computer. This creates a local copy of the files. Now files can
be edited, new ones can be added, and files can be deleted. These
changes are then brought back to the repository. If users at
different computers synchronize their files frequently with the
repository, most modern version control systems will be able to merge
changes in files that have been edited simultaneously on different
computers. This is perhaps one of the most useful features of project
hosting services. However, the merge functionality clearly works best
for pure text files and less well for binary files, such as PDF files,
MS Word or Excel documents, and OpenOffice documents.
What to choose?
---------------
It might seem challenging to pick the project hosting service
and the version control system that are right for you. Below
is some very personal advice.
* I would recommend Git as the default choice of version control system.
It is simply superior in many aspects, but for a beginner the superior
merge functionality is most useful.
* If you need private repos and you are not a student, choose
Bitbucket unless you are willing to pay for private repos at GitHub.
* If you want to make links to your programs in documentation,
stay away from Bitbucket as this site embeds the version of the
file into its URL (but you can get around this problem with a trick
described in the section :ref:`bitgit:bitbucket:URLs`).
* If a few collaborate on a project and everyone wants to be notified
in email about changes in project files, the procedure on
Bitbucket is easier to use than the one on GitHub.
For the examples below, assume that you have some directory tree
``my-project`` with files that you want to host at Bitbucket or GitHub
and bring under version control. The official name of the
project is "My Project".
Installing Git
--------------
.. index:: git
The installation of Git on various systems is described on the `Git
website `__ under the *Download* section. Git
involves compiled code so it is most convenient to download a
precompiled binary version of the software on Windows, Mac and other
Linux computers. On Ubuntu or any Debian-based system the relevant
installation command is
.. code-block:: text
Terminal> sudo apt-get install git gitk git-doc
This tutorial explains Git interaction through command-line applications
in a terminal window. There are numerous `graphical user interfaces to
Git `__. Three examples are
`git-cola `__,
`TortoiseGit `__, and
`SourceTree `__.
.. _bitgit:git:config:
Configuring Git
---------------
Make a file ``.gitconfig`` in your home directory with information on
your full name, email address, your favorite text editor, and
the name of an "excludes file" which defines the file types that Git
should omit when bringing new directories under version control.
Here is a simplified version of the author's ``.gitconfig`` file:
.. code-block:: text
[user]
name = Hans Petter Langtangen
email = hpl@simula.no
editor = emacs
[core]
excludesfile = ~/.gitignore
The ``excludesfile`` variable is important: it points to a
file called ``.gitignore``, which must list,
using the Unix Shell Wildcard notation,
the type of files that you do not need to have under version control,
because they represent garbage or temporary information,
or they can easily be regenerated from
some other source files. A suggested `.gitignore `__ file looks like
.. code-block:: text
# compiled files:
*.o
*.so
*.a
# temporary files:
*.bak
*.swp
*~
.*~
*.old
tmp*
.tmp*
temp*
.#*
\#*
# tex files:
*.log
*.dvi
*.aux
*.blg
*.idx
*.nav
*.out
*.toc
*.snm
*.vrb
*.bbl
*.ilg
*.ind
*.loe
# eclipse files:
*.cproject
*.project
# misc:
.DS_Store
.. admonition:: Carefully judge what files to bring under version control
You should be critical to what kind of files you really need a full
history of. For example, you do not want to populate the repository
with big graphics files of the type that can easily be regenerated by
some program. The suggested ``.gitignore`` file above lists typical
files that are not needed (usually because they are automatically
generated by some program).
In addition to a default ``.gitignore`` file in your home directory, it
may be wise to have a ``.gitignore`` file tailored your repo in the
root directory of the repo.
Large data files, even when you want to version them, fill up your
repo and should be taken care of through the special service
`Git Large File Storage `__.