User:Timothee Flutre/Notebook/Postdoc/2012/08/14

About Git

• Motivation: nowadays, it's pretty common to use a computer for a project in which one wants to: keep history of the changes, access them on different machines with different operating systems, share our work with someone else, etc. In such cases, it's very useful to use a distributed versioning system, such as Git.

• Start using git: first you need to download it. Then you need to read some documentation about it. And finally you can start using it. Typical cases are when developing a software or writing an article.

• Need some help: the learning curve for git is quite steep at the beginning, so it's always worth browsing help pages, reading Git Reference, and searching for questions and answers on stackoverflow.

• Writing a paper: in this example, I am writing a paper with two colleagues. We decide to do it as a centralized workflow, the shared repository being hosted by github.
  • Each of us needs to create a free account.
  • I need to upgrade my account in order to have the right to manage private repositories ($7/month).
  • I create a private repository named "paper" and add my colleagues as collaborators to it.
  • I retrieve the repository on my local machine: git clone git://github.com/timflutre/paper.git
  • I create my first file, for instance "paper_main.tex", and add it to git in my local repository: git add paper_main.tex followed by git commit -m "first commit" paper_main.tex.
  • I create one branch per collaborator (the default branch being "master"): git branch tim, then git branch colleague1 and finally git branch colleague2. I can list the local branches with git branch and I can switch to my branch with git checkout tim for instance.
  • I push the changes I made from my local repo onto github: git push origin master, this for each branch I created.
  • I send an email to my colleagues telling them that they can retrieve the content of the repository from github into their local machine(s): git clone https://github.com/timflutre/paper.git.
  • Each of us can make modifications on its own branch, and push them on github in order to allow the others to access the changes: git push origin colleague1 for instance.
  • From time to time, one of us has the responsibility to merge the changes and update the "master" branch with the latest version.
  • Once this is done, the others need to retrieve the new content of "master" in their local repo: git checkout master, git fetch origin, git diff master origin/master, git merge origin/master.
  • Then, they need to update their local branch with the new content of "master": git checkout colleague1, git diff --name-status colleague1..master. This will list the files having differences between their local branch and the new content of "master".
  • One can look at the differences file by file: git diff --color-words colleague1:paper_main.tex master:paper_main.tex. The options "--color-words" is especially useful in LaTeX.
  • To merge the content of "master" into his own branch, we do: git merge master.
  • In case of conflicts, we have to edit our own files by hand. Or we can also choose to ignore the conflicts and overwrite our local files with the content of "master" one file at a time: git checkout --patch master paper_main.tex. Even more radical, we can decide to "overwrite" our personal local branch with our local, recently-updated "master" branch (all files at once): git checkout colleague1 followed by git reset --hard master.