- 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.
- Documentation: first you can give it a try online! If you like, you can freely download it, and read more documentation. Typical use cases are when developing a software or writing an article (or even a book!). Also have a look at Karl Broman's tutorial. As the learning curve for git is quite steep at the beginning, it's always worth browsing help pages, reading Git Reference, and searching for questions and answers on stackoverflow.
- Conflicts: when updating one branch with the content of another one (
git checkout branch1; git merge branch2), some conflicts can happen, and it is usually hard to know how to solve them properly (but see a concrete example here). In the following, branch1 can be master and branch2 can be origin/master, or branch1 can be master and branch2 can be dev.
- The first solution is to edit each conflicted files by hand, then run
git add fileX.txt (staging indicates to git that the conflict is resolved) and finally run
git commit -m "merge branch2 and solve conflicts" fileX.txt.
- The second solution is to ignore the conflicts and overwrite the files of branch1 with the content of branch2, one file at a time:
git checkout --patch branch2 fileX.txt.
- The third solution, even more radical, is to "overwrite" all of branch1 with the content of the branch2, all files at once:
git reset --hard branch2.
- undo uncommitted changes:
git checkout myfile.txt
- split a big commit in several smaller commits:
git add -p myfile.txt
- usual config:
git config --global user.name 'Timothée Flutre'; git config --global user.email 'firstname.lastname@example.org'; git config --global core.editor emacs; git config --global i18n.commitEncoding 'utf8'; git config --global i18n.logOutputEncoding 'utf8'
- remote via ssh tunnel: first open the tunnel
ssh gateway.foo.bar -l tflutre -Nf -L 20400:maincluster:22, then add the remote
git remote add mcl ssh://tflutre@localhost:20400/home/tflutre/myproject/.git
- 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.
- Setting up the infrastructure:
- 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.
- Typical working cycle:
- 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 the recently-updated local "master" into his own local branch, we do:
git merge master.
- Tips: don't version the output pdf in the repository because, as it is binary, git can't merge it properly. But you can add a Makefile (see below) and, by entering
make main -i on the command-line, it will compile your pdf document when you need it
all: main supp
rm -f *~ *.aux *.dvi *.log *.pdf *.bbl *.blg *.toc
- Two remotes: let's imagine that on cluster1 I have 2 branches, "master" and "dev", on github I only have "master", and I want to work with "dev" on cluster2.
- first I log on cluster2 and I clone the repo from github:
git clone https://github.com/timflutre/myproject.git
- then I add my repo from cluster1 as a remote:
cd myproject/; git remote add cluster1 ssh://tflutre@cluster1:/home/tflutre/myproject/.git
- finally I fetch the remotes and create a "dev" branch which tracks the one on cluster1:
git remote update; git checkout -b dev cluster1/dev