.. !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. 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. 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 `__.