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

From OpenWetWare

(Difference between revisions)
Jump to: navigation, search
(About Git: improve readability)
(About Git: add tip)
(6 intermediate revisions not shown.)
Line 15: Line 15:
* '''Need some help''': the learning curve for git is quite steep at the beginning, so it's always worth browsing [https://help.github.com/ help pages], reading [http://gitref.org/ Git Reference], and searching for questions and answers on [http://stackoverflow.com/ stackoverflow].
* '''Need some help''': the learning curve for git is quite steep at the beginning, so it's always worth browsing [https://help.github.com/ help pages], reading [http://gitref.org/ Git Reference], and searching for questions and answers on [http://stackoverflow.com/ stackoverflow].
 +
 +
 +
* '''Conflicts''': when updating one branch with the content of another one (<code>git checkout branch1; git merge branch2</code>), some conflicts can happen, and it is usually hard to know how to solve them properly (but see a concrete example [http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging 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 <code>git add fileX.txt</code> (staging indicates to git that the conflict is resolved) and finally run <code>git commit -m "merge branch2 and solve conflicts" fileX.txt</code>.
 +
** The second solution is to ignore the conflicts and overwrite the files of branch1 with the content of branch2, one file at a time: <code>git checkout --patch branch2 fileX.txt</code>.
 +
** The third solution, even more radical, is to "overwrite" all of branch1 with the content of the branch2, all files at once: <code>git reset --hard branch2</code>.
 +
 +
 +
* '''Tips''':
 +
** undo uncommitted changes: <code>git checkout myfile.txt</code>
 +
** split a big commit in several smaller commits: <code>git add -p myfile.txt</code>
 +
** usual config: <code>git config --global user.name 'Timothée Flutre'; git config --global user.email 'timflutre@gmail.com'; git config --global i18n.commitEncoding 'utf8'; git config --global i18n.logOutputEncoding 'utf8'</code>
Line 34: Line 46:
*** One can look at the differences file by file: <code>git diff --color-words colleague1:paper_main.tex master:paper_main.tex</code>. The options "--color-words" is especially useful in LaTeX.
*** One can look at the differences file by file: <code>git diff --color-words colleague1:paper_main.tex master:paper_main.tex</code>. 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: <code>git merge master</code>.
*** To merge the content of the recently-updated local "master" into his own local branch, we do: <code>git merge master</code>.
-
*** 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: <code>git checkout --patch master paper_main.tex</code>. Even more radical, we can decide to "overwrite" our personal local branch with our local, recently-updated "master" branch (all files at once): <code>git checkout colleague1</code> followed by <code>git reset --hard master</code>.
+
** 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 <code>make main -i</code> on the command-line, it will compile your pdf document when you need it
 +
 
 +
<nowiki>
 +
all: main supp
 +
 
 +
main:
 +
latex paper_main.tex
 +
bibtex paper_main
 +
latex paper_main.tex
 +
latex paper_main.tex
 +
pdflatex paper_main
 +
 
 +
supp:
 +
latex paper_supplements.tex
 +
bibtex paper_supplements
 +
latex paper_supplements.tex
 +
latex paper_supplements.tex
 +
pdflatex paper_supplements
 +
 
 +
clean:
 +
rm -f *~ *.aux *.dvi *.log *.pdf *.bbl *.blg *.toc
 +
</nowiki>
<!-- ##### DO NOT edit below this line unless you know what you are doing. ##### -->
<!-- ##### DO NOT edit below this line unless you know what you are doing. ##### -->

Revision as of 17:26, 5 March 2013

Project name Main project page
Previous entry      Next entry

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.


  • 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.


  • Tips:
    • 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 'timflutre@gmail.com'; git config --global i18n.commitEncoding 'utf8'; git config --global i18n.logOutputEncoding 'utf8'


  • 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

main:
	latex paper_main.tex
	bibtex paper_main
	latex paper_main.tex
	latex paper_main.tex
	pdflatex paper_main

supp:
	latex paper_supplements.tex
	bibtex paper_supplements
	latex paper_supplements.tex
	latex paper_supplements.tex
	pdflatex paper_supplements

clean:
	rm -f *~ *.aux *.dvi *.log *.pdf *.bbl *.blg *.toc


Personal tools