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

From OpenWetWare

(Difference between revisions)
Jump to: navigation, search
(About Git: put "conflicts" in a separate section)
(About Git: add tip)
(3 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''':
* '''Tips''':
** undo uncommitted changes: <code>git checkout myfile.txt</code>
** 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>
** 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 39: 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>.
 +
** 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
-
* '''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. In the following, branch1 can be master and branch2 can be origin/master, or branch1 can be tim and branch2 can be master.
+
main:
-
** The first solution is to edit the files by hand and choose which version we want to keep for each conflict.
+
latex paper_main.tex
-
** 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>.
+
bibtex paper_main
-
** 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>.
+
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 16: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